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.