Create your first skill: the five-step method

Why a method, and not just a file

At step 2, you saw the anatomy: frontmatter, description, body, scripts. You might think it is enough to fill in the boxes. That is the trap most first skills fall into — and the reason so many end up as dead files: never loaded, or loaded at the wrong moment, or loaded but betrayed by ambiguous instructions.

A skill is a small object, but a testable one, with a life cycle. The method below treats it as such. Five steps, each with its deliverable and its exit criterion:

Let's walk each step on our connecting thread — the meeting-summary skill — all the way to the complete file at the end of this step.

① Scope: one skill, one task, one criterion

Before writing a single line of the file, a one-page brief answering three questions:

Which task, in the singular? "Write the summary of a meeting from raw notes." Not "manage meeting documentation" (three tasks in disguise: writing, archiving, distributing), not "help the team communicate better" (a wish, not a task). The singular test: if your scoping sentence contains an "and", you probably have two skills.

Which implicit know-how? The most profitable question of the whole brief. Interview the person who does this task well today: what do they know that a newcomer would miss? For our summary: "never an action without an owner and a deadline", "we do not interpret intentions", "HR topics do not go into a distributed summary". These tacit rules are the core of the value — a skill that only captures the obvious is not worth its maintenance cost.

How will the result be judged? An observable criterion, written before you start: "a reader who missed the meeting knows what to do on Monday morning, in under one page". It will serve as the referee at step ④ — without a criterion set calmly in advance, testing becomes a contest of impressions.

Deliverable of step ①: the scoping page. Exit criterion: each of the three answers fits in one sentence.

② Describe: the trigger before everything

Counter-intuitive but crucial: you write the description before the instructions. Because a skill with a perfect body and a failed description is never loaded — it does not exist, as we saw at step 2. Triggering is feature number one; you design it first.

The method in three moves:

Collect real phrasings. Not the ones you find elegant: the ones your users actually type. Gather five to ten authentic requests — Slack messages, emails, tickets. For our thread: "can you do the minutes?", "I need the summary of the product meeting", "send me the decision log", "recap of this morning's meeting please". The trigger vocabulary is in there, not in your head.

Write what + when. First sentence: what the skill produces, concretely. Second: the situations that must trigger it, using the collected words — "meeting summary", "minutes", "decision log", "recap".

Run the gate test. Reread your description asking: for each collected request, would a model that sees only these lines load the skill? And for a neighboring but out-of-scope request — "draft the agenda for the next meeting" — would it let it pass? A good description is a gate: it opens for the scope, it stays shut next door.

Deliverable of step ②: 3 to 5 lines of description. Exit criterion: the gate test passes mentally on your ten collected phrasings.

③ Instruct: the body of the manual

Only now, the instructions. The proven structure — the anatomy from step 2 — in the order the model needs it:

The nominal procedure first — the expected output structure, section by section, with the formal rules ("one decision per bullet, past tense"). This is the happy path, the one of 80% of executions.

Tone and limits next — factual, one page maximum, no interpretation of intentions. Keep it short: every style rule must be justified by a deviation actually observed or genuinely feared.

Edge cases last — and this is where the difference between a decent skill and a production skill is made. Take the implicit know-how from step ① and turn each tacit rule into written conduct: contradictory notes → produce the summary of the clear points and list the gray areas; sensitive information → exclude from the summary, flag to the requester. The golden rule: every ambiguity settled in the file is an improvisation avoided in production.

One complete reference example (a model summary in templates/) is often worth ten extra rules: the model imitates better than it interprets.

Deliverable of step ③: the SKILL.md body + the reference example. Exit criterion: a colleague discovering the skill can execute the task by hand following only the file.

④ Test: triggering first, content second

The step everyone skips — and the one that separates a hobbyist skill from a team skill. Two campaigns, in this order:

Trigger campaign. Build your grid: the five to ten real phrasings from step ② (which must trigger), plus three to five neighboring out-of-scope requests (which must not). Submit them one by one, in fresh conversations, and record: loaded / not loaded. A false negative (legitimate request, skill ignored) is fixed by enriching the description's vocabulary; a false positive (neighboring request, skill wrongly loaded) is fixed by tightening the "when".

Content campaign. Once triggering is reliable — and only then — test output quality against the criterion from step ①: take real meeting notes (including one twisted case: incomplete notes, an HR aside slipped into the middle) and verify the produced summary respects structure, tone and edge cases.

Testing in this order is not methodological fussiness: if you test content first, every iteration on the instructions can also alter triggering behavior you have not yet measured — you are chasing two rabbits. Triggering stabilized, then content: one variable at a time.

Deliverable of step ④: the filled test grid. Exit criterion: 100% of legitimate phrasings trigger, zero false positives on the neighbors.

⑤ Iterate: one deviation, one change

In production, keep a deviation log: every time the skill disappoints (not loaded, badly applied, unforeseen edge case), one line — the request, the observed behavior, the expected behavior. Then, periodically:

• The deviation comes from a failed trigger → adjust the description (often: one word of real vocabulary is missing)
• The deviation comes from a failed execution → adjust the body (often: one edge case to add)
• One change at a time, replaying the step ④ grid after every modification — the grid becomes your non-regression test

And one hygiene habit: date a changelog line at the end of the file. Three months later, knowing why a rule exists prevents deleting it by mistake.

The deliverable: the complete SKILL.md of our thread

Here is the full file, assembled across the five steps. It is your starting template — swap the domain, keep the structure:

---
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.
---

# 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 with a note of what is missing.
4. **Open points** — what remains to be settled, with the
   planned next step and its owner if known.

## Tone and style
- Factual. No commentary, no interpretation of intentions.
- Short sentences, active voice.
- 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.
- Meeting with no decision at all: state it as such in the
  Decisions section ("No decision recorded") rather than
  promoting discussions into decisions.
- Doubt about an action owner: mark "owner to be confirmed" —
  never assign by deduction.

## Pre-delivery check
- The four sections are present, in order.
- Every action has an owner and a deadline (or sits under
  Open points).
- The document fits on one page.

## Changelog
- v1.0 — created, format validated on 3 test meetings.

And the companion templates/example-summary.md: take the best summary your team has actually produced, anonymize it, place it alongside. Imitation model supplied, half the road travelled.

📍 Skills & MCP path — step 3/9

1. 🗺️ The map before the territory
2. 🔬 Anatomy of a skill
3. 🛠️ Create your first skill ← you are here
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 → Skills in the enterprise: governance — who writes, who validates, who maintains — and why a malicious skill is a permanent behavior injection. Governance, security angle included.

Your skill is written? The AI agent security check will tell you whether your organization is ready to host it.