Agent Skills

1 · What a Skill is essential

You've explained the same thing to Claude fifteen times this month. "Write the incident report the way we do it — timeline in UTC, cite every claim, no blame language, action items with owners." You paste that paragraph into a fresh chat, tweak it, paste it again next week. It's tribal knowledge trapped in your head and your clipboard, and every teammate re-invents their own slightly-different version. A Skill is the fix: you write that know-how down once, in a file, and from then on Claude reaches for it automatically whenever the task shows up.

Here's the analogy that makes it click. Think of a Skill as a recipe card in a kitchen's recipe box. The chef doesn't memorise every dish or keep all the cards open on the counter — that would be chaos. Instead each card has a title ("Beef Wellington") they can glance at, and only when tonight's order matches does the chef pull that one card and follow it step by step. The full recipe — the technique, the timings, the reference photo — stays folded away until it's actually needed. A Skill works exactly this way: a short label Claude can scan cheaply, and a detailed body it opens only on a match.

The mistake beginners make is reaching for a Skill for everything, or confusing it with the tools they already know. A Skill is not a one-off instruction (that's just a prompt) and it's not always-on project context (that's CLAUDE.md). It's specifically for recurring, specific know-how — a task you do the same way again and again — that you want packaged so it can be versioned, reviewed, and shared like code, yet costs almost nothing when it's not in use. Get that distinction right and Skills become a superpower; get it wrong and you've just made a folder full of prompts nobody triggers. With that framing, here's the precise definition.

An Agent Skill is a folder with a SKILL.md that packages reusable know-how — instructions, and optionally scripts and reference files — that Claude loads on demand when a task matches. It turns "the way we do X" into a versioned, shareable capability.

2 · Anatomy of a Skill essential

The good news you're about to discover: there's no framework to learn here. People hear "Agent Skill" and brace for a config schema, a registry, a build step. There is none. A Skill is a folder with a Markdown file in it. If you can create a directory and write a to-do list, you can write a Skill — and that low ceremony is deliberate, because the whole point is that ordinary teammates author these, not just platform engineers.

Picture it like a labelled folder in a filing cabinet. On the front is a sticky note saying what's inside and when to grab it — that's the metadata. Inside are the actual documents: the main instructions, plus any supporting handouts and a calculator you keep clipped to it. The folder's name is the Skill's name; the sticky note is the trigger; the pages inside are what Claude reads and follows once it opens the folder. Nothing more exotic than that.

Two pieces do all the work, and it's worth naming them before you see the code so you know what to look for. First, the front-matter — a tiny header of name and description — which is the sticky note Claude scans to decide whether this Skill is relevant. Second, the body — plain Markdown instructions below the header — which is the how Claude follows once the Skill fires. The common mistake is pouring all your effort into a beautiful body while writing a lazy one-line description; but a Skill with a perfect body and a vague description is a recipe card with a blank title — it never gets pulled, so its brilliance is never seen. Treat the description as first-class. The layout and the SKILL.md below show both pieces in a real, minimal Skill.

layout.txt.claude/skills/
└── incident-report/
    ├── SKILL.md            # instructions + trigger metadata
    ├── template.md         # a reference the body points to
    └── scripts/
        └── gather_logs.sh   # an optional helper the Skill can run

SKILL.md---
name: incident-report
description: >
  Write a postmortem/incident report in our house format. Use whenever the user
  asks for an incident report, postmortem, or RCA writeup.
---

# Incident report
1. Use the structure in `template.md` (timeline, impact, root cause, actions).
2. If logs exist, run `scripts/gather_logs.sh <service>`.
3. Timeline entries are UTC, newest last; every claim cites a log line or ticket.
4. "Action items" need an owner and a due date each.
5. No blame language — describe systems and events, not people.

3 · Why progressive disclosure matters intermediate

Imagine if your kitchen chef had to read every recipe card in the box, cover to cover, before cooking a single dish. Fifty cards, thousands of words, every night, whether or not any of them applied to tonight's order. The kitchen would grind to a halt — and worse, you'd pay for all that reading even on nights you only served toast. That is exactly the trap a naive Skills system would fall into: load every Skill's full instructions into context on every request. The clever idea that avoids it has a name — progressive disclosure — and it's the single reason a team can install dozens of Skills without every chat getting slower and more expensive.

The principle is simple: reveal detail only when it's needed. What Claude keeps in view at all times is just the sticky note — each Skill's name and one-line description, a handful of tokens apiece. Those tiny labels are enough to answer the only question that matters up front: is this Skill relevant to what the user just asked? If the answer is no, the Skill's full body is never opened, so you never pay for it. If the answer is yes, then Claude reads the full SKILL.md — and only then do any bundled reference files get pulled in, and only if the body actually points at them. It's a three-tier ladder of cost: labels always, body on match, extras on demand.

Why does this deserve its own section rather than a footnote? Because it inverts the intuition most people carry about context. Newcomers assume "more installed Skills = a heavier, slower agent," so they hoard know-how in their head to keep sessions lean — and defeat the whole purpose. The truth is the opposite: because dormant Skills cost only their label, adding the fifty-first Skill is nearly free until the day a task finally matches it. The common mistake, then, isn't installing too many Skills — it's writing bodies so bloated that when one does match, the on-match cost balloons. Keep bodies tight and lean on bundled files for the heavy detail, and the economics stay in your favour at any scale. The little cost model below turns this argument into concrete numbers. Only each Skill's name + description are always in context (tiny). The full body loads only on a match. That's what lets a team ship dozens of Skills without every session paying for all of them — the context-economy lesson from PE2.

disclosure_cost.pydef context_cost(skills, matched):
    """Always-loaded: name+desc (~20 tokens each). Body (~500) only if matched."""
    always = sum(20 for _ in skills)
    bodies = sum(500 for s in skills if s in matched)
    return always + bodies

skills = ["incident-report", "release-notes", "code-review", "data-clean", "sql-style"]
print("all 5 skills, none matched:", context_cost(skills, set()), "tokens (just metadata)")
print("all 5, one matched:       ", context_cost(skills, {"incident-report"}), "tokens")
print("if bodies always loaded:  ", 5*520, "tokens (5x waste)")

all 5 skills, none matched: 100 tokens (just metadata)
all 5, one matched:        600 tokens
if bodies always loaded:   2600 tokens (5x waste)

4 · Advanced — a Skill that bundles a script advanced

Would you ask a brilliant colleague to add up a column of two hundred numbers in their head? Of course not — you'd hand them a calculator. Yet that's exactly what you're doing when you ask a language model to count criticals in a log dump, sort timestamps, or tally null rates by eyeballing text. It can do it, mostly, but it's slow, it's probabilistic, and one day it will quietly miscount and you won't notice. The fix is to let the model do what it's genuinely great at — reasoning and narrating — and hand the exact, mechanical work to code. Skills let you ship that code inside the Skill itself.

A bundled script is the calculator clipped to the recipe card. When the Skill's instructions say "run scripts/summarize.py on the CSV," Claude executes real, deterministic code and reads back a trustworthy result — the same answer every single time, no drift, no hallucinated totals. Then the model reasons over that reliable output and writes the human-facing summary. You get the best of both worlds: the precision of a program and the fluency of a model, glued together by the Skill. And thanks to progressive disclosure, the script sits idle at zero cost until the body actually references it (that's the Tier-2 loading from the last section) — so bundling helpers never bloats your context, it only pays off when used.

The habit to build — and the mistake to avoid — is treating the helper like throwaway glue. It isn't; it runs with your agent's permissions and it runs unattended, so write it as a clean, testable unit you'd be comfortable importing anywhere (the same discipline as any command-line tool in DF1). Give it a clear input and output, no hidden side effects, and a shape you can unit-test on its own before a Skill ever calls it. A sloppy helper that crashes on odd input turns a helpful Skill into a landmine. The example below is a helper an incident-report Skill might ship — deliberately small, pure, and runnable on its own so you can see exactly what "clean and testable" looks like.

skill_helper.py# scripts/summarize_incidents.py — a helper the incident-report Skill calls
def summarize(events):
    """events: [(ts, service, severity)] -> a timeline + a headline count."""
    events = sorted(events)                       # chronological
    crit = sum(1 for _,_,sev in events if sev == "critical")
    timeline = [f"{ts} UTC — {svc} ({sev})" for ts, svc, sev in events]
    return {"critical_count": crit, "timeline": timeline}

r = summarize([("10:05","api","critical"), ("10:01","db","warning"), ("10:12","api","critical")])
print("criticals:", r["critical_count"])
for line in r["timeline"]: print(" ", line)

criticals: 2
  10:01 UTC — db (warning)
  10:05 UTC — api (critical)
  10:12 UTC — api (critical)

5 · Distributing Skills advanced

A Skill that lives only on your laptop helps exactly one person. You wrote the perfect incident-report Skill, it fires beautifully, your postmortems are consistent and fast — and your five teammates still each hand-roll their own, because they've never seen yours. The whole value proposition of Skills is that know-how becomes shared: "the way we do X" turns into a default the whole team inherits without a meeting. That only happens if the Skill lands somewhere everyone's Claude can find it — which is what distribution is about.

The key idea is scope: where a Skill lives determines who gets it, and it maps cleanly onto how a company shares anything. A Skill committed into a repo's .claude/skills/ is like a document in the team's shared drive — clone the repo and it's just there, same version for everyone. A personal Skill in your own user config is like a note in your private notebook — it travels with you across every project but nobody else sees it. And a plugin-bundled Skill is like a published library on an internal registry — anyone across the org who installs the bundle picks it up. Same file, three different blast radii, chosen by where you put it.

The mistake here is thinking of distribution as a mechanical afterthought — just git add and move on. It's actually a governance decision, and picking the wrong scope has real consequences. Commit a half-baked Skill to the project scope and you've foisted your experiment on everyone's session; keep a genuinely useful one personal and the team keeps duplicating it. There's also a security dimension the moment a Skill leaves your machine: a shared Skill's bundled scripts run with each installer's agent permissions, so distributing one is closer to publishing a dependency than emailing a doc — it deserves the same review. The table below lays the three scopes side by side; match the scope to how widely the know-how should actually travel.

6 · Professional — write a triggering description professional

Here's the most heartbreaking way a Skill fails: it works perfectly and never runs. The body is flawless, the bundled script is tested, the folder is committed — and then it just… sits there. Weeks pass. Nobody's postmortems improve. The Skill is dormant, because the one line that decides whether Claude ever opens it — the description — was too vague to match anything. All that effort, invisible. This is far and away the number-one Skill bug in practice, and the whole cure lives in a single sentence you have to get right.

Recall from the anatomy section that the description is the only part of a Skill always in context — the sticky note on the folder. That makes it the entire trigger signal: Claude fires the Skill by matching your task against that one line and nothing else. So the description isn't a summary, it's a trigger, and those are different jobs. A summary answers "what is this?" ("Helps with spreadsheets"). A trigger answers "when should I reach for this?" ("Use whenever the user asks to create, edit, or export an Excel file"). The failing descriptions are the ones written as summaries — they describe a capability floating in the abstract, giving Claude no situational cue for when it applies, so it never applies.

The reliable pattern is to name the situation in the user's own words: lead with "use when" or "use whenever the user asks for…" and then list the concrete nouns a real person would type — report, review, summary, postmortem, RCA, clean, format. Those task words are the hooks Claude latches onto. The opposite mistake, worth guarding against too, is a description so broad it fires on everything and collides with your other Skills — a trigger that's always on is as useless as one that's never on. Aim for the narrow band in between: specific enough to fire exactly when it should, and not a token more. The lab below is a small "linter" that scores a description on precisely these traits, so you can catch a dead trigger before you ship it rather than months later.

desc_score.pydef score_description(desc):
    d = desc.lower(); score, notes = 0, []
    if "use when" in d or "use whenever" in d: score += 1
    else: notes.append("say WHEN to use it (\"use whenever...\")")
    if len(desc) >= 40: score += 1
    else: notes.append("too short — name concrete triggers")
    if any(w in d for w in ["report","review","summary","writeup","clean","format"]):
        score += 1
    else: notes.append("name the task nouns users will say")
    return score, notes

print(score_description("Writes stuff"))
print(score_description("Write an incident report/postmortem. Use whenever the user asks for an RCA or postmortem writeup."))

(0, ['say WHEN to use it ("use whenever...")', 'too short — name concrete triggers', 'name the task nouns users will say'])
(3, [])

7 · Tech-lead — a Skills library for the org tech-lead

Think about what walks out the door every time a senior engineer leaves. The way they wrote incident reports, the SQL conventions they enforced in review, the release-note format everyone quietly copied from them — years of "how we do things here" that lived only in their habits. Onboarding a new hire means someone re-teaching all of it by osmosis, imperfectly, over months. A curated Skills library is the tech-lead's answer to that leak: it captures the team's recurring know-how as code you can commit, so it survives turnover and every new person inherits it on day one instead of year one.

The mental model that matters at this altitude is that a Skills library is a shared codebase, and it needs the same governance. A folder of uncoordinated Skills rots exactly like a folder of uncoordinated scripts: nobody owns them, two of them quietly overlap and fight to trigger on the same task, and half of them stopped firing months ago and no one noticed. So the lead's job isn't to write every Skill — it's to run the library like a maintainer runs a repo. One clear owner per Skill. Descriptions deliberately kept non-overlapping so triggering stays predictable and two Skills never collide. Review before merge, versioning, and a quiet deprecation path for Skills that have gone dark.

The judgement call underneath all of it — and the common mistake juniors make — is deciding what even deserves to be a Skill. The temptation is to skill-ify everything, which just recreates the sprawl you were trying to avoid. The discipline is a decision rule: promote know-how to a Skill only when it recurs, is situation-specific enough to write a clean trigger for, and ideally benefits from a deterministic bundled step. One-off work is cheaper as a direct instruction; borderline cases often belong in a slash command or a line of CLAUDE.md, not a full Skill. Get that gate right and the library stays lean and trustworthy; skip it and you're back to tribal knowledge, just with more folders. The exercises that follow put both halves — the decision rule and the governance policy — into practice.

# .claude/skills/commit-style/SKILL.md
---
name: commit-style
description: Write conventional-commit messages. Use when composing a git
  commit message from a diff.
---

Format: `type(scope): summary` where type is feat|fix|docs|refactor|test.
- Summary in imperative mood, <=72 chars, no trailing period.
- Add a body only when the "why" isn't obvious from the summary.

Tier 0 (always):  the skill's `description` line only  -> cheap, always in context
Tier 1 (on use):  the full SKILL.md body                -> loaded when relevant
Tier 2 (on demand): bundled files/scripts the body points to -> read as needed

def context_cost(stage):
    return {"idle": "description only",
            "triggered": "description + SKILL.md body",
            "deep": "description + body + referenced files"}[stage]
print(context_cost("idle"))       # description only
print(context_cost("triggered"))  # description + SKILL.md body

.claude/skills/csv-report/
  SKILL.md
  scripts/summarize.py       <- bundled helper

# SKILL.md body excerpt:
To summarize a CSV, run the bundled script:
    python scripts/summarize.py <path-to-csv>
It prints row count, column types, and per-column null rates.
Read its output, then write the narrative summary.

Weak:   description: "Helps with spreadsheets."
        -> too vague; the model can't tell when it applies.

Strong: description: "Generate .xlsx spreadsheets with formulas and charts.
         Use when the user asks to create, edit, or export an Excel file
         or a report as a spreadsheet."
        -> names concrete triggers (create/edit/export .xlsx), so the
           model loads it exactly when relevant.

Distribution checklist:
  [ ] Skill is a self-contained folder (SKILL.md + any scripts).
  [ ] Description is specific enough to trigger correctly (see expert rung).
  [ ] Bundled scripts are reviewed — they run with the agent's permissions.
  [ ] No secrets, no network calls to untrusted hosts inside scripts.
  [ ] Versioned in a shared repo / registry; pin a version when installing.
  [ ] A short README: what it does, when it triggers, what it can touch.

def is_skill_worthy(repeated, situation_specific, needs_deterministic_step):
    if not repeated:
        return "NO — one-off; a direct instruction is cheaper than a skill"
    if situation_specific or needs_deterministic_step:
        return "YES — recurring, clearly-triggered; bundle a script if it "\
               "needs deterministic work"
    return "MAYBE — could be a slash command instead of a full skill"

print(is_skill_worthy(True, True, True))    # YES
print(is_skill_worthy(False, True, False))  # NO

# Governance: one owner per skill; non-overlapping descriptions (so two
# skills don't fight to trigger); review + version in a shared repo;
# deprecate skills that stop triggering.

Knowledge check check yourself