Editing Agent Instructions

Read this before modifying AGENTS.md or any guide it links to.

Token Budget Mindset

AGENTS.md loads on every agent request; domain guides load on entry to a relevant area. Keep AGENTS.md under 200 lines and each domain guide under 300 lines. When a file exceeds its budget, split or prune — do not compress prose to fit.

When NOT to Add Content

Before writing a new rule, ask whether it is actually needed:

Agents already do it. Test with a prompt first. If the agent behaves correctly without the rule, don't add it.
One-off incident. Prefer a code-level fix (lint rule, CI check, test assertion) over a new doc rule.
Hardcoded paths. File paths change; use "search for X" patterns instead.
Upstream docs. Don't reproduce pytest, ruff, or other tool docs — link to them.
Contradicts an existing rule. Search all linked guides before adding. If two rules conflict, consolidate into one.
Already covered elsewhere. Search AGENTS.md and every linked guide for overlapping guidance.

If any of the above apply, do not add the content.

Where Content Belongs

The goal is a lean AGENTS.md plus rich domain guides that teach agents what they can't learn from the code alone.

Scope	File
Project-wide invariants (contribution policy, env setup, test/lint commands, commit conventions)	`AGENTS.md`
Area-specific knowledge (model patterns, format details, deprecation timelines)	Domain guide

Rules of thumb:

If it only matters for one area, put it in a domain guide.
If it matters for all areas, consider AGENTS.md — but first verify agents don't already do it.
Create a new domain guide when you have 5 or more non-obvious instructions sharing a coherent scope.

What Makes a Good Domain Guide

Add what agents can't infer from the code or public docs: project-specific conventions that differ from standard patterns, correct approaches that require cross-file context, and fixes for repeated mistakes. Each entry should be short, specific, and actionable — e.g., which files to touch, what order to change them in, and which tests to run.

Skills

Skills live in .agents/skills/<name>/ and follow the Agent Skills specification.

Claude Code does not read .agents/, so symlink each skill: ln -s ../../.agents/skills/<name> .claude/skills/<name>.
Frontmatter: name matches the directory. description says what the skill does and when to use it; quote it if it contains a colon.
Keep SKILL.md under 500 lines and move detail into files it links to.
tools/pre_commit/check_agent_files.py runs in pre-commit to check the skill and AGENTS.md rules

Keeping Docs Lean

Every addition should trigger review of surrounding content for stale or redundant items.
Prefer examples over explanations — a 3-line snippet beats a paragraph of prose.
Merge related bullets into one principle instead of listing variants.
Use search for X instead of hardcoded file paths.
PR references are fine in domain guides for traceability, but avoid them in AGENTS.md.

Anti-Patterns

Pattern	Problem
Reactive accumulation	Adding a rule per incident without pruning leads to bloat
Copy-paste between guides	Duplicated content drifts apart; keep in one place, link from the other
Imperative walls	Long DO NOT lists that agents skim past; consolidate into principles
Config snapshots	Show the command to get the value, not the value itself

Change Checklist

Before submitting changes to any agent instruction file:

Non-obvious? Would an agent do the wrong thing without this rule?
No conflicts? Searched all linked guides for contradictions?
Right file? Project-wide goes in AGENTS.md, area-specific in a domain guide?
Offset the addition? Removed or consolidated something to compensate?
Under budget? AGENTS.md < 200 lines, domain guides < 300 lines?
No hardcoded paths? Uses "search for X" where paths may change?
Tested? Verified that an agent actually follows the new instruction?