Should a Step in Your Bot's Skill Be a Script or a Paragraph of Prose?

The decision: how much latitude should this step have?

Anthropic's skill authoring guidance frames this as a single question you answer separately for every step in a Skill, not once for the whole file. The guidance tells authors to match the level of specificity in an instruction to the task's fragility and variability.

The top tier is high freedom: plain text instructions used when multiple approaches are valid and the model should decide the path. Anthropic's own example is a code review: check structure, look for bugs, suggest readability improvements, follow project conventions. None of those steps have one correct sequence, so prose that states the goal is enough.

The bottom tier is the opposite: an exact script, run verbatim, for anything where a slip is expensive or hard to undo. The guidance recommends pre-made utility scripts over asking the model to generate equivalent code on the fly, because a script is more reliable than generated code, saves tokens since its contents never have to enter context, and produces consistent output run after run.

Sources: Skill authoring best practices - Claude Platform Docs.

A worked example: one invoicing skill, three freedom levels

Illustrative example. Suppose a small-team bot has a Skill for monthly client invoicing. It has three steps: draft a cover note, fill in line items from a timesheet export, and submit the invoice to the payment processor.

Drafting the cover note is a high-freedom step. Tone, length, and which project highlights to mention all vary by client, and getting it slightly wrong costs nothing more than a quick edit. Prose instructions describing the goal are enough here.

Filling in line items is a medium-freedom step. There's a preferred format and a fixed set of fields, but the number of line items and their order still vary by invoice. A parameterized template or pseudocode step fits: a fixed shape, with room to vary the contents.

Submitting the invoice to the payment processor is the low-freedom step. A wrong amount, a duplicate submission, or the wrong recipient account is expensive and sometimes irreversible. This is the step Anthropic's guidance says belongs in a literal script that the model runs rather than reasons through, with the execution intent stated explicitly, for example an instruction to run a named submission script rather than to write equivalent code inline.

The point of the example is that a single Skill can and usually should mix all three levels. Writing the whole invoicing Skill as one tier, either all prose or all scripts, is where this goes wrong in practice: all-prose makes the submission step unreliable, and all-script makes the cover note sound robotic and brittle to small client-by-client variation.

Sources: Skill authoring best practices - Claude Platform Docs.

What goes wrong when the tier is mismatched

Too much freedom on a fragile step produces inconsistent output: the model takes a different path each run, and on a payment or deletion step that inconsistency is the actual risk, not just an annoyance.

Too little freedom on a judgment call produces brittle failures: a rigid, over-specified procedure for something like a code review breaks the moment a repository doesn't match the assumed structure, because the step has no room to adapt.

Anthropic's guidance also recommends a safeguard that applies regardless of tier: build in verifiable intermediate outputs so the model, or a human, can catch a mistake mid-task rather than only after the Skill finishes. This matters most on the steps you've deliberately made low-freedom, where a wrong intermediate result is exactly the kind of error a fixed script won't catch on its own.

For a bot builder, the practical check is to look at each step and ask whether a mistake there is cheap to fix (lean toward prose) or expensive to fix (lean toward a script), rather than deciding the whole Skill's style in one pass.

Sources: Skill authoring best practices - Claude Platform Docs.

Why this also affects your bot's context budget

The freedom-level decision isn't only about reliability; it changes how many tokens a Skill costs to run. Anthropic's Skills documentation describes three loading levels: metadata is always loaded at roughly 100 tokens per Skill, the SKILL.md body loads only when the Skill triggers and should stay under about 5,000 tokens, and bundled resources or scripts load only as needed.

A script sits outside that budget almost entirely. Because only the script's output, not its source, enters context when Claude executes it, a low-freedom script step is often the cheaper option even though it looks like more work to write up front. A prose step for the same task has to spend tokens describing every edge case to get consistent behavior, which can end up costing more context than the script would have.

This gives a second, practical reason to push fragile or repetitive steps toward scripts: it isn't only about correctness, it's about not burning the shared context budget re-explaining the same procedure the model already executed reliably last time.

Sources: Skill authoring best practices - Claude Platform Docs, Agent Skills - Claude Platform Docs.

A checklist for writing or auditing a Skill step

Apply this per step, not per Skill file, when writing a new Skill or reviewing one a teammate wrote.

First, ask what happens if this step goes slightly wrong. If the answer is 'nothing much,' it's a candidate for high freedom. If the answer is 'money moves, data is deleted, or a message goes to the wrong person,' it belongs at low freedom with a script.

Second, check whether a preferred pattern already exists for the step but some variation is still acceptable, such as a report format with a flexible number of sections. That middle case is where a parameterized template earns its place instead of either plain prose or a rigid script.

Third, for any step you push to low freedom, confirm the instruction states whether the model should execute the script or merely read it as a reference for complex logic, since Anthropic's guidance notes execution is usually preferable for reliability and efficiency, and an ambiguous instruction here can lead the model to regenerate the logic instead of running the trusted script.

Sources: Skill authoring best practices - Claude Platform Docs.