Writing for Agents
Write project instructions that tell an agent when to read a reference and how to recognize completion.
npx skills add mattpocock/skills@writing-for-agents What it does
A repository guide can mention a release checklist without saying when it applies. Writing for Agents makes those triggers explicit and keeps detailed procedures in the document used for that task.
What changes after install
- Name the task that should trigger each reference.
- Separate always-loaded guidance from task-specific steps.
- Express completion in observable terms.
Install
Run this command with Node.js 22.20 or later and select your agent in the Skills CLI.
npx skills add mattpocock/skills@writing-for-agents Before using Writing for Agents
- An existing instruction file or workflow brief, its reference documents, and example requests.
Read the reviewed setup instructions for the selected workflow.
When to use it
- Clarify when an agent should read a project guide.
- Reduce repeated rules across instructions and supporting files.
When not to use it
- Writing customer-facing help or release copy.
A worked example
Take a repository where schema changes require a migration review. Draft one instruction pointing to the migration guide. Try it against two example requests, adding a database column and changing a button label, and check that only the first needs the guide.
Troubleshooting
- When a rule fires too often, narrow its trigger.
- If two documents disagree, choose the authoritative location and link there. Preserve generator-owned marker blocks when editing an existing file and inspect the diff for lost delimiters.
How it chooses an approach
Keep the routing instruction short enough to read on every task. Put the detailed procedure where it will be loaded once the relevant condition holds.
When to use another skill
- Skill Creator for packaging new instructions as a reusable skill.
- Documentation and ADRs for capturing a lasting architectural decision.
- Internal Comms for briefing teammates on the change.
What to check after it runs
Check that each reference resolves and that its trigger covers an actual request. Ask a reviewer to identify the final evidence required for the migration.
Related workflows
More in Writing
- Internal Comms — staff announcements
- Copy Editing — marketing copy revision
- Postmortem Writing — incident review reports
Related skills in other categories
FAQ
- How do I keep generated sections intact?
- Identify the opening and closing markers before editing. Compare the final file with the original and preserve the complete generated block.
- How do I tell whether a shorter instruction still works?
- Use representative requests and compare which procedure the agent chooses and how it decides it is finished.