Improve the structure, triggers and completion criteria of skills, AGENTS.md or CLAUDE.md instructions.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill writing-for-agents --agent claude-code
For Codex, replace claude-code with codex in the command and /writing-for-agents with $writing-for-agents in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:writing-for-agents instead; avoid installing the same skills twice.
Provide the file and at least one observed failure, such as skipped checks, unwanted activation or missed reference material. Identify rules that must remain so editing the instructions does not silently redesign your team’s process.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/writing-for-agents
Revise this project’s AGENTS.md. Deployment instructions are mixed into daily development and agents prepare a release too early. Preserve permission requirements, make the deployment trigger explicit and clarify development completion criteria.
Work through the task
Locate the instruction failure
Distinguish activation, reading and completion problems. A deployment section entering context too early may need a sharper condition; skipped testing may reflect an unclear completion criterion. Adding emphasis everywhere does not address these different failure modes.
Separate steps from reference
Keep universally required actions in the main sequence and move branch-specific detail behind explicit reference pointers. A pointer should say when to read the file, not merely that more information exists. Place related definitions and exceptions together so one reading provides the needed context.
Make completion observable
Replace vague completion language with observable outcomes, such as reporting the checks actually run and any unfinished items. Avoid duplicating commands already defined in package.json across several documents. Point to the authoritative place so later updates do not create conflicting instructions.
Check the result
Review the diff against the original requirements: essential rules retained, triggers understandable and referenced files present. Try the previously failing task again and observe whether behavior improves. Fewer words are a side effect, not the success criterion.
Common questions
Does it package an installable plugin? It guides instruction writing; packaging and distribution are separate.
Is shorter always better? Preserve necessary constraints and organize information around when it is needed.
Does it suit ordinary articles? It targets agent-consumed working instructions; reader-facing articles usually need a different style.
Simplify customer-support routing instructions
A support agent may escalate every customer message as an engineering incident. Ask: “Use writing-for-agents to simplify support/AGENTS.md while preserving privacy and escalation rules. State when to read refund, incident, and account-recovery references. Use ‘duplicate charge with no visible order’ as the failure case; after revision, check that the agent looks up order and payment records before escalation.” Begin with the real misclassification, not a vague request for clearer prose.
Test both an ordinary refund question and a real duplicate charge. The first should not start incident response; the second should not lose escalation because the file became shorter. If the same sentence is bolded in the main document and three references, the trigger ambiguity remains. Clear entry conditions, necessary exceptions, and observable stopping points matter more than additional words.
Consolidate duplicated decision rules
When revising a long skill, put each decision rule in one place and refer to it elsewhere. Then check when dependencies load and whether the executor can tell when to stop. A contributor used writing-for-agents to refine seven workflows, consolidating duplicated review rules and dependency-loading guidance in a second pass and shortening three skill bodies. That is an editorial outcome, not proof that shorter prompts perform better. Re-run a task that previously failed to see whether triggering, execution, and completion claims improve.