Starter Files

Updated July 31, 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 → 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.