Agent instructions and system prompts in crystl

Your agent uses the crystl command for many crystl features: cards with a button, the copy bar, the workbench, worker shards, and waiting on another shard. It uses them only if it knows the command exists and when to use it. crystl tells it in three places: a block in each project, a section in your global instruction files, and eight skill files. Together they are crystl’s agent instructions, and settings → system prompts shows all of them. This page says what that buys you, what each place holds, who reads it, and how to see it, edit it, or turn it off.

What your agents can do with it

Hand you a button instead of a sentence. When something needs running, the agent sends a card with the command on it, and you click once. Without the briefing it writes “run this” in prose.
Put things where you can grab them. Tokens, URLs and snippets go to the copy bar. Files open rendered in the drawer. Tasks land on the workbench.
Fan work out and bring it back. The agent can start worker shards in their own worktrees, name them, wait for them, and tell you when they need a person. It knows not to merge its own branch.
Check who is talking. A message that claims to come from another shard gets verified before the agent acts on it.
Know what your licence allows. The agent plans around Guild-only commands instead of hitting a refusal mid-task.
Pay for the detail only when it is used. The eight skills load on demand, so a session that never spawns a worker never reads the fan-out rules.
Work the same in every agent. Claude Code, Codex, Kimi, opencode, goose, Copilot CLI, Gemini CLI, Cursor and Antigravity all read the same text from the folder each one scans.
Brief your teammates’ agents too. The project block is committed with the repo, so an agent on another machine gets the same instructions.

If you just saw eight crystl- skills appear

crystl 2.284.0 wrote them the first time it launched. They teach your agent how to use crystl’s own commands. Your agent reads only a one-line description of each skill when a session starts. It loads the full text only when a task needs it.

The skills sit in your home folder, so agents see them in every project. Each skill tells the agent to ignore it outside a crystl shard. To remove all eight, see turning it off.

The three places

A block in each project. Every gem (a project open in crystl) gets a short block in its AGENTS.md. The block is about 4 KB and under 40 lines. It starts with a marker line such as , which names the crystl version that wrote it, and ends with . To find it in a file, search for crystl-cli:begin. The gem’s CLAUDE.md imports the block with @AGENTS.md. It holds how to tell whether the agent is inside crystl, the rule for checking that a message from another shard is real, the everyday commands, how crystl wants the agent to use them, and the worktree rules. Agents read it in full at the start of each session, so it stays short. Because it is committed to the repo, a teammate’s agent also reads it, even if that teammate does not use crystl.

A section in your global files. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md get a section that starts with a marker line such as  and ends with . The marker names the version and the tier the section was written for. It says which crystl commands your licence includes and where your identity file is. The project block is shared with your team, so it does not assume a licence. The global section knows whether you are on the free tier or Guild. See CLI command tiers.

Eight skills. Each is a folder named crystl-<topic> that holds a SKILL.md:

Skill	What it covers
`crystl-cli`	how to tell whether the agent is inside crystl, the full rule for checking a message from another shard, the tier marking, the read commands
`crystl-fanout`	spawning, naming, waiting on and merging worker shards and worktrees
`crystl-reveal`	cards, the copy bar, markdown show, the workbench and links panels, activity
`crystl-workbench`	the WORKBENCH.md and LINKS.md formats, NORTH-STAR.md, gem types
`crystl-sequences`	sequences, stages and schedules
`crystl-endpoints`	model endpoints, keys on stdin, local-model worker limits
`crystl-crews`	heroes, parties, quests, sidequests, courts, gauntlets, formations
`crystl-keys`	finding where a key lives and asking for a missing one without printing it

The project block used to be 30 KB, and every agent read all of it, every session. Now the detail lives in the skills and loads only when needed. An agent that supports skills reads only each skill’s one-line description at session start. A session that never spawns a worker pays only for one description line. The full fan-out rules load when a task needs them.

Each skill file has a marker line that says crystl wrote it and gives its version. crystl rewrites its own files when the version changes. It never changes a SKILL.md it did not write, even if the name matches.

Who reads what

crystl writes the skills to the folder each agent reads:

