A stable skill is not a well-written prompt. It is a small piece of engineering: defined boundaries, explicit contracts, ordered actions, failure recovery, and tests. Here is what each part does and why skipping it breaks the skill.
Scope
The scope is the boundary. A stable skill states what it does in one sentence and lists at least three things it does not do. Scope is what makes testing possible: if you cannot describe the bounded behavior, you cannot test it. When a skill drifts, the first repair is narrowing the scope.
Input contract
The input contract names what the skill accepts and what it assumes. Without it, the skill interprets vague input differently on every run. A stable skill answers: what must be provided, what has a default, and what will be rejected.
Actions
Actions are the ordered steps with their tools, inputs, and expected outputs. The key property is determinism: the same input should produce the same outcome. Vague steps are where determinism dies. “Review the code” produces different work every run. “Run the type check, list each error, and fix them in dependency order” is repeatable.
Failure handling
Real runs fail. A stable skill documents its failure modes and a recovery step for each one: what can go wrong, what to do, and when to stop and ask a human. The presence of failure handling is a quality signal on its own. A skill that has never considered failure will fail in production.
Human checkpoints
Some steps should not be automated. Checkpoints mark the moments where a human must confirm: approving scope, reviewing a design direction, accepting a deliverable. Skills that skip checkpoints remove judgment from decisions that need it.
Output contract
The output contract states what the skill delivers and in what form. It is the promise the skill makes. If the output contract says “a deployed site”, the skill must end with a URL and the evidence that it works, not with a summary of what it did.
Tests
The minimum test suite is small and powerful:
- The run-twice test: identical input, diff the outputs. Divergence means underspecification.
- One test per failure mode: trigger the failure, confirm the recovery works.
- The fresh-agent test: someone with no context follows the skill and succeeds.
Tests are what make a skill a product instead of a suggestion. They also make updates safe: when the environment changes, you re-run the suite and see exactly what broke.
The order that works
Scope, then contracts, then actions, then failure handling, then checkpoints, then tests, then documentation. Documentation comes last because it should describe tested behavior. A skill built in this order tends to stay stable, and when it does break, the tests tell you where.