How to Write a Skill so Your Agent Can Follow It

In step 3, you learned how to improve a skill from real session evidence. When something goes wrong, you make the smallest patch that fixes the problem.

That keeps unnecessary rules from getting into the skill. But even useful patches add up. Over time, a skill can become harder to read simply because every fix leaves another sentence behind.

This step is about writing those instructions so they stay clear and compact. The goal is not to make the skill as short as possible. The goal is to make every line easy to understand and useful to the agent.

A good skill should make the next action obvious.

Use the name people already know

Sometimes a long explanation already has a shorter name. For example, you could write:

Go through the deployment steps without actually making any changes so we can see what would happen first.

Or, if the term is already familiar to the people using the skill:

Dry run first.

You could write:

If the new version causes a problem, return the system to the last working version.

Or:

Rollback if the deployment fails.

The shorter version works because dry run and rollback already carry meaning for the people reading them.

The same can be true of phrases like breaking change or source of truth. A shared term can replace several sentences without losing the idea.

The important word there is shared. If the reader has to stop and look up the term, you have not made the instruction clearer. You’ve only hidden the explanation inside unfamiliar vocabulary.

When a section feels too long, ask whether the idea already has a familiar name. If it does, use the shorter term. If it doesn’t, keep the explanation. Remember, clarity matters more than cleverness.

Tell the agent what to do

One of the easiest ways to make an instruction clearer is to describe the behavior you want.

Compare:

Do not ask several questions at once.

with:

Ask one question, then wait for the answer before continuing.

The first tells the agent what to avoid. The second tells it what to do instead.

That difference matters because a prohibition can still leave the next action unclear. If you say do not continue, the agent still has to figure out what it should do while it waits.

This doesn’t mean that every don’t is bad. Some rules really are boundaries.

• Do not delete production data.
• Do not deploy without approval.
• Do not include credentials in the output.

Those rules are useful because the forbidden action itself matters. When there is also a clear next step, include it. For example:

Do not deploy without approval. Prepare the deployment, then ask the reviewer to approve it.

Now the agent knows both the boundary and the correct behavior. When you find a negative instruction, ask whether it tells the agent enough to know what happens next.

Replace vague words with things you can check

Words like clean, concise, thorough, simple, and scannable make sense to people because we fill in their meaning from context.

An agent has to do the same thing.

If you write make the summary concise, the agent has to decide what concise means for this task. One run may produce two sentences. Another may produce six paragraphs.

A checkable criterion gives the instruction a clearer boundary.

Instead of:

Make the summary concise.

you might write:

Summarize the decision, rationale, and next action in three bullets or fewer.

Now both the agent and the reviewer know what success looks like.

Not every check needs a number. Checkable:

• Every recommendation should name the tradeoff it introduces is checkable.
• The command should succeed on a clean checkout.
• The final answer should include the file that changed and why it changed.

The useful question is: How would I know whether this instruction was followed?

If you can’t answer that, the instruction may still be too vague. Don’t add a number just to make something sound precise. Use 47 words or fewer is not automatically better than keep the explanation to one short paragraph. The check should reflect something that actually matters.

Keep the instructions where the agent can find them

A skill doesn’t need to contain everything you know about the task, just the information the agent needs in order to do the work.

That usually means the main skill should hold the steps, the important decisions, the boundaries, and the checks that tell the agent when the task is complete. Longer explanations can live somewhere else.

For example, a testing skill might say which tests to run and what counts as success. A linked reference file could contain the full testing architecture, unusual fixtures, or examples of past failures.

This is progressive disclosure: start with the instructions the agent needs most often, and make deeper information available when the task calls for it.

The benefit is simple. The main skill stays easier to scan, but you do not have to throw away useful context.

Keep the structure shallow. If the skill links to one file, and that file links to three more files, the agent has to hunt for the information. Whenever possible, let the main skill point directly to the reference it may need.

Show the format when the format matters

Sometimes the problem isn’t the wording of the instruction. It is the shape of the output. Suppose you write:

Create a short changelog entry with a title, summary, and migration note.

That describes the structure, but the agent still has to decide what the final format should look like.

If the structure matters, show it.

<changelog-template>
### [Title]

[One-sentence summary]

Migration: [required / not required]
</changelog-template>

Now the agent has a pattern to follow. A template does not guarantee that the output will be perfect, so you still need to check the result. But it removes one unnecessary decision from the task. Use templates when consistency matters not for every answer.

Prune what no longer changes behavior

Even a well-written skill will grow over time.

Every patch from step 3 may have been useful when you added it. But a later change may make an older sentence unnecessary. Two rules may now say almost the same thing. An explanation that helped you write the skill may no longer help the agent use it.

That’s why skills need pruning. Read the skill one sentence at a time and ask:

If I delete this sentence, does the agent behave differently?

If the answer is no, delete it.

Don’t spend time polishing a sentence that no longer needs to exist. A shorter version of an unnecessary instruction is still unnecessary.

Some of the hardest things to remove are explanations you like. They may have helped you understand the problem or arrive at the final rule. That does not mean they still belong in the skill.

If the reasoning is worth saving, put it somewhere else: a commit message, a design note, a linked reference, or the session record that led to the change.

The skill should preserve the behavior, not the entire history of how you discovered it.

Give the whole skill one editing pass

Before you move to the final step, read the skill from beginning to end and make one focused editing pass.

Look for long explanations that have a familiar name. Use the shorter term only when the meaning will already be clear to the people using the skill.

Check that each instruction tells the agent what to do. Keep true prohibitions, but add the correct next action when the agent needs one.

Look for vague words. If an instruction says clean, good, simple, thorough, or concise, ask how you would actually check it.

Move background out of the way. Keep the working instructions in the main skill. Put deeper explanation, large examples, and reference material in linked files.

Prune. Delete any sentence that no longer changes behavior.

What remains may be shorter, but that is not the real goal. The real improvement is that the agent has fewer things to interpret.

In the final step, you will test the whole skill and publish it somewhere your team can actually use it.