Agent	Reads
Claude Code	`~/.claude/skills`
Codex, Kimi Code, opencode, goose, Copilot CLI, Gemini CLI, Cursor	`~/.agents/skills`
Antigravity	`~/.gemini/config/skills`, written only when Antigravity is installed
`claude@<endpoint>` and `codex@<endpoint>` sessions on a model endpoint	`~/.claude/skills` or `~/.agents/skills`, to match the agent
aider, and any agent with no skills	nothing; see agents without skills

Inside and outside crystl

The skills live in your home folder. Every agent sees them in every project, inside or outside crystl. Each description starts with “Inside a crystl shard only”. Each body starts with a test: if CRYSTL_SHARD is not set in the environment, the agent is not in a crystl shard, so it should skip the skill and run no crystl commands. The project block and the global section open with the same test.

The skills are instructions. Nothing blocks an agent from running them. An agent that ignores the test can still run crystl outside a shard, and that command may act on the crystl app that is running. If that matters to you, turn the skills off.

Seeing and editing the text

Settings → system prompts shows every prompt crystl gives your agents, read from the same code that writes it. You can edit some of them and only read the others.

You can edit these:

the project block
the global section
the skills group, with one card per skill

You can read these, but not edit them, under quest and worktree prompts:

the prompts each agent gets in a quest
the rules for a shard in its own worktree
the protocol a fan-out worker follows

crystl fills these in when a shard starts, with the shard’s name and the shards beside it. The cards show placeholders such as <shard> in those places.

To change an editable card:

Press edit, change the text, and save writes it into the files at once.
crystl adds the skill’s name, its description, the crystl-only line and the marker line itself. The body is yours to edit.
Agents learn crystl’s commands from this text. If you delete a command here, agents stop using it.
reset to crystl’s default brings the shipped text back.
When a release changes the default behind your edit, the skill’s card says so. show what changed shows the diff, and take the new default replaces your text.

Settings → context → skills lists every skill on this Mac, yours and crystl’s. A crystl skill has a crystl tag. Its edit button opens system prompts. It has no delete button, because crystl would write the file again at the next launch.

Turning it off

Two switches in Settings → agents → defaults, under AGENT AWARENESS:

tell agents about the crystl CLI in each gem controls the project block. When it is off, crystl writes no new blocks. Blocks already in your repos stay, because editing committed files is your call. To remove them, run crystl uninstall --primers (the project blocks). Add --dry-run to see what it would change first.
tell agents about your licence in the global files controls the global section and the skills together. Both live in your home folder, so one switch controls everything crystl writes there. You cannot keep one and drop the other. When it is off, crystl removes the section from your global files and deletes its eight skill files, in every folder it wrote them. The button remove crystl’s section from the global files now does both at once and turns the switch off. Turn the switch back on and crystl writes them again, with any edits you made under system prompts.

On a fresh install, crystl writes all three at first launch. A card then tells you so, with a remove it button. After an upgrade to 2.284.0, crystl writes the skills at first launch and shows a what’s new card with a see the skills button.

Removing one skill and keeping the others is not a crystl setting. Codex can turn off single skills in its own config, and the skills tab shows these as disabled. Other agents load every skill in their folder.

With both switches off, an agent in a gem does not know it is inside crystl. It still works as a coding agent. It does not use cards, the copy bar, the workbench, or worker shards unless you ask.

Agents without skills

aider has no skills, and by default it does not read AGENTS.md either, so out of the box it gets no briefing. To give it the project block, point it at the file with --read AGENTS.md or a read: entry in .aider.conf.yml. The block’s last line names crystl docs <topic>, which prints the detailed material in the terminal for fanout, sequences, crystl-quest, open-models, api-keys and task-backlog. Other tools without skills get the same block and the same pointer.

When something looks wrong

A crystl skill is missing from an agent’s list. Check the folder that agent reads in the table above, and check the switch is on. Codex can turn off single skills in its own config; the skills tab shows these as disabled.
An edit was lost. An edit made in the file itself is replaced by the default at the next launch. Edit under system prompts instead, where it is kept as your own version.
A skill file crystl did not write is in the way. crystl keeps it and says so in the launch log. Rename or remove it yourself if you want crystl’s version there.
The marker line in a skill shows an older version than the app. The files are rewritten at the first launch of each release. Restart crystl to update them.