Claude Skills: Packaging Expertise Claude Can Load on Demand

The longer I work with LLMs in production, the more convinced I am that the hard problem isn't the model's raw capability — it's getting the right knowledge into context at the right time. Stuff too much into the system prompt and you pay for it on every single call while drowning the model in irrelevant detail. Stuff too little and the model improvises badly.

Claude Skills are a clean answer to exactly this tension. A Skill is a packaged, reusable capability — a folder of instructions plus optional scripts and resources — that Claude loads on demand only when the task calls for it. In this post I'll explain how they work, why the design is smart, and how to author ones that actually trigger when they should.

The core idea

A Skill is a self-contained folder. At minimum it contains a SKILL.md file with a name, a description, and a set of instructions. Optionally it bundles supporting files: helper scripts, reference documents, templates, examples.

The crucial mechanism is progressive disclosure. Claude doesn't load the full contents of every available Skill into context. Instead:

1. It sees a lightweight index — just each Skill's name and description.
2. When a user's request matches a Skill's description, Claude loads that Skill's full instructions.
3. Only if the task requires them does it reach further into the bundled scripts and resources.

Think of it like a senior engineer's reference shelf. You don't memorize every manual — you know which manual exists and what it covers, then you pull it down only when you need it.

This layering is what keeps the base context lean. The model carries cheap metadata always, and pays the cost of detailed instructions only when relevant.

Why this matters

Three concrete wins, all of which I care about as someone shipping real features:

• Context efficiency. Detailed, multi-page instructions for handling, say, spreadsheets don't sit in your context on every unrelated request. They load only when a spreadsheet task appears. That's lower cost and less distraction for the model.
• Reusability. A capability you've refined once — the right way to structure a report, your team's API conventions, a tricky file format — is packaged so it works the same way every time, instead of being re-explained in each conversation.
• Shareability. A Skill is just a folder. You can version it in Git, review it in a PR, and share it across a team or organization. Expertise stops living in one person's head or one person's prompt history.

The mental shift is this: instead of treating the prompt as one giant blob you constantly tune, you build a library of focused capabilities the model composes as needed.

Anatomy of a Skill

The heart of every Skill is its SKILL.md, which opens with YAML frontmatter declaring the metadata, followed by the instructions in Markdown.

---
name: pdf-form-filler
description: >
  Fills, reads, and flattens PDF forms. Use when the user wants to
  populate a fillable PDF, extract field values from a form, or
  produce a completed PDF from structured data. Handles AcroForm
  fields and checkbox/radio groups.
---

# PDF Form Filler

## When to use this
Use this skill for any task involving fillable PDF forms — populating
fields, reading existing values, or flattening a form so it can no
longer be edited.

## Instructions
1. Inspect the form to enumerate its fields using `scripts/inspect.py`.
2. Map the user's data onto the field names exactly as reported.
3. Fill the form with `scripts/fill.py --in form.pdf --data values.json`.
4. If the user wants a final, non-editable copy, pass `--flatten`.

## Resources
- `scripts/inspect.py` — lists every field name and type.
- `scripts/fill.py` — populates and optionally flattens the form.
- `reference/field-types.md` — notes on tricky field types.

The pieces:

• name — a short, unique identifier for the Skill.
• description — the single most important field. This is the text Claude reads to decide whether the Skill is relevant. More on this below.
• The body — clear, imperative instructions, ideally with a "when to use" section and pointers to bundled resources.
• Bundled files — scripts the model can execute, reference docs it can read, templates it can fill in. These stay out of context until needed.

How Claude decides to use a Skill

This is the part people misunderstand. Skills are model-invoked, not manually triggered by a magic command. Claude is given the list of available Skills (their names and descriptions) and, based on the user's request and the conversation, decides on its own whether any Skill applies.

So the trigger is semantic. If someone says "can you fill out this tax form PDF for me?", and a Skill's description mentions filling PDF forms, Claude recognizes the match and loads it. There's no keyword the user has to type.

That has a direct implication: the description is your routing logic. A vague description means the Skill won't fire when it should, or fires when it shouldn't. A precise one routes cleanly.

Authoring descriptions that trigger correctly

After writing a number of these, here's what reliably works:

• Lead with what it does, then when to use it. "Fills and reads PDF forms. Use when the user wants to populate a fillable PDF..." The model needs both the capability and the trigger conditions.
• Name the concrete nouns and verbs users will use. If the Skill handles Word documents, say "Word document," ".docx," "Word file." The description should overlap with how real requests are phrased.
• State the boundaries. Add what it's not for. "Do not use for PDFs or spreadsheets." This prevents a broad Skill from swallowing tasks meant for another.
• Keep it specific over clever. A description is not marketing copy. Precision beats brevity here.

A weak description like "helps with documents" will misfire constantly. A strong one enumerates the file types, the actions, and the boundaries so the routing decision is nearly unambiguous.

Putting capability in the body

The frontmatter handles discovery; the body handles execution. Once a Skill is loaded, its instructions are what guide Claude through the task. Treat the body like documentation you'd hand a competent new teammate:

## Instructions
1. Always validate the input file exists before processing.
2. For multi-sheet workbooks, confirm which sheet the user means.
3. Use `scripts/transform.py` for the heavy lifting — do not
   reimplement the parsing logic inline.
4. Report a short summary of what changed when finished.

Two practical notes:

• Prefer scripts for deterministic work. If a step is better done by code than by the model reasoning token-by-token — parsing a binary format, doing exact arithmetic, manipulating a file — put it in a bundled script and have the instructions call it. This is more reliable and cheaper.
• Keep the body scannable. Numbered steps, short sections, explicit file references. The model follows structure well.

Use cases where Skills shine

The pattern fits anywhere you have repeatable, specialized procedures:

• Document formats — creating and editing .docx, .pdf, and .xlsx files, where the correct handling involves non-trivial libraries and conventions you don't want re-derived each time.
• Internal workflows — your team's way of writing a release note, filing a ticket, scaffolding a service, or formatting a report.
• Domain conventions — coding standards, API usage patterns, brand or style guidelines that should apply consistently.
• Tool wrappers — codifying the right sequence of commands for a CLI or internal system so the model uses it correctly every time.

In each case the Skill captures expertise once, loads it only when relevant, and applies it consistently.

Final thoughts

Claude Skills reframe prompt engineering as something closer to building a library. Instead of one ever-growing system prompt, you assemble a set of focused, documented capabilities, each carrying a precise description that lets the model route to it on demand. Progressive disclosure keeps the base context lean; the bundled scripts and resources keep execution reliable.

If you start authoring Skills, put your energy into two things: write descriptions precise enough that triggering is nearly deterministic, and push deterministic work into scripts rather than leaving it to the model. Get those right and you end up with reusable, shareable expertise that behaves the same way every time — which is exactly what you want from a capability you're going to lean on in production.