Decide when a script beats prose

Don’t add a script because skills have a scripts/ folder. Add one when you watch the agent rebuild the same deterministic step, run after run.

What makes a good script

Good candidates parse a known format, validate a structured output, compute something, or convert one format to another. The common thread: given the same input, the output is always the same. No judgment involved.

The release-readiness skill doesn’t need a script to run Git or the test suite. The agent and the project’s own tooling already know how. It does benefit from a validator that checks whether the final report has every required section and a valid decision. That’s mechanical, and the agent would otherwise re-derive it every time.

What stays in prose

Judgment stays in prose. A script can’t decide whether a deprecation warning blocks this particular release. That depends on the project, the version, and what the team agreed. You could encode that policy in code, but then the policy hides in a file nobody reads. Keep it visible in the instructions and in the report.

Three questions before writing code

Compare the options in this order:

1. Can one precise instruction solve it?
2. Does the repository already provide the command?
3. Would a bundled script give a more consistent, testable result?

Pick the smallest option that works. A script is code you have to maintain, document, and secure. Prose is cheaper until it isn’t.

Look at real runs

Here’s how I decide. Run the skill twice and read both traces. Every time the agent writes throwaway parsing or checking logic, mark it.

This is the kind of thing you’ll find:

> Checking report has "## Decision" heading... found
> Checking report has "## Evidence" heading... found
> Checking report has "## Blockers" heading... missing

Same logic, written from scratch in both runs, slightly different the second time. That’s the signal. A deterministic step, repeated, with drift. It becomes a script.

If the two runs differed because the tasks were different, keep the flexibility. Don’t freeze a step that needs to adapt.

The project’s script

For our skill, the script is scripts/validate-report.mjs. Its only job is to check the structure of the report: the headings exist, the decision is one of GO, NO-GO, or NEEDS REVIEW.

One rule I’d write in bold at the top of the file: it must never infer GO from the presence of headings. A report with all the right sections and no evidence is still a bad report. The validator checks shape. The agent, and you, check substance.