Skip to content
Writing

Writing for Agents

Write project instructions that tell an agent when to read a reference and how to recognize completion.

Install with Skills CLI
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.

Install with 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

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.

More in Writing

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.