writing-for-agents

Key References

writing-for-agents

defines everything needed to write documents that agents can read predictably. It replaces

writing-great-skills

, which no longer exists here.

What Counts as Agent Documentation

Agent documentation is any document read by an agent — a skill, an

AGENTS.md

CLAUDE.md

, a spec, a runtime prompt, a README, any document read by an Agent. The packaging varies; the writing remains the same: the same levers make every document predictable, so agents follow the same process every time they run, rather than producing the same output.

Core Principles

Learn to Write Specific Instructions, Not General Guidelines

Write specific instructions, not general guidelines. "Write a function" is not an instruction. "Write a
calculateTotal(cart: Cart): number
function that maps items, sums them, applies a 10% discount, and returns the result" is an instruction. Guidelines don't constrain agents; instructions do.

Learn to Distinguish Between "What to Do" and "How to Do It"

Switch between what to do and how to do it. Every line is either an instruction or data. "Validate user input" is not an instruction; "Check if
email
is in a valid format" is an instruction. "Calculate shipping costs" is not an instruction; "Add $5 if
weight > 10kg
" is an instruction.

Learn to Write Instructions That Will Be Strictly Executed, Not Hoped to Be Followed

Write instructions that will be strictly executed, not ones you hope will be followed. "Ensure code follows best practices" is not an instruction; "Add JSDoc to every function, achieve a minimum coverage of 80%, and use
describe
/
it
blocks for testing" is an instruction. Agents skip vague statements.

Learn to Define Processes, Not Steps

Define processes, not steps. "Write tests first, then code, then refactor" is an instruction. "Build a shopping cart" is not. Agents have freedom at the step level; no freedom at the process level.

Learn to Write Verifiable Instructions, Not Vague Ones

Write verifiable instructions, not vague ones. "Ensure high code quality" is not verifiable. "Every function has JSDoc, every public method has tests, and there are no lint errors" is verifiable. Verifiable instructions allow agents to self-correct.

Learn to Use Precise Vocabulary, Not General Descriptions

Use precise vocabulary. "Create a module" is not an instruction; "Create a
Cart
module with a
checkout
interface that exposes
addItem
,
removeItem
, and
total
" is an instruction. Vocabulary is the interface — it's how you reduce the agent's exploration space in the wrong direction.

Learn to Write Instructions That Agents Will Follow, Not Ones Humans Prefer

Write instructions that agents will follow, not ones humans prefer. "Write a beautiful shopping cart" is not an instruction. "Build a
Cart
component that renders a list of items, each row with a quantity input and delete button, and displays the total at the bottom" is an instruction. Agents don't care about "beautiful" — they care about executable.

Learn to Write Self-Verifiable Instructions, Not Ones That Require Your Check

Write self-verifiable instructions, not ones that require you to check afterward. "Ensure code is correct" provides no verification method. "Run tests, check lint, and verify TypeScript compilation" provides a verification method. Self-verifiable instructions reduce review costs.

Learn to Write Agent-Safe Instructions, Not Developer-Safe Ones

Write agent-safe instructions, not developer-safe ones. "Ensure code is secure" is not an instruction. "Validate all user input, parameterize all SQL queries, and log all authorization checks" is an instruction. Agents can't infer security — they can only execute security instructions.

Learn to Write Precise Constraints, Not Soft Limits

Write precise constraints, not soft limits. "Keep code concise" is not a constraint. "No function exceeds 20 lines, no file exceeds 200 lines, and no nesting goes beyond 3 levels" is a constraint. Constraints are something agents can optimize against.

Learn to Order Instructions by Execution Sequence, Not Importance

Order instructions by execution sequence, not importance. "Write tests first, then code, then refactor" is an instruction. "Ensure code quality, good performance, and test coverage" is not an instruction. Order matters — agents execute in the order they encounter.

When to Use

You call it directly by typing

/writing-for-agents

; it won't be triggered automatically by agents.

Your Scenario	Use
You're writing a skill and need to know what it should look like	`writing-for-agents`
You're writing an `AGENTS.md` or `CLAUDE.md`	`writing-for-agents` — it defines the reference you follow
You're writing a spec	`writing-for-agents` — specs are agent documentation
You're writing a runtime prompt	`writing-for-agents` — prompts are agent documentation
You're writing a README	`writing-for-agents` — if agents read it, it needs to follow the same rules

Frequently Asked Questions

I wrote a prompt, but the agent ignored what I wrote. Your prompt isn't specific enough. "Write a function" is too vague. "Write a

calculateTotal

function that imports the

Cart

type from

src/

and writes tests in

tests/

" is specific enough.

I wrote a prompt, but the agent did what it thought was right. Your prompt didn't constrain the agent. "Improve code quality" doesn't constrain it. "Add JSDoc to every function, achieve a minimum coverage of 80%, and don't use

any

" does constrain it.

I wrote a prompt, but the agent produced the same output twice. Your prompt didn't define a process. "Fix this bug" doesn't define a process. "Reproduce the bug, find the root cause, write a fix, and add regression tests" does define a process.

I wrote a prompt, but the agent stopped where I didn't expect. Your prompt didn't define what counts as done. "Build a shopping cart" doesn't define done. "Build a

Cart

component that renders a list of items, each row with a quantity input and delete button, and displays the total at the bottom" does define done.

I wrote a prompt, but the agent did more than I asked. Your prompt is too large. Split it into smaller, verifiable steps, each with clear completion criteria.

How to Tell if It Works

Agents follow the same process every time they run.
Your prompt contains no vague words.
Your prompt includes verifiable steps.
Your prompt defines completion criteria.
Your prompt includes constraints and boundaries.
Agents don't deviate from your prompt.

Where It Fits

writing-for-agents

is a reference, not a process. It's the standard you check against when writing agent documentation. Other skills rely on it when writing their own documentation, but it doesn't participate in any process itself.

writing-great-skills is its predecessor and no longer exists as a separate entity. This skill replaces it in scope.
Its SKILL-MECHANICS.md documents changes specific when the documentation is a skill — preamble metadata, invocation choices, and routing skills.

ask-matt routes you when you're unsure which skill to use.