Agent Instruction Files

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

FileToolPurpose
CLAUDE.mdClaude CodeProject instructions loaded at session start
CLAUDE.local.mdClaude CodePersonal instructions, auto-gitignored
AGENTS.mdClaude CodeMulti-agent workflow definitions
codex.mdOpenAI CodexProject instructions for Codex CLI
GEMINI.mdAntigravity CLIProject instructions for Antigravity CLI (formerly Gemini CLI)
.cursorrulesCursorProject-level editor rules
.windsurfrulesWindsurfProject-level editor rules
copilot-instructions.mdGitHub CopilotInstructions for Copilot

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

Creating files

File chooser panel

The file chooser is a glass panel that shows every supported file type with an icon and a short description explaining what it does and when to use it. It appears when you click ”+ add file” in the Map View while browsing a project. (The library’s own ”+ new kit” and ”+ new file” buttons skip it and open the block editor directly.)

Each entry shows whether the file already exists in the current project (green dot). Selecting a type creates the file with a scaffold template and opens the block editor.

CLAUDE.md w/rules

One of the file chooser options is CLAUDE.md w/rules, marked with a “recommended” badge. Selecting it creates both:

  • A CLAUDE.md file with scaffold sections (Overview, Build & Run, Architecture, Conventions)
  • A .claude/rules/ directory for modular instruction files

This is the recommended setup for new projects. It gives you a clean CLAUDE.md that stays focused while rules handle the detail.

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:

  • Green: 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 → library to manage your file templates and skills. The page has four tabs: starter kits, files, skills, 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 sit 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.

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 codex.

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

codex manages ~/.agents/skills/*/SKILL.md for Codex CLI. Same pattern: browse, create, edit, delete.

rules

Manage .claude/rules/*.md files for the current project. 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)
  • 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/**"
---

The rules tab also shows each rule’s path scope at a glance: blue text for scoped rules, dim “no path scope” for rules that always load.

Rules in the map view

When browsing a project in the Map View, navigating into .claude/rules/ shows all rule files with an ”+ add rule” button. This opens the same name + path scope dialog as the library’s rules tab, letting you add rules without leaving the map.

Project optimizer

The optimizer scans your project and flags configuration gaps. Agent file checks include:

  • Missing CLAUDE.md (high): no project instructions at all
  • Missing codex.md (high): when Codex is active but has no instructions
  • CLAUDE.md over 200 lines (medium): suggests splitting into .claude/rules/
  • CLAUDE.md over 400 lines (high): urgently needs splitting
  • No Build & Run section (high): agents can’t build without commands
  • No Architecture section (medium): agents navigate better with a project map
  • No .claude/rules/ (low): suggests modular instruction files
  • Few rules (low): when you have 3 or fewer rules, suggests expanding
  • No .claude/settings.json (low): project permissions for team sharing

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 and the optimizer both help 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 so every new gem starts with the same instructions.

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.