Deep dive · 18 min
What is a skill, and when does it beat a prompt?
You have explained the refund procedure to an agent forty times, once per session. Where should that knowledge actually live?
Assumes Agent loops.
An agent has three places knowledge can live, and they are not interchangeable. The system prompt is always present and read on every call. A tool is something the model can invoke. A skill is a document the agent loads when a task calls for it — procedures, conventions, house rules — and otherwise leaves alone.
The case for skills is mostly economic and organisational. A refund procedure in the system prompt is paid for on every call, including the thousands that are not about refunds. The same procedure as a skill costs nothing until a refund request arrives — and when it is wrong, there is one file to fix, one version to bump, one diff to review.
A good skill has a trigger and a body. The trigger says when to load it: the customer mentions a refund, asks for a manager, reports damage. The body is written as instructions to the agent, not as prose about the topic — numbered steps, what you may say, what you may not, in that order. The lab shows both skills in full; read one before running.
- Procedures belong in skills. The order of operations for a refund is knowledge, not identity.
- Boundaries belong in skills when they are topic-specific, and in the prompt when they are universal.
- Facts that change belong in retrieval, not in skills. A skill is the procedure for looking a policy up, not the policy.
- Anything the model needs on every single call is a prompt. A skill that always loads is a prompt with extra steps.
The lab runs the same agent on the same task twice, bare and with the relevant skill loaded, and sets the traces side by side. On the refund task, during development, the bare agent read the policy, looked up the order, and issued the refund — a side effect, taken, with an empty reply. With the skill it looked up the order, read the policy, checked stock, took no action, and explained eligibility.
It also said "I will now issue a refund", which the skill forbids. That is the honest result: a skill moved the behaviour a long way and did not make it perfect. A skill is a guide in the harness sense — it steers before the action — and it still needs a sensor behind it. The guarded refund tool from the agent-loops course is the precondition — a guide on the tool itself — and the check that it held is the sensor.
Skills are also the unit that makes a team's agent knowledge shareable. A system prompt is one string, owned by whoever wrote it. A skill directory is a set of files with authors, histories and tests — the same shape as any other code, which means the same review process, the same ownership, the same ability to find out who changed the refund procedure and when.
- Keep each skill to one procedure. A skill that covers refunds and escalations will load when neither applies.
- Test a skill the way the lab does: the same task with and without, graded. A skill that does not change the output is documentation, not a skill.
- Version them. When a procedure changes, the skill changes, and old traces should be readable against the skill that was loaded at the time.
- Watch for skills that always load. That is a sign the knowledge belongs in the prompt — or that the triggers are too broad.
Loading a skill is, mechanically, just putting text in context. What makes it a skill rather than a longer prompt is everything around that: the trigger, the versioning, the test, and the fact that it is absent most of the time. The mechanism is trivial; the discipline is the point.