Starter Files

Updated September 18, 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, context, and crystl offers them every time you create a new gem.

Managing templates

Open settings, context. Two of its five tabs cover starters:

  • starter kits are bundles: a whole setup (an agent file plus its sections, rules, skills and starter files) installed into a project in one go. crystl ships one kit per kind of project 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.

The kits crystl ships

The shelf you are offered is filtered by the gem’s type, so a Records gem sees the Records kit rather than a list of code stacks.

One code kit, and stack flavour from the catalog

Code and General gems are offered Coding Project, a universal kit. It is universal on purpose: a coder already knows their own stack, and being handed a Prisma heading nobody asked for is friction rather than help. What ships in the app has to be useful to any coding project.

Stack kits, Next.js, Vite React, Node API, Astro and more, live in the online catalog at crystl.dev. They are additive: a fetched kit appears alongside the built-in one rather than replacing it. If crystl has not reached the catalog, the list says so, because a one-row list with no explanation reads as “this is all crystl has”.

Five purpose kits

One kit per type that produces something other than software. General gets none: a kit for “anything the other six do not describe” could only hold generic headings.

Kit Sections it writes Files it lays down
Coding Project Build & Run, Architecture, Code Style, Testing Philosophy, Verification Gate, Commit Discipline, File Size Limit, Mistakes Log none of its own
Research Gem Files in this gem, Citing a source, Mistakes Log sources/README.md, FINDINGS.md
Content Gem Files in this gem, Audience and voice, Mistakes Log drafts/README.md, published/README.md, STYLE.md
Records Gem Files in this gem, Entry format, Adding an entry, Mistakes Log data/README.md
Personal Gem Files in this gem, Writing in the log, Mistakes Log LOG.md
Orchestration Gem Files in this gem, Mistakes Log ROSTER.md, PRIORITIES.md, INBOX.md, LOG.md, WORKING-WITH-ME.md, and its own richer WORKBENCH.md

Two conventions run through all of them, and they are the point rather than decoration. Every file opens by saying what it is and how it relates to the others, so an agent that opens one file learns the shape of the whole set. And the files cross-link, so the set is a graph rather than a pile.

What every kit ships

Whatever the type, and whether the kit came with crystl, from the catalog, or from your own library:

  • AGENTS.md, holding the kit’s sections.
  • CLAUDE.md, holding the one line @AGENTS.md. Claude Code reads CLAUDE.md and nothing else, so a kit that wrote only AGENTS.md would leave its whole text unread. The import keeps one copy of the writing: editing AGENTS.md changes what every agent reads.
  • WORKBENCH.md, the workbench task list, empty, saying what it is and how a task is written.
  • MISTAKES.md, an empty log saying what goes in it and when to count a repeat.
  • .claude/settings.json for Claude kits, with empty permissions and hooks. Deliberately not pre-filled: a deny rule you did not write is invisible, and the first time it refuses something you would have no idea where the refusal came from.

No kit ships a NORTH-STAR.md, of any type. The only thing one could ship is an empty skeleton, and an empty direction file is the document that feature exists to displace. Getting yours written is a drafting job for your agent.

Installing never overwrites

A file already at the target path is skipped, never replaced. That makes a kit safe on a project you are adopting into crystl.

Skipping asks about the job the file does, not only its name. A gem from before the rename keeps BACKLOG.md, and crystl prefers WORKBENCH.md whenever one exists, so writing an empty WORKBENCH.md into that gem would shadow a live task list and your items would appear to vanish. The same holds for a mistakes log called LESSONS.md, LEARNINGS.md, GUARDRAILS.md or GOTCHAS.md. The existing file wins and the install reports it as skipped.

The file-wise promise

Installing a kit completes the structure. The substance stays yours.

That is the whole contract between kits and the project optimizer: the kit is the answer key for which files and sections a project of this type should have, and the optimizer is the marked paper. Every structure finding is the diff between where you are and what the kit would have given you, and a fresh install clears all of them.

What no kit can supply is what your build command actually is, what your conventions actually are, or what you have actually rejected. Those are reported as substance, and a kit shipping plausible filler to clear them would score 100 and mean nothing. Build & Run arrives holding # add your build / run commands here, and the optimizer says so the moment it is installed. That finding is your own work, honestly labelled, rather than a failure.

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.