writing-for-agents

# Writing for agents Write agent instructions for reliable execution, not for completeness as documentation. Every instruction consumes attention. Keep always-loaded context small and move conditional detail behind clear pointers. ## Principles ### Single source of truth Keep each rule or workflow authoritative in one place. Reference it elsewhere instead of copying it. Duplication creates drift and gives repeated instructions accidental extra weight. ### Context pointers A pointer tells the agent: - what information exists; - when it should be loaded. Example: `Use the database-change skill for schema, migration, RLS, or database authorization changes.` The trigger matters as much as the destination. ### Progressive disclosure Keep information at the lowest level that still makes it reliably available. Prefer: 1. short always-loaded pointer; 2. focused skill or rule; 3. deeper reference loaded only when needed. Do not put an entire workflow in `AGENTS.md` when a pointer to a skill is enough. ### Steps vs reference Separate: - actions the agent must perform; - reference material it may consult. Procedural workflows should have a clear sequence. Reference rules should be grouped by concept. ### Completion criteria Important steps should define what "done" means. Prefer observable criteria. Weak: `Review the implementation carefully.` Better: `Inspect the complete diff and account for every changed file before finishing the review.` ### Positive instructions Describe the desired behavior directly. Prefer: `Make focused changes within the issue scope.` over long lists of hypothetical bad behaviors. Use prohibitions for genuine hard guardrails. ### Use the environment as truth Do not duplicate information the agent can cheaply inspect from: - package configuration; - scripts; - directory structure; - CI; - tool help; - code. Document the things the environment does not explain: - intent; - constraints; - decisions; - source precedence; - known traps. ## Writing skills A good skill should contain: - clear name; - invocation description; - purpose; - ordered process when procedural; - rules that materially change behavior; - observable completion criteria. A skill should own one coherent capability. Split skills when they have independent triggers or substantially different workflows. Do not split merely to make files shorter. ## Writing AGENTS.md Use `AGENTS.md` primarily for: - source-of-truth pointers; - important project-wide constraints; - navigation to applicable skills or docs. Avoid turning it into a complete engineering handbook. ## Pruning For every instruction ask: - does this change agent behavior? - does it belong here? - does it duplicate another source? - can the environment answer this instead? - does every task need this in context? Delete instructions that no longer earn their context cost. ## Rules - One authoritative home per behavior. - Project-specific context stays in project repositories. - Global rules should be broadly reusable. - Prefer precise triggers over broad descriptions. - Do not hide critical requirements behind weak optional wording. - Do not repeat the same instruction across skills and rules. ## Completion Agent-facing writing is complete when: - responsibilities are clear; - triggers are clear; - sources of truth are clear; - conditional detail is loaded only when needed; - completion can be evaluated; - duplicated or stale instructions have been removed.