ai-agents claude-agents.instructions.md

Claude Agent and Skill Rules

src/claude/*.md are hand-maintained Claude agent prompts with unique Claude-specific content (name/model frontmatter). They are NOT generated. templates/agents/*.shared.md holds the shared body that the Copilot and VS Code copies are generated from. No check compares the content of src/claude/*.md against that shared body, and the co-change check that exists is one-directional (see MUST-1). .claude/agents/, .claude/skills/, and .claude/commands/ hold per-repo artifacts loaded by Claude Code.

MUST

1. Edit Claude agents directly, in lockstep with the shared template. src/claude/*.md is hand-maintained; no generator writes it (detect_agent_drift.py:19 "Claude agents have unique content and are NOT generated from templates."). To change shared agent behavior, edit BOTH src/claude/<agent>.md AND templates/agents/<agent>.shared.md in the same change, then run uv run python build/generate_agents.py to refresh the generated Copilot and VS Code copies (src/copilot-cli/, src/vs-code-agents/). build/scripts/validate_install_parity.py checks co-change in a diff, not content agreement: "reports the sibling files that should have changed together and did not" (validate_install_parity.py:24). Nothing compares the two files' text for agreement.

That co-change check is asymmetric, so it does not enforce the lockstep in the direction you most need. Measured at origin/main:

python3 build/scripts/validate_install_parity.py --files templates/agents/architect.shared.md; echo $?  # 1
python3 build/scripts/validate_install_parity.py --files src/claude/architect.md;          echo $?  # 0

A solo template edit is caught. A solo src/claude/ edit is not: the hand-maintained copies are exempt from the required-sibling set, so you can change Claude agent behavior without touching the template and no gate objects. This carve-out is load-bearing, not vestigial: measured at origin/main 08f4941565, of the 173 commits since 2025-01-01 touching a hand-maintained member of a shared-agent group, 54 (31%) did not touch the template. A group is a stem with a templates/agents/{stem}.shared.md, and its hand-maintained members are all three of src/claude/{stem}.md, .claude/agents/{stem}.md, and .github/agents/{stem}.agent.md. Counting only src/claude/ gives a different and narrower 26 of 142, 18%. Both figures grow as commits land, so re-measure rather than trusting the absolute counts; the ratio is the durable part. Treat the lockstep as a convention you uphold, not a rule the tooling enforces. The drift detector scores similarity against a floor, a much weaker condition than agreement; see the section below. Read both files before you edit either. 2. Skill schema. Every skill MUST have a SKILL.md with frontmatter fields name, version, description per .agents/steering/claude-skills.md. 3. Skill tests. New skills MUST include pytest coverage under tests/skills/<name>/; CI tests do not ship with skills. 4. File cap per PR. Skill additions SHOULD ship ≤10 files per PR (see .agents/steering/claude-skills.md). 5. No internal references in src/claude/. Files under src/claude/ MUST NOT reference .agents/ paths that will not exist for downstream installers. 6. Python for skill scripts. New skill scripts MUST be Python per ADR-042. 7. Test what the prose promises. When a SKILL.md names a script, an exit code, and what that code means, it has defined an executable contract, and at least one file under tests/ MUST assert the documented exit-code behavior. Prose is not enforcement: a documented exit code that nothing asserts drifts from the script the first time someone edits the script and not the document, and the drift is invisible because the document still reads correctly. check_skill_contract_tests.py enforces this.