# 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 → library**, and crystl offers them every time you create a new gem.

## Managing templates

Open **Settings → library**. Two of its four tabs cover starters:

- **starter kits** are bundles: a whole setup (an agent file plus its rules and skills) installed into a project in one go. crystl ships a universal **Coding Project** kit and you can build your own with **"+ new kit"**.
- **files** are single-file templates: one CLAUDE.md, one AGENTS.md, one codex.md. **"+ new file"** opens a blank one.

Click any of them to open the block editor, edit in place, and save. The list lives at `~/.config/crystl/file-library.json` and picks up changes immediately, so new gems created after a save see the updated version.

A template writes to its file type's usual name (`CLAUDE.md` for a CLAUDE.md template) unless you give it a custom filename, which is how you target a path like `docs/setup.md` or `.claude/commands/review.md`.

## Applying starters to new gems

When you create a gem through the **New Gem** panel (the "+" at the bottom of the crystal rail), pick a kit under **INCLUDE STARTER BUNDLE**. crystl writes its files alongside `.crystl/project.json` as the gem is created, after the directory exists and before the first shard opens, so the project's first terminal session already sees them on disk.

**Existing files are never overwritten.** If the target path already has a file, crystl skips it. That makes starters safe on an existing project you're adopting into crystl.

## Bundled defaults

crystl ships with a baseline **Coding Project** kit you can use out of the box: enough project-level context for an agent to be useful without any customization. Build your own kit alongside it when your projects want a different baseline.

## 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 library JSON to a dotfiles repo and symlink `~/.config/crystl/file-library.json`, and every teammate gets the same kits and 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/