Editing Agent Instructions

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

File Layout

Generic	Variants	Audience	Scope
AGENTS.md	CLAUDE.md, ...	Agents	Project-wide instructions.
.agent/	.claude/, .codex/, ...	Agents	Agent specification directory.
docs/	N/A	Humans & Agents	Project documentation.

Generic files are framework-agnostic. Variants directly symlink generic files or refer to them and add framework-specific content.

For skills, keep canonical content under .agent/skills/<skill-name>/SKILL.md. Variant trees such as .codex/skills/<skill-name> and .claude/skills/<skill-name> should be directory symlinks to the canonical .agent skill directory, not directories containing only a symlinked SKILL.md. Codex documents support for symlinked skill folders and can skip file-level SKILL.md symlinks during discovery. Claude Code discovers the file-level symlink layout in current versions, but directory symlinks match the shared skill-package structure and keep supporting files in sync across frameworks.

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.

Keeping Docs Lean

• Every addition should trigger review of surrounding content for stale or redundant items.
• Refer to existing files (e.g., "follow the PR template") instead of restating their content — keep a single source of truth.
• 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?

Acknowledgements

This guide is adapted from the vLLM project's editing-agent-instructions.md.

Last updated: 05/13/2026