Agent Instruction Files

Updated October 15, 2026

Agent instruction files tell AI coding tools how to work in your project. They define build commands, architecture notes, conventions, and rules that agents follow during every session. crystl gives you a complete system for creating, editing, and managing these files, with guidance at every step.

Supported file types

crystl supports instruction files for multiple AI tools:

File Tool Purpose
CLAUDE.md Claude Code Project instructions loaded at session start
CLAUDE.local.md Claude Code Personal instructions, auto-gitignored
AGENTS.md Any agent (Claude Code, Codex, and most coding tools) Shared project instructions, the cross-tool convention
codex.md Legacy Older Codex convention. Codex reads AGENTS.md; it only reads codex.md if you add it to project_doc_fallback_names
GEMINI.md Antigravity CLI Project instructions for Antigravity CLI (formerly Gemini CLI)
PLANS.md Codex Execution plan template: how agents write living design documents
.cursorrules Cursor Project-level editor rules
.windsurfrules Windsurf Project-level editor rules
copilot-instructions.md GitHub Copilot Instructions for Copilot

Additionally, crystl manages Claude Code’s extended config system: rules, skills, and settings.

Creating files

For an existing project, add a file from the files drawer’s + file button on any folder. See the files drawer below. The library’s own “+ new kit” and “+ new file” buttons open the block editor directly, skipping the drawer.

New gem panel

When creating a new gem, the panel offers a starter kit under INCLUDE STARTER BUNDLE. The kit’s agent file, rules, and skills are written automatically as the gem is created, locally or over SSH, and existing files are never overwritten. See starter files.

The block editor

Every instruction file opens in crystl’s two-column block editor:

  • Left pane: the file content, shown as draggable block sections (or a raw text view)
  • Right pane: a block library where you can browse and insert reusable sections

Blocks represent logical sections of your file (e.g. “Build & Run”, “Architecture”, “Conventions”). You can:

  • Drag blocks to reorder them
  • Click a block to expand and edit its content
  • Toggle between blocks mode and raw mode for direct text editing
  • Insert blocks from the library with one click

Line count indicator

When editing CLAUDE.md or CLAUDE.local.md, the editor footer shows a live line count:

  • Plain: under 150 lines, within target
  • Yellow: 150-200 lines, approaching the recommended limit
  • Red: over 200 lines, consider splitting into rules

Claude Code recommends keeping CLAUDE.md under 200 lines for best performance. The indicator helps you know when it’s time to refactor.

The file library

Open settings, context, to manage your file templates and skills. The page has five tabs: starter kits, files, skills, plugins, and rules.

starter kits

Bundles: a whole agent file setup installed into a project in one go, rather than one file at a time. crystl ships a universal Coding Project kit, listed first, and your own kits appear below it. Click “+ new kit” to build one, which starts from the CLAUDE.md scaffold.

Kits are what the New Gem panel offers under INCLUDE STARTER BUNDLE, so this is the tab to visit when you want new projects to start with a particular setup.

files

Single-file templates: one CLAUDE.md, one AGENTS.md, one codex.md, as opposed to a kit’s collection. Click “+ new file” and it opens blank in the block editor.

There are two ways in: “+ new file” here, or the save as template button in the file editor’s footer, which puts the file you’re looking at into the library under a name you pick. Templates get unique names automatically. Creating multiple CLAUDE.md templates gives you “CLAUDE.md”, “CLAUDE.md 2”, etc. Rename them in the editor to something descriptive like “Swift Project” or “React App”. A template writes to its file type’s usual name unless you set a custom filename on it (e.g. docs/setup.md).

skills

Two sub-tabs, claude and other agents.

claude manages .claude/commands/*.md, the slash commands Claude Code can invoke. These are simple markdown prompt templates. You can:

  • Browse and import skills from the crystl skills library
  • Create new skills with the “+ new skill” button
  • Edit and delete existing skills

other agents manages ~/.agents/skills/*/SKILL.md, the shared skills directory that Codex, Antigravity, and other agents read. Same pattern: browse, create, edit, delete.

plugins

One row per installed Claude Code plugin, showing where it is on disk and how many skills it bundles. A plugin you have turned off for the open project is dimmed and badged.

This tab sits beside skills because a plugin’s payload is skills, commands, and subagents. Before it existed, plugin-bundled skills appeared in no tab at all, so someone with a dozen plugins saw none of the skills those plugins added.

It is read-only, unlike the tabs either side of it. The plugin system re-materialises a file you delete and overwrites a file you edit, so a delete or edit button here would offer something it cannot make stick. The rows don’t expand either: a normal machine has well over a hundred skill files under the plugin cache, and listing them all is a wall of rows you can’t act on. Each row has a reveal button that opens the plugin’s directory instead.

