Skill Anatomy

The Whole Skill, at a Glance

The previous lesson covered the two lines every SKILL.md needs — name and description. This lesson zooms out to the rest of the folder: what a complete skill can contain, and how the pieces relate to each other before you build one in the next lesson.

pdf-processing/
├── SKILL.md          # Required: metadata + instructions
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
├── assets/             # Optional: templates, resources
└── ...                 # Any additional files or directories

Only SKILL.md is required. A skill with nothing else — just that one file — is completely valid, and you’ll build exactly that in the next lesson. The other three folders exist for when a skill needs more than instructions alone can carry.

The Body: Where the Instructions Live

Everything after the frontmatter’s closing --- is the skill’s body — plain Markdown, no format restrictions. This is where you tell the agent what to actually do. In practice, the sections that work best are:

• Step-by-step instructions
• Examples of input and output
• Common edge cases and how to handle them

One thing does constrain the body, though: when a skill activates, the agent loads the entire body into context — there’s no partial loading of SKILL.md itself. That’s the reason the other three folders exist: to hold everything that doesn’t need to load every single time.

scripts/ — Executable Code

Code the agent can run: a Python script, a shell command, a small utility. Useful when a task needs something more reliable than an agent improvising a command from scratch each time — the same validation logic, written once, run the same way every time it’s needed.

references/ — Documentation on Demand

Additional documentation the agent reads only when it needs to: a detailed technical reference, a form template, notes on a specific edge case. The key property of references/ is that its files load only when the body tells the agent to read them — not automatically, not every time the skill activates.

assets/ — Static Resources

Templates, schemas, lookup tables, example files — material the agent’s output is built from or checked against, rather than instructions it reads.

You’ll build with all three of these directly in Files & Resources later in this course. For now, the mental model is enough: the body is what loads every time the skill activates; everything else loads only when the body says to.

Why the Split Exists

This isn’t an arbitrary organizational convention — it’s what makes a skill scale. If everything lived in SKILL.md, a skill with a large reference manual would cost just as much context on a trivial request as it would on a complex one. Splitting instructions (always loaded) from resources (loaded on demand) is what lets a skill be genuinely thorough without being expensive to activate. You’ll see exactly how this plays out in token terms in the next lesson, Progressive Loading.

A Test for What Goes Where

Before you write a line of a skill’s body, it’s worth asking one question about it: would the agent get this wrong without this instruction?

An agent already knows what a PDF is, roughly how HTTP works, what a database migration does in general terms. It doesn’t know your project’s specific conventions, an unfamiliar internal API’s quirks, or which of three equally-plausible approaches your team has standardized on. A skill earns its keep by supplying the second kind of information, not the first:

<!-- Too verbose — the agent already knows what PDFs are -->
## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. pdfplumber is recommended because it handles most cases well.

<!-- Better — jumps straight to what the agent wouldn't know on its own -->
## Extract PDF text

Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.

Every sentence in a loaded skill competes with the rest of the conversation for the agent’s attention, so this test is worth applying by habit, not just on a first draft: if the answer is no, cut it.

Summary

• Only SKILL.md is required; scripts/, references/, and assets/ are optional additions for when instructions alone aren’t enough
• The body (Markdown after the frontmatter) loads in full every time a skill activates — there’s no partial loading of SKILL.md itself
• scripts/ holds executable code, references/ holds documentation loaded on demand, assets/ holds static resources the output is built from
• Before writing an instruction, ask: would the agent get this wrong without it? If not, it doesn’t belong in the skill

You now know the full shape of a skill. Next, you’ll build one — from an empty folder to a working SKILL.md an agent actually uses.