Structuring Step-by-Step Instructions Claude Can Follow Reliably
The description gets a Skill discovered. The instructions decide whether it actually works.
Once Claude has matched a task to a Skill, everything from that point forward depends on the body of the SKILL.md file - the actual steps it's meant to follow.
Loose, paragraph-style instructions tend to produce inconsistent results: a slightly different approach each time, details handled differently across runs, an ending that varies in shape.
This page is about the structure that avoids that: clear, numbered steps a reader (and Claude) can follow the same way every time.
Summary
- Core Idea: Instructions structured as ordered, concrete steps produce consistent behavior; instructions written as prose invite drift.
- Why It Matters: A Skill that behaves differently each time it runs is hard to trust, even if any individual run looks reasonable.
- Key Concepts: numbered steps, single-action steps, ambiguous verbs, branching, defined ending, step granularity.
- When to Use: Reach for this whenever you're drafting a Skill's body, or when an existing Skill produces inconsistent results across similar tasks.
- Limitations / Trade-offs: Highly granular steps improve consistency but can make simple tasks feel over-engineered; the right granularity depends on how much the task actually varies.
- Related Topics: Writing an effective description, scoping tool access, bundling reference files, common Skill mistakes.
Foundations
The instruction body of a SKILL.md file is what Claude actually executes once a Skill has been triggered. Its job is to be followed the same way every time, not just to be read once and understood in spirit.
The most reliable shape for that is a numbered list of concrete steps.
## Instructions
1. Read the pull request diff provided by the user.
2. Check each changed file against the team's checklist (naming, tests, comments).
3. List any checklist items that fail, with the specific file and line.
4. If every item passes, state that clearly instead of listing failures.
5. Output the results as a short pass/fail summary per checklist item.Each numbered line does one thing. There's no step that says "review the code and comment on anything that seems off" - that's a paragraph pretending to be a step, and it will produce a different result depending on mood, phrasing, and context each time it runs.
Contrast that with a paragraph version of the same task:
Look over the PR diff and check it against our usual checklist, noting
anything that doesn't look right, and let the user know what needs fixing
before it can be merged.Both describe the same underlying task. Only one of them tells Claude, unambiguously, what to check, in what order, and what the output should look like.
Mechanics & Interactions
Reliable step structure comes down to a small number of habits, applied consistently.
One action per step. If a step contains "and" joining two genuinely separate actions, it's usually two steps. "Read the notes and draft a summary" hides an entire step (deciding how to group the notes) inside a single line.
Concrete verbs over vague ones. "Handle formatting appropriately" and "review for issues" are common phrases that sound like instructions but don't actually specify an action. Replace them with the actual check: "apply the house style guide," "flag any function longer than 40 lines."
Explicit branches instead of buried conditions. When a task genuinely forks based on the input, write the fork as its own step with labeled sub-paths, not as a clause inside a longer sentence.
3. Check the transcript length.
3a. If under 500 words, summarize in a single paragraph.
3b. If 500 words or more, summarize with one paragraph per topic discussed.This is more verbose than "summarize appropriately based on length," but it removes the guesswork that causes different runs to draw the line in different places.
A defined ending. The last step should describe exactly what gets produced - its shape, not just "wrap up." "Output the four fields above as a short structured summary" leaves far less room for drift than "provide your findings."
Step granularity should match real variability, not habit. A task with one fixed path needs fewer, coarser steps. A task that genuinely branches on real-world variation needs that variation spelled out. Adding numbered steps to a task that has no real decision points just adds noise.
Too coarse: "1. Review the document and summarize it."
Too fine: "1. Open the document. 2. Read the first sentence.
3. Read the second sentence. ..."
Right-sized: "1. Read the full document. 2. Identify the three main
claims. 3. Summarize each claim in one sentence.
4. Output the three sentences as a numbered list."Advanced Considerations & Applications
As instructions grow past a handful of steps, two additional structural choices start to matter: grouping and referencing.
Grouping related steps under sub-headings keeps a long instruction body scannable, the same way a long document benefits from section headers rather than one continuous list.
## Instructions
### Gathering Input
1. Read the provided notes or transcript.
2. Confirm the input includes a date range; if missing, ask for it.
### Producing the Summary
3. Group items into shipped, in progress, and blocked.
4. Draft three to five sentences per group.
### Finishing
5. Output the grouped summary as the final response.Referencing bundled files by name, not inlining everything, keeps the main step list focused on the sequence of actions rather than the full detail of any one of them. A step like "apply the formatting rules in style-guide.md" points Claude to load that file only when it's actually needed, rather than forcing every run to read reference material the task might not require.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Flat numbered list | Simple to write and scan | Gets unwieldy past ~8-10 steps | Short, linear tasks |
| Grouped steps under sub-headings | Stays readable as the task grows | Slightly more structure to maintain | Multi-phase tasks (gather, process, output) |
| Steps that reference bundled files | Keeps the main list short; detail loads only when needed | Requires the bundled file to exist and be named clearly | Tasks with large reference material (style guides, schemas, templates) |
A useful habit once a step list is drafted: read it as a checklist a new teammate could follow without asking a clarifying question. Any point where you'd expect a "wait, what does that mean?" is a step that needs to be more concrete, split into a branch, or reworded with a specific verb.
Instructions also benefit from the same iteration mindset as descriptions. Running the Skill against a few real, varied inputs and comparing the outputs for unwanted inconsistency is the most reliable way to find steps that are actually vaguer than they looked on paper.
Common Misconceptions
- "Well-written prose is just as reliable as numbered steps." - Prose can be well-written and still leave the actual sequence of actions ambiguous, since natural language doesn't force an explicit order the way a numbered list does.
- "More steps always means more reliability." - Padding a simple, linear task with excessive granularity adds noise without adding consistency. Granularity should track real decision points in the task.
- "Branches make instructions too complicated to be worth writing out." - An unwritten branch doesn't disappear, it just gets resolved inconsistently at run time. Writing it out explicitly is what removes the inconsistency.
- "The instructions just need to describe the goal, not the process." - A clear goal without a clear process still leaves the actual path to that goal underspecified, which is exactly what produces run-to-run drift.
- "If the Skill works once, the instructions are fine." - A single successful run doesn't test consistency. The real test is whether several different but similar inputs all produce results shaped the same way.
FAQs
Why do numbered steps produce more consistent results than a paragraph?
A numbered list forces an explicit order and a discrete action per step, removing the guesswork a paragraph leaves about what happens first, what happens next, and where the task actually ends.
How do I know if a step is too vague?
- If it uses a phrase like "handle appropriately," "review for issues," or "wrap up," it's describing an outcome rather than an action.
- The fix is to replace it with the specific check or action that phrase was standing in for.
Should every "and" in a step be split into two steps?
- Not always, but if the two halves are genuinely separate actions rather than one continuous action, splitting them into their own steps usually improves reliability.
How should I write a branch in the instructions?
Write the fork as its own step with labeled sub-paths (like 3a and 3b), stating the exact condition that decides which path applies, rather than folding the condition into a single dense sentence.
What should the last step in a list do?
- Describe exactly what gets produced and in what shape, so there's no ambiguity about when the task is complete.
Is there an ideal number of steps for a Skill's instructions?
There's no fixed number - the right count matches the task's real complexity. A simple linear task might need four or five steps; a multi-phase task might need more, ideally grouped under sub-headings.
When should steps be grouped under sub-headings instead of left as one flat list?
- Once a step list grows past roughly eight to ten items, or the task naturally has distinct phases (gathering input, processing, producing output), grouping under sub-headings keeps it scannable.
How do I test whether my instructions are reliable?
Run the Skill against a few real, varied inputs and compare the outputs. Unwanted differences in shape or approach between runs point to a step that's vaguer than it looked when written.
Should instructions reference bundled files directly, or repeat their content inline?
- Referencing a bundled file by name (like a style guide or schema) keeps the main step list focused and lets Claude load the detail only when a step actually calls for it.
What's the difference between a well-structured instruction and a checklist a teammate could follow?
Ideally there isn't one - a good test for instruction quality is whether a new teammate could execute the steps without needing to ask a clarifying question about what any given step means.
Does adding more detail to every step always improve reliability?
- No. Detail should track real variability in the task. Adding exhaustive detail to a step that has no real decision point just makes the instructions longer without making the output more consistent.
Related
- Skill Design & Packaging Basics - a first working example of a short step list.
- Writing an Effective Skill Description That Claude Will Trigger On - what has to succeed before these steps ever get read.
- Walkthrough: Bundling Reference Files and Scripts Into a Skill Package - how to reference detail from within a step.
- Scoping a Skill's Tool Access With allowed-tools - constraining what a step is even allowed to do.
- Anatomy of a SKILL.md File - where the instruction body sits within the full file.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.