You have 30+ skills in production. They work. But "works" isn't the bar anymore — predictable is. This lesson gives you the vocabulary to reason about why a skill steers well or drifts, and a framework for auditing any skill file in under two minutes.
The vocabulary comes from Matt Pocock's skills repo — 314 commits over 6 months of one person discovering, through iteration, what makes a skill predictable. He distilled it into four axes.
The Four Axes
Every skill can be evaluated along four independent dimensions. Each axis has concepts (tools) and failure modes (anti-patterns). Think of them as lenses — you rotate through all four when auditing.
1. Invocation
How a skill is reached, and the load you pay for that reach.
Model-Invoked — agent fires it autonomously (pays context load)
User-Invoked — human types its name (pays cognitive load)
Context Load — the always-on cost of a description, every turn
Cognitive Load — human must remember it exists
Router Skill — one entry point that maps to many
Granularity — how finely you split (more splits = more load)
2. Information Hierarchy
How a skill's content is arranged, from primary steps down to disclosed reference.
Steps — ordered actions (primary tier)
Reference — material referred to on demand (secondary)
External Reference — lives outside the skill system entirely
Progressive Disclosure — push detail behind a pointer
Co-location — keep related info under one heading
Sprawl — simply too long; cure by disclosure + splitting
3. Steering
The levers that shape runtime behaviour toward predictability.
Branch — a distinct case the skill handles
Leading Word — a concept from pretraining that anchors behaviour cheaply
Completion Criterion — what tells the agent a step is done
Legwork — work the agent does within a step (not offloaded to user)
Premature Completion — ending before genuinely done
Negation — naming what NOT to do makes it more available
4. Pruning
Keeping a skill lean — each remedy paired with the failure it exists to cure.
Single Source of Truth — each meaning in one place
Relevance — does this line still bear on what the skill does?
Duplication — same meaning in multiple places
Sediment — old content never cleared; adding feels safe, removing feels risky
No-Op — instruction that changes nothing (model does it by default)
Applying the Axes: A Live Audit
Let's audit a real skill from your repo. Here's your handoff skill:
~/.kiro/skills/handoff/SKILL.md (description)
Compact the current conversation into a handoff document
for another agent session to pick up. Use when ending a
session, switching context, or preparing work for a fresh agent.
~/.kiro/skills/handoff/SKILL.md (workflow)
1. Save the handoff to a path produced by `mktemp -t handoff-XXXXXX.md`
2. Suggest which skills the next session should use
3. Do not duplicate content already in PRDs, plans, ADRs,
issues, commits, or diffs — reference them by path or URL instead
4. Redact any sensitive information, such as API keys,
passwords, or personally identifiable information
5. If the user passed arguments, treat them as a description
of what the next session will focus on and tailor the doc accordingly
Axis-by-axis reading
Axis
Observation
Verdict
Invocation
disable-model-invocation: true — user-invoked. Zero context load. Human must remember to use it.
✅ Appropriate — handoff is a deliberate action, not something the agent should do autonomously.
Hierarchy
Has an Interface table (reference) + a Workflow (steps). Reference comes before steps.
⚠️ The Interface table is useful but sits above the workflow. A reader (the agent) hits 10 lines of schema before knowing what to do. Consider whether the table is needed at all — the workflow's step 1 implies the shape.
Steering
Step 3 is a negation: "Do not duplicate…". Step 4 is a positive instruction: "Redact". Step 5 is a branch (if user passed args).
⚠️ Step 3 uses negation — names what not to do, which drags duplication into the frame. Reframe positively: "Reference existing artifacts by path or URL." Step 5 is a clear branch — good.
Pruning
Compact skill (5 steps). No obvious sediment. But: the Interface table partially duplicates the workflow steps (both say "summary", "next_steps", etc.).
⚠️ Mild duplication between table and workflow. The table is a form of reference; if the agent already knows what fields to produce from the objective, the table may be a no-op.
Key insight
The handoff skill is solid — but the audit found two micro-improvements in 30 seconds: reframe the negation in step 3, and evaluate whether the Interface table earns its lines. This is the power of having vocabulary: you see what you can name.
The Audit Discipline
Now you have a repeatable method. For any skill, in under two minutes:
Invocation: Is it model-invoked or user-invoked? Does that match how it should be reached? Is the description pulling its weight?
Hierarchy: Can you find the steps in 3 seconds? Is reference disclosed progressively, or does it sprawl upfront?
Steering: Scan for negations (flag them). Check each step's completion criterion — is it clear when the agent is "done"? Look for leading words that anchor behaviour.
Pruning: Any line that says what the model would do anyway? Any meaning stated twice? Anything stale?
Check Your Understanding
A skill has the instruction: "Never use console.log for debugging." What failure mode does this exhibit?
Sprawl — the skill is too long and needs splitting
Negation — naming what not to do makes it more available
No-Op — the model already avoids this by default
Premature Completion — the step ends before it's done
Correct. Negation drags the prohibited action into the model's attention. Reframe positively: "Use the debugger or structured logging for debugging." The model now has a target instead of an avoidance.
Not quite. This is negation — the instruction says what NOT to do, which makes the prohibited thing more salient. It's not sprawl (length) or no-op (default behaviour). The cure is to state the positive target instead.
You add "Always write clean code" to a skill's rules. Which failure mode is this?
Duplication — the same meaning exists elsewhere in the skill
Sediment — layers of old content that never get cleared
No-Op — the model already does this by default; you pay context for nothing
Negation — you're naming what not to do by implication
Correct. "Write clean code" changes nothing — the model already optimises for this. You spend context tokens to say what would have happened anyway. Delete it.
This is a No-Op. The instruction doesn't change behaviour because the model already aims for clean code by default. It costs context tokens without adding steering value.
A model-invoked skill has a 200-word description that the agent loads on every turn. What concept describes the cost of keeping this loaded?
Context Load — the always-on cost a model-invoked skill pays per turn
Cognitive Load — the cost on the human remembering the skill exists
Sprawl — the skill file is simply too long overall
Progressive Disclosure — reference should be pushed behind a pointer
Correct. Context Load is what model-invoked skills pay: their description occupies space on every single turn, whether they're needed or not. If the skill is rarely used, it's paying rent for an empty room.
This is Context Load — the specific cost that model-invoked skills pay by keeping their description in the agent's context every turn. Cognitive Load is the human-side equivalent. Sprawl refers to the full skill length, not just the description.
Your Exercise
Pick any skill from ~/.kiro/skills/ and run the four-axis audit. Write down one finding per axis. If you find a negation, rewrite it as a positive instruction. Bring your notes to the next session — we'll refactor one together.
Questions? Ask me anything that's unclear — the vocabulary, how to apply an axis to a tricky skill, or whether a specific instruction in your skills is a no-op. I'm your teacher.