Most "prompt engineering" advice is about wording. The thing that actually changes agent behaviour is structure: what the document says, in what order, and how it tells the agent when to stop.

This is the anatomy I keep coming back to. It is the shape of a good SKILL.md, and it is not specific to any one tool.

1. Frontmatter: name and description 

--- name: pull-request-review description: "Analyze a PR and produce a report with blockers, suggestions and risks." ---

The description is not marketing copy. It is the routing signal: an agent with a folder of skills reads these to decide which one applies. Write it as when to use this, not what this is about.

2. When to use it (and when not to)

A short section that names the trigger and the boundary:

  • use it when a diff is ready for review and the author wants blocking issues separated from suggestions;
  • do not use it for a single-file typo fix, where the full procedure is overkill.

Skills fail most often here, not in the steps. An agent that applies the wrong skill confidently is worse than one that does nothing.

3. Prerequisites

What has to be true before step 1: the repository is checked out, the CI config is readable, the migration folder exists. Anything the agent would otherwise discover by guessing.

4. The numbered procedure

This is the part that makes the difference. Numbered steps give the agent a state machine: it is on step 3, and step 3 has a defined end. Prose has no state, so the model decides for itself when it is finished, and it usually decides too early.

## Procedure  1. Read the full diff before commenting. 2. Separate blocking issues from suggestions. 3. Verify every claim against the code, not the description. 4. Confirm the changelog entry exists for every user-visible change. 5. Verify migrations have a down-migration.

One action per step. If a step needs an "and", it is two steps.

5. Worked examples

A realistic input and the expected output. Examples do more work than rules: they show the level of detail, the tone, and the format the agent should produce. One good example beats three paragraphs of instruction.

6. Common mistakes

The failure modes you learned the hard way:

  • commenting on the diff summary instead of the diff;
  • treating a style preference as a blocker;
  • approving a migration without checking the down path.

This section is where a skill earns its keep. It encodes the judgement that took you time to build.

7. A verification checklist

The last step, and the one people skip. A checklist turns "looks done" into "confirmed done":

  • [ ] every blocker cites a line in the diff;
  • [ ] the changelog covers all user-visible changes;
  • [ ] every migration has a down path;
  • [ ] no claim was taken from the PR description without checking the code.

Without it, the agent stops when it runs out of things to say. With it, it has to confirm each item before it can call the task finished.

The shape, in one line

Frontmatter for routing, a boundary for scope, prerequisites for context, numbered steps for state, examples for calibration, mistakes for judgement, a checklist for completion.

Write those seven sections once and you have a document that behaves the same way every time, with any agent that can read Markdown.

I built Skill Forge to generate this shape from whatever material you already have: notes, a doc, a rough draft. The demo needs no account, and the output is a plain .md you can keep or publish.