Starter Files

Updated April 9, 2026

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.

  • Gems & Shards — Creating new gems and the New Gem panel
  • MCP Servers — .mcp.json format and server catalog
  • Facet Inserts — Reusable prompts and commands (templates for input, not files)