Choosing Determinism
Always choose determinism where determinism is an option. A model step varies
between runs, costs tokens every run, and cannot be tested; a script does none
of that.
Sort every step
Read the whole skill: SKILL.md, its references, and its scripts. For each
step, ask: given the same inputs, must two correct runs produce the same
result? If yes, script it.
| Deterministic: script it |
Judgment: leave to the model |
| Fetching, filtering, sorting, counting, or deduplicating |
Choosing among options or weighing trade-offs |
| Parsing command output, files, or structured data |
Interpreting ambiguous intent or prose |
| Fixed command sequences, above all ordered or destructive |
Writing or reviewing prose and code |
| Resolving paths, names, dates, ages, versions, or IDs |
Deciding whether a finding matters |
| Checking a format, schema, or precondition |
Explaining a result to the user |
| Rendering output whose exact layout a person or parser uses |
Drafting a message whose wording must fit |
Split mixed steps: a script gathers and normalizes the inputs, the model
decides, and a script applies or renders the decision.
Prefer, in order: an existing tool's structured mode (a --json flag, a query
filter, a plumbing command) inside a script; a new script in the skill's
scripts/; model reasoning last.
Writing the script
- A header comment states usage, arguments, output format, and every exit
code.
- Take every input as an argument or on stdin. Never prompt. Read the clock,
randomness, or the environment only when that value is the point, and accept
an override so tests can pin it.
- Print JSON or fixed-format lines in a defined order, with no prose.
- Fail loud: check required tools first, name each error on stderr, and exit
non-zero. Never succeed on empty or malformed input. End each failure with a
pointer to the skill file that explains it, and let a wrapped tool's own
error text through.
- Make writes idempotent. Test with synthetic inputs, each error path included.
Wiring it into SKILL.md
Write "Run scripts/<name> <args>", then what to do with each output and exit
code. Do not restate in prose what the script does; its header documents it.
When determinism is not an option
- When a step looks scriptable but stays with the model, give the reason in one
line so the next editor does not script it.
- Do not fake determinism: a keyword list standing in for reading code is worse
than the model reading it, unless that list is the author's actual rule.
Report
List each step moved to a script, each script added or changed with its tests,
and each scriptable-looking step left to the model with its reason.
1---2name: choosing-determinism3description: Moves each step of an agent skill whose correct result is fixed by its inputs into a script the skill runs, leaving the model only judgment. Use when the user says "script the deterministic steps", or when creating a skill, or adding or changing its steps, commands, or parsing. Not for trimming a skill; use cutting-skills.4metadata:5 source: https://skillmd.com/skills/bostonaholic/choosing-determinism6---78# Choosing Determinism910Always choose determinism where determinism is an option. A model step varies11between runs, costs tokens every run, and cannot be tested; a script does none12of that.1314## Sort every step1516Read the whole skill: `SKILL.md`, its references, and its scripts. For each17step, ask: given the same inputs, must two correct runs produce the same18result? If yes, script it.1920| Deterministic: script it | Judgment: leave to the model |21| ----------------------------------------------------------- | --------------------------------------------- |22| Fetching, filtering, sorting, counting, or deduplicating | Choosing among options or weighing trade-offs |23| Parsing command output, files, or structured data | Interpreting ambiguous intent or prose |24| Fixed command sequences, above all ordered or destructive | Writing or reviewing prose and code |25| Resolving paths, names, dates, ages, versions, or IDs | Deciding whether a finding matters |26| Checking a format, schema, or precondition | Explaining a result to the user |27| Rendering output whose exact layout a person or parser uses | Drafting a message whose wording must fit |2829Split mixed steps: a script gathers and normalizes the inputs, the model30decides, and a script applies or renders the decision.3132Prefer, in order: an existing tool's structured mode (a `--json` flag, a query33filter, a plumbing command) inside a script; a new script in the skill's34`scripts/`; model reasoning last.3536## Writing the script3738- A header comment states usage, arguments, output format, and every exit39 code.40- Take every input as an argument or on stdin. Never prompt. Read the clock,41 randomness, or the environment only when that value is the point, and accept42 an override so tests can pin it.43- Print JSON or fixed-format lines in a defined order, with no prose.44- Fail loud: check required tools first, name each error on stderr, and exit45 non-zero. Never succeed on empty or malformed input. End each failure with a46 pointer to the skill file that explains it, and let a wrapped tool's own47 error text through.48- Make writes idempotent. Test with synthetic inputs, each error path included.4950## Wiring it into SKILL.md5152Write "Run `scripts/<name> <args>`", then what to do with each output and exit53code. Do not restate in prose what the script does; its header documents it.5455## When determinism is not an option5657- When a step looks scriptable but stays with the model, give the reason in one58 line so the next editor does not script it.59- Do not fake determinism: a keyword list standing in for reading code is worse60 than the model reading it, unless that list is the author's actual rule.6162## Report6364List each step moved to a script, each script added or changed with its tests,65and each scriptable-looking step left to the model with its reason.