The list is read from your agent’s installed-plugins manifest rather than by walking the cache, so a plugin with two versions cached still counts once. Plugins are installed per machine, so for an SSH gem this shows the plugins on your Mac, not the ones the remote agent loads. The tab says so when the open shard is remote.

To turn plugins on or off per project, see plugins & skills.

rules

Manage rule files from both scopes Claude Code loads: ~/.claude/rules/*.md for every project, and the open project’s .claude/rules/*.md. Rules are modular instruction files that Claude Code auto-discovers. When your CLAUDE.md gets too long, move sections into focused rule files.

Creating a rule prompts for:

  • Name: becomes the filename (e.g. testing-conventions.md)
  • Save in: the global scope, or the open project
  • Path scope (optional): glob patterns that restrict when the rule loads (e.g. src/Api/**/*.cs, **/Migrations/**). Rules without a path scope load every session.

Rules with path scoping get YAML frontmatter:

---
paths:
  - "src/Api/**/*.cs"
  - "**/Migrations/**"
---

Each rule’s row says where the file is and, for scoped rules, which paths it applies to.

The files drawer

Open a gem’s right sidebar and switch to files (Cmd + ] cycles the views). It shows the project’s real file tree with what crystl knows about your agents drawn on top:

  • Folders draw in blue, files in white, and a breadcrumb under the tabs says which folder you’re in as you scroll deeper.
  • A file an agent loads carries a badge saying how it’s reached (named in instructions, found by path), and the read order tab estimates what each file costs in tokens at session start.
  • Files worth having that aren’t in the project appear as dotted rows: the recommended instruction files, a docs/ folder, and the shared .agents/skills/ home. Each one has an add button and a small ? bubble explaining what the file is for and why it helps. If your library holds a saved file of that name, the add button offers it alongside crystl’s scaffold.
  • + file on any folder creates a blank file, deposits a saved library file, or scaffolds a new skill.

Agent skills

Skills are the open SKILL.md format (agentskills.io): a folder with a name, a short description, and instructions an agent loads only when a task calls for them. The drawer recognizes a skill wherever it lives in the project, shows which of your agents can discover it from that location, and charges only the small metadata part to session start, because that’s all agents load eagerly.

The shared home is .agents/skills/. Codex, Cursor, Gemini CLI, Copilot, Goose, and most tools adopting the standard read it directly. Claude Code only reads .claude/skills/, so the drawer offers one click that links the shared folder into it, the arrangement Claude Code’s own docs describe. The link happens only when you click, it never overwrites a folder that’s already there, and on a remote gem that can’t be reached it says so rather than guessing. Skills you already have in .claude/skills/ can move into the shared folder, after a confirmation step. The drawer says whether a skill is linked and where the link points.

Project optimizer

The files drawer’s optimizer tab scans your project and flags configuration gaps, with a score card at the top. Agent file checks include:

  • No CLAUDE.md (high): your agent has no project instructions
  • No AGENTS.md (medium): instructions exist for one agent but nothing portable to a second
  • No Build & Run section (high): agents can’t build or test without the commands
  • Build & Run is a placeholder (high): the section exists but has no real commands yet
  • Imported file does not exist (medium): an @path import names a file that is not in the project
  • No file size limit stated (low): without a limit, agents create unbounded files
  • CLAUDE.md is very short (low): likely a stub, and more context improves agent accuracy

There is deliberately no check for a long instruction file, and none for a missing .claude/rules/ or .claude/settings.json: length is not a defect on its own, and a convenience you have not opted into is not a gap.

Each recommendation explains why it matters and, where possible, offers a button to create the missing file.

SSH support

All file operations work over SSH: creating files, writing templates, inserting rules, and setting up the .claude/rules/ directory. crystl uses the SSH ControlMaster socket for file transport, so remote projects get the same file management as local ones.

Best practices

Keep CLAUDE.md under 200 lines. This is Claude Code’s recommended target. The editor’s line count bar helps you stay within it.

Split early with rules. Don’t wait until CLAUDE.md is unwieldy. Create focused rule files for distinct concerns: testing conventions, API patterns, code style, migration safety.

Use path scoping for monorepos. Rules can target specific directories or file patterns, so frontend rules don’t load when working on backend code.

Use templates for consistency. If your team has multiple projects, build a starter kit in the library and pick it when creating a gem, so any project you choose starts with the same instructions. A file that turned out well in one project can be saved into the library as a starter and deposited into others.

CLAUDE.local.md for personal preferences. Keep team-shared instructions in CLAUDE.md and personal preferences (verbose output, preferred test runner) in CLAUDE.local.md. It’s auto-gitignored.