Write Predictable Instructions for Agents

What it does

The source distinguishes steps from reference material and always-loaded context from material reached through pointers. A pointer should explain both what a document contains and when to read it. Branch-specific references can move out of the main flow, while essential instructions remain visible. The guidance treats environment configuration as a source of truth and warns that restating it creates a stale cache. Pruning removes irrelevant or ineffective sentences; it is not permission to delete hard security or data-protection boundaries.

When to use it

• Shorten a bloated AGENTS.md without losing essential guidance.
• Make a specialist reference discoverable under the right trigger.
• Improve a workflow whose vague done condition causes premature completion.

Step-by-step workflow

1. Identify the document’s real branches and the behavior each must produce.
2. Separate ordered actions from definitions and optional reference.
3. Keep shared essentials inline and give branch references explicit triggers.
4. Replace vague completion language with observable, sufficiently demanding criteria.
5. Remove duplication and stale environment copies, then review the revised paths.

Example request

Use writing-for-agents to review our deployment instructions. Identify which commands are already authoritative in package scripts and which operational decisions are undocumented. Keep credential rules and rollback requirements explicit. Show a shorter main flow with precise completion checks and triggered references for optional environments. Propose the diff before editing. Do not create or install a skill.

Worked example

A deployment document saying verify everything can be sharpened into checking the expected public version and a representative user flow. A staging-only procedure can move behind a clear staging trigger instead of interrupting every production read. If the repository already names its build command in package scripts, duplicating the command in several guides creates drift. The review should preserve the reason for an unusual step, because that knowledge may not be recoverable from configuration alone.

What you get

A proposed instruction rewrite with deliberate information hierarchy, precise pointers and observable completion boundaries.

How to evaluate the result

• Check every pointer names a real target and useful trigger.
• Verify each step has a checkable completion condition.
• Review deletions against security, accessibility and data-preservation requirements.

What you need

The current document, related references and actual environment configuration. Skill authoring also requires the source’s SKILL-MECHANICS reference for invocation and frontmatter details.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

Document wording is not a guarantee of agent behavior. Test important branches in the intended client before treating a rewrite as reliable. Removing a redundant sentence must not remove an explicit user requirement or safety boundary.

Related workflows

• Use retro to identify instruction problems from actual sessions.
• Use skill-creator for a separately authorized skill-authoring project.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Reviewed SKILL.md (immutable commit)
• Publisher README: distributions and compatibility
• Reviewed MIT license