Design or refactor skills by separating deterministic and non-deterministic steps. Use when creating or improving skills, especially to move repeatable workflows into scripts/ and update SKILL.md to call them.
apm install @kasperjunge/refactor-for-determinism[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@kasperjunge/refactor-for-determinism)---
name: refactor-for-determinism
description: Design or refactor skills by separating deterministic and non-deterministic steps. Use when creating or improving skills, especially to move repeatable workflows into scripts/ and update SKILL.md to call them.
---
# 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