Agent Instruction Files

Updated April 16, 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.mdGoogle GeminiProject instructions for 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
  • Click ”+ new template” in the File Library settings

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 includes dropdowns for selecting CLAUDE.md and codex.md templates from your library. These templates are applied automatically when the gem is created — locally or over SSH.

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 > File Library to manage your file templates and skills. The library has four tabs:

Templates

Reusable instruction file templates that you can select when creating new gems. Each template is a collection of blocks for a specific file type (CLAUDE.md, AGENTS.md, codex.md, etc.). Click ”+ new template” to open the file chooser and create a template for any supported type.

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

Claude Skills

Manage .claude/commands/*.md files — slash commands that 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

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

Codex Skills

Manage ~/.agents/skills/*/SKILL.md files for Codex CLI. Same pattern as Claude skills — browse, create, edit, delete.

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 File Library, 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, create File Library templates 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.