Anatomy of a skill: the SKILL.md dissected

A skill from the outside: a folder, not magic

Before opening the hood, the overview. A skill, on disk, is this:

meeting-summary/
├── SKILL.md          ← the core: frontmatter + instructions
├── scripts/          ← optional: deterministic supporting code
│   └── format_check.py
└── templates/        ← optional: templates, reference examples
    └── example-summary.md

Three observations that frame everything else:

It is text. No binaries, no proprietary format, no compilation. A skill can be read, diffed, and versioned in Git like any other file in the repository. That is a precious property — for review, for audit, for maintenance — and a limit you must know: everything in it will be readable in plain text inside a conversation context.

The SKILL.md is mandatory, the rest is optional. A minimal skill fits in a single file. Scripts and templates only appear when they bring something text cannot guarantee — more on that below.

The folder is self-contained. A well-designed skill does not depend on another skill to work. If you feel the need for an "import", that is the sign of a bad decomposition — back to the drawing board.

The frontmatter: the permanent storefront

Now let's open the file of our connecting thread — the meeting-summary skill we will build for real at step 3. Here is its header:

---
name: meeting-summary
description: Writes meeting summaries in the house format —
  Decisions / Actions / Open points sections, factual tone, one
  page maximum. Use whenever someone asks for a meeting summary,
  minutes, a decision log or a meeting recap.
---

Two fields, and one fundamental asymmetry to understand:

name — the identifier. Short, lowercase, hyphenated. It is used to reference the skill (logs, management, explicit invocation). Purely technical role.

description — the storefront. It is the only part of the skill the model sees at all times. Everything else in the file — the instructions, the examples, the rules — is invisible until the model has decided, on the sole basis of this description, that the skill deserves to be loaded.

Read that last sentence again; it is the central mechanism: the model does not "rummage through" your skills on every request. It consults a catalog of descriptions, and loads — or not.

The description under the microscope

Since everything hinges there, let's dissect the one from our thread. It answers two questions, in this order:

1. What does the skill do? — "Writes meeting summaries in the house format — Decisions / Actions / Open points sections, factual tone, one page maximum." Concrete, specific, verifiable. Not "helps with document writing": that is a description that triggers nothing because it could trigger everything.

2. When to use it? — "Use whenever someone asks for a meeting summary, minutes, a decision log or a meeting recap." Note the choice of words: these are the phrasings users actually type, including "minutes". The description speaks the language of the requests it must intercept.

The comparison that makes the principle obvious:

❌ description: Helps produce quality documents for the team.
   → too vague: never loaded (or wrongly loaded on everything)

❌ description: Summary skill v2, replaces the old version,
   approved by Marc in March.
   → talks about the skill, not the task: the model finds
     no trigger signal in it

✅ description: Writes meeting summaries in the house format
   [...] Use whenever someone asks for a meeting summary,
   minutes, a decision log or a meeting recap.
   → what + when, in the users' own words

The body: the instructions

Once past the frontmatter gate, the body of the SKILL.md is loaded in full. This is where the expertise lives. Here is our thread's body (abridged — the full version is the deliverable of step 3):

# Meeting summary — house format

## Mandatory structure
1. **Context** — one line: date, attendees, purpose.
2. **Decisions** — what was settled. One decision per bullet,
   past tense, no conditionals.
3. **Actions** — who / what / by when. Never an action without
   an owner and a deadline; if either is missing, record it
   under Open points.
4. **Open points** — what remains to be settled, with the
   planned next step.

## Tone and style
- Factual. No commentary, no interpretation of intentions.
- One page maximum. Beyond that, summarize harder — no
  appendices.

## Edge cases
- Raw notes unreadable or contradictory: produce the summary
  of the clear points, explicitly list the gray areas under
  Open points. Never invent a decision.
- Sensitive HR or individual information: do not include it;
  flag its existence to the requester, outside the summary.

Three writing traits to remember, valid for all your future skills:

Imperative and concrete. "One decision per bullet, past tense" — not "decisions should ideally be phrased clearly". A skill is a procedure, not a charter of good intentions.

Edge cases are written down. Contradictory notes, sensitive data: ambiguous situations are settled in the file, calmly, by you — rather than improvised by the model, in the moment, differently each time. That is exactly the value of a documented procedure: repeatability in non-nominal cases. ISO 27001-certified readers will recognize the principle.

Nothing superfluous. Every loaded line costs tokens and attention. Version history, acknowledgments, the project's political context: out. A skill body is judged like a runbook — whatever does not help execution has no place in it.

Bundled scripts: when text is not enough

Last compartment of the folder: supporting scripts. The dividing rule is simple —

Text for judgment, code for determinism.

Writing a synthesis, adapting a tone, settling an edge case: judgment → instructions. Verifying that an output respects a format, converting data, applying an exact transformation: determinism → a script the model executes, rather than an operation it does "in its head" with approximation risk.

In our thread, scripts/format_check.py verifies that the produced summary contains the four sections in order — a mechanical quality control, exactly the kind of task you do not leave to improvisation.

📍 Skills & MCP path — step 2/9

1. 🗺️ The map before the territory
2. 🔬 Anatomy of a skill ← you are here
3. 🛠️ Create your first skill
4. 🏛️ Skills in the enterprise: governance
5. 🔌 MCP: the protocol explained
6. ⚡ Use an existing MCP server
7. ⚙️ Build your minimal MCP server
8. 🛡️ Secure your MCP servers
9. 📡 The ecosystem: where to find, where it moves

Next step → Create your first skill: we write the full version of our connecting thread, from requirements to testing — with the five-step method for a description that triggers every time.

To place this step on the big map: step 1, the map before the territory.