Scripts or instructions: what a skill should do in code
Some steps work better as a script Claude runs than as prose it interprets. Which ones, how to call them from SKILL.md, and what scripts cost elsewhere.
A skill can hold two kinds of instruction: prose Claude interprets, and scripts Claude runs. Mixing them well makes a skill both flexible and reliable.
| Better as a script | Better as instructions |
|---|---|
| Validate a file's structure | Decide what the page should say |
| Pack or format output | Choose a layout for a new screen |
| Check a list of rules mechanically | Judge whether a design reads as generic |
Calling a script from SKILL.md
Before finishing, run `python scripts/check_tokens.py <file>` and fix every line it reports.Name the script, the input and what to do with the output. Claude runs it and works from the result, which is usually shorter than the reasoning it replaces.
The cost: other people's machines
A script that needs a package the user does not have fails on first use, and the user blames the skill. Keep scripts dependency-light, and check requirements with a preflight step that names everything missing at once. Testing on a machine that is not yours is covered in testing on a clean machine.
Questions
When should a skill include a script?
When a step must give the same result every time: validation, formatting, file generation, checks with a clear pass or fail. Prose is better for judgement.
Do scripts save context?
Often. Claude runs the script and reads its output instead of reading and reasoning about the steps inside it.
What is the risk of scripts in a skill?
They run on the user's machine, so they depend on what is installed there. Check dependencies up front and fail with a clear message.