# Starter Files

> Reusable project templates for CLAUDE.md, AGENTS.md, .mcp.json, and any other file you want to seed new gems with.

Starter files are reusable templates Crystl can write into a project directory when you create a new gem — or drop into an existing gem on demand. They're how you standardize project setup: every new repo gets the same `CLAUDE.md`, the same `AGENTS.md`, the same base `.mcp.json`, without copy-pasting between directories.

## What They Are

A **starter file** is a named template with a target filename and a content body. Anything you'd otherwise hand-write into a fresh project is a good candidate:

- `CLAUDE.md` — instructions and conventions for Claude Code
- `AGENTS.md` — shared agent guidelines
- `.mcp.json` — MCP server declarations
- `.gitignore`, `.editorconfig`, `README.md`, license headers, issue templates — anything text-based

Starters live in a central list you manage from settings, and Crystl offers them every time you create a new gem.

## Managing Templates

Open **Settings → File Library** and select the **Templates** tab. The tab lists every template you currently have, with controls to create, edit, reorder, and delete them.

Each template has four fields:

- **Name** — the display label shown in the New Gem panel and the settings list (e.g. "Backend CLAUDE.md", "Default AGENTS.md")
- **Filename** — the path the template will be written to, relative to the project root (e.g. `CLAUDE.md`, `.claude/commands/review.md`)
- **Content** — the body of the file
- **Order** — where the template sits in the list; lower numbers appear first

Click a template to open the editor, edit the content in place, and save. The list is stored at `~/.config/crystl/starters.json` and picks up changes immediately — new gems created after a save will see the updated template.

## Applying Starters to New Gems

When you create a gem through the **New Gem** panel (from the Crystal Rail "+" or the "Gem Settings" button), the panel shows a **Starter Files** section with a checkbox for each template in your list.

- Check the starters you want written into the new project
- Crystl creates the files alongside `.crystl/project.json` when the gem is created
- **Existing files are skipped** — if the target path already has a file, Crystl never overwrites it. This makes starters safe to enable by default on existing projects you're adopting into Crystl.

Starters run after the directory is created and before the first shard opens, so the project's first terminal session already sees them on disk.

## Bundled Defaults

Crystl ships with a small set of default templates you can use out of the box — baseline `CLAUDE.md` and `AGENTS.md` files that give Claude enough project-level context to be useful without any customization. They're just regular starter entries, so you can edit them, duplicate them, or delete them like any other template.

## Per-Project Overrides

For templates that only make sense inside a specific gem, you can store project-local starters in the gem's `.crystl/` folder. These show up alongside the global list when you're working inside that gem and are useful for:

- Repo-specific `CLAUDE.md` variants (e.g. "frontend mode" vs "backend mode")
- Team templates that shouldn't leak into unrelated projects
- Experimental starters you're drafting before promoting to the global list

Project-local starters travel with the gem, so if you sync the `.crystl/` folder across machines the same templates show up everywhere.

## Use Cases

**Standardize team setup.** Define a `CLAUDE.md` once with your team's coding conventions, review rules, and architectural notes. Every new project gets the same instructions without anyone having to remember.

**Seed Claude with your preferences.** Keep a personal `CLAUDE.md` starter with your preferred style (e.g. "prefer small functions, never use emojis, always add unit tests") so every new gem starts from the same baseline.

**Bootstrap MCP servers.** Ship a default `.mcp.json` with your common servers (filesystem, GitHub, search) so new projects can use MCP tools immediately. Crystl merges with any existing `.mcp.json` rather than overwriting.

**Share project templates across a team.** Commit your starter JSON to a dotfiles repo and symlink `~/.config/crystl/starters.json` — every teammate gets the same templates.

## Related Docs

- [Gems & Shards](/docs/gems-and-shards) — Creating new gems and the New Gem panel
- [MCP Servers](/docs/mcp-servers) — `.mcp.json` format and server catalog
- [Facet Inserts](/docs/facet-inserts) — Reusable prompts and commands (templates for input, not files)

---
Source: https://crystl.dev/docs/starter-files/