tools-only Refactor for Determinism
Build reliable skills by separating deterministic steps from judgment-based steps.
Core Principle
Deterministic steps belong in scripts. Use SKILL.md to orchestrate the workflow and reserve judgment for the non-deterministic parts.
Workflow
1. Identify Deterministic vs Non-Deterministic Work
For each step in the skill:
- Deterministic: repeatable, mechanical, or validation-heavy steps → script candidates
- Non-deterministic: judgment, interpretation, creative choices → keep in SKILL.md
Examples of deterministic steps:
- Running quality checks
- Verifying clean git state
- Updating version strings
- Promoting CHANGELOG sections
- Collecting diff context for review
Examples of non-deterministic steps:
- Writing changelog content
- Selecting a solution approach
- Code review judgments
- Deciding release timing
2. Design Scripts for Deterministic Steps
For each deterministic step:
- Create a script in
scripts/within the skill directory - Make it self-contained with clear error messages
- Validate inputs and exit non-zero on failure
- Prefer small, single-purpose scripts
3. Update SKILL.md to Use Scripts
- Replace manual command lists with script calls
- Reference scripts using relative paths:
scripts/... - Keep judgment steps explicit in prose
4. Document Boundaries
Make the line between scripted and non-scripted steps obvious:
- Use section headers like "Deterministic Steps" and "Judgment Steps"
- Call out where human/agent judgment is required
Output Format
## Determinism Audit
### Deterministic Steps (script candidates)
- [Step] → [script name]
### Non-Deterministic Steps (keep in SKILL.md)
- [Step] → [why it needs judgment]
### Script Plan
- scripts/[name] - [purpose, inputs, outputs]
### SKILL.md Updates
- [Where to call each script]
Common Mistakes
| Mistake | Fix |
|---|---|
| Scripting judgment | Keep decision-making in SKILL.md |
| One giant script | Split into small, focused scripts |
| Silent failures | Print clear errors and exit non-zero |
| Hardcoded paths | Use repo-relative paths |
| Forgetting SKILL.md updates | Always wire scripts into instructions |
What NOT to Do
- Do NOT hide decisions inside scripts
- Do NOT make scripts that require manual editing
- Do NOT mix multiple responsibilities into one script
- Do NOT add extra documentation files beyond SKILL.md