Why Skills¶
A skill's value is a delta: the difference between what your agent does with it and what it does without it. Not "does this skill contain good advice?" but "does the agent behave measurably better when this skill is loaded?" Hold onto that framing — it decides what you write, what you cut, and eventually what you retire.
A skill is an opinionated cheatsheet¶
The Agent Skills open standard defines a skill as a
folder with a SKILL.md the agent discovers and loads on demand. That's the
mechanism. The purpose is narrower and more useful to keep in mind: a skill
encodes what the agent gets wrong without help — the gotchas, the exact
commands, the conditional logic, the "do this, not that" calls that a capable
model still fumbles because they're specific to your domain, your tools, your
conventions.
What a skill is not¶
That purpose draws three boundaries, and each one matters because crossing it quietly taxes every future agent turn or hides the knowledge where the agent can't act on it.
A skill is not documentation. Explanatory prose — the why it works this way, the background, the tour — belongs on a docs site like this one, read by humans on demand. Put it in a skill and it loads into the agent's context on every trigger, competing with the commands that actually change behavior; the reader who needed the explanation never sees it, and the agent that didn't pays for it anyway.
A skill is not a library or CLI. Reusable, testable code belongs in a tools
repo with its own versioning and tests. A skill can call a tool, but if you
find yourself pasting a program into SKILL.md, you've moved code into a place
that can't be unit-tested and will drift from the real thing.
A skill is not a one-off script. If the agent can write it on the spot from the task description, encoding it just spends context to save the model work it does cheaply anyway. Reserve the skill for what the model can't derive: your domain's gotchas, your tools' non-obvious flags, the conventions nobody wrote down. Each of the three has a home; the skill is only for the knowledge the model doesn't already have and can't reconstruct.
The delta, made concrete¶
The workshop's incident_triage skill claims a specific behavior change: given
a vague "bookings are failing" report, the agent should pull firing alerts,
correlate recent deploys, assign a severity, and draft a structured summary.
Run its eval with and without the skill loaded and you get a lift report:
This is demo output, not a measurement
The bundled skilleval.py runs in --demo mode, which simulates both the
agent's trajectory and the judge's verdict — it exists to show you the shape
of the report (cases, pass rates, the lift line), not to measure a real
skill. The +66.7 above is illustrative. Genuine lift numbers only arrive
once the harness is wired to a live agent, which is a tracked Phase 5 task
on the build plan. What is real today is the workflow: run with, run
without, compare, decide.
Read that bottom line as the delta the skill is claiming: without it the agent handles only the easy case, with it all three. Whatever produces the number, the lift is what justifies the context the skill consumes on every turn it's loaded. A skill that can't show a delta is either teaching the model things it already knows or solving a problem nobody has — and in both cases it's costing tokens for nothing.
That last point is mechanical, not rhetorical. A skill's description sits in the agent's system prompt on every request, whether or not the skill ever triggers — that standing presence is how the agent discovers it in the first place (Module 02). So a zero-delta skill isn't neutral: it pays a context cost on every turn and returns no behavior change to offset it. Zero benefit plus a standing cost is strictly negative — an agent carrying a zero-delta skill is measurably worse off than one without it — which is why flat lift is a ship-blocker, not a polish-later. Fix the skill until the delta appears, or don't ship it. This is the thesis the rest of the workshop builds on, and you'll measure it directly in the ablation exercises.
What the delta framing changes about what you write¶
Once you're writing for the delta, most "helpful" content reveals itself as noise. Every line in a skill competes for the agent's context with everything else in the window, so a line that restates what the model already knows isn't neutral — it's a net negative.
<!-- No delta: the model already knows this -->
gRPC is a high-performance RPC framework that uses Protocol Buffers.
Remember to validate your inputs and handle errors gracefully.
<!-- Real delta: a gotcha the model cannot derive -->
`moncli` timestamps are UTC; deployment timestamps are local to the deploy
region. Convert before correlating, or you'll match the wrong deploy.
The first block is training data the model recites on request; loading it changes nothing. The second is a specific, non-obvious failure mode — the kind of thing you only learn by getting burned once — and it visibly changes what the agent does. When you're unsure whether a line belongs, ask the delta question: would removing this change the agent's behavior on a task I haven't tested? If not, cut it.
Key takeaways¶
- A skill earns its place by the measurable delta it produces, not by containing good advice.
- Skills encode what the model gets wrong — gotchas, exact commands, domain logic — not what it already knows.
- If you can't articulate the behavior a skill changes, you can't write a tight one, and you won't be able to evaluate it later.
Drill it¶
ex02_experience_before_theory— attempt a task with no skill, log the failures, and turn that failure log into a first draft. The failures are the delta.ex06_run_ablation— run a skill with and without and read the lift for yourself.
(Exercises unlock in the Exercises section; the cross-linking pass wires direct links once they're built.)