Anatomy of a skill: build your own AI employee

Every free download in the library is a skill or a template. In this guide I take one apart, show you what each piece does, and help you build your own for a task you do every week.

What a skill is

A skill is a folder with one file inside: SKILL.md. That file holds instructions in plain language. Claude Code reads it when the task matches and then follows it.

You don’t need code for that. Some skills also run a script, and that’s optional. Most of mine are plain text.

A skill is an AI employee with one job. “Write five hooks for this post” is a job. “Do my marketing” is not. If you can’t describe the output in one sentence, the skill is too big.

Where skills live

Claude Code looks for skills in fixed places. The two you need:

Where	Path	Who gets it
Project	.claude/skills/<skill-name>/SKILL.md	Everyone who opens this folder (commit it to share it)
Personal	~/.claude/skills/<skill-name>/SKILL.md	You, in every project on this machine

Start with the project location. Then the skill sits next to the business context it reads.

Two ways a skill runs

1. Claude picks it. At the start of a session Claude reads the short description of every skill. When your request matches one, it loads the full file and follows it.
2. You call it. Type / and the skill name at the start of your message, for example /meeting-notes-to-tasks. Anything you type after the name is passed on as the input.

Only the descriptions load at the start. The body of SKILL.md loads when the skill is used. So you can have many skills without filling Claude’s memory.

The frontmatter

Frontmatter is the block at the top of the file between two lines of ---. It’s written in YAML, a simple key: value format. It tells Claude Code what the skill is called and when to use it.

---
name: meeting-notes-to-tasks
description: Turns raw meeting notes into a task list with owner, deadline and next step. Use when the user pastes meeting notes, a call transcript or a summary and asks for tasks, action items or follow-ups.
---

The frontmatter has to start on the very first line of the file.

name

The name becomes the command, so /meeting-notes-to-tasks. Leave it out and Claude Code uses the folder name instead. Use lowercase words with hyphens and keep the name and the folder the same, so you never have to wonder which one counts.

description

This is the most important line in the whole skill. Claude reads it to decide when to use the skill, and it’s the only part Claude sees before the skill loads.

A good description has two parts:

• What it does, with the output first: “Turns raw meeting notes into a task list with owner, deadline and next step.”
• When to use it, in the words people actually type: “Use when the user pastes meeting notes, a call transcript or a summary and asks for tasks, action items or follow-ups.”

Put the key use case at the front. Claude Code cuts the description off in the skill list after 1,536 characters, together with the optional when_to_use field.

Common mistake: a description like “Helps with meetings.” Claude can’t tell when that applies, so it either never loads the skill or loads it for the wrong job.

Other fields you may want

The docs list more fields. All of them are optional. These are the ones I actually use:

Field	What it does
when_to_use	Extra trigger phrases or example requests. Added to the description and counts toward the same 1,536 characters.
argument-hint	A hint shown when you type the command, such as [path-to-notes].
disable-model-invocation	true means only you can start the skill. Claude won’t load it by itself. Use it for anything with side effects or timing you want to control.
user-invocable	false hides it from the / menu, so only Claude uses it. Good for background knowledge.
allowed-tools	Tools Claude may use without asking you while the skill runs.
paths	File patterns. The skill only loads automatically when you work on matching files.

Claude Code ignores field names it doesn’t know, without an error. So a typo in a field name fails silently. Check spelling against the skills docs.

The body: writing good instructions

Under the frontmatter you write the instructions. Write them like a briefing for a new employee who is smart but has never met you. They don’t know your business, your format or your taste. You have to tell them.

I use the same six parts in every skill.

1. Input

What the skill needs before it starts, and what it does when something is missing.

## Input

- Required: meeting notes (pasted text or a path to a .md or .txt file).
- Optional: the meeting date. If missing, ask once. Don't guess.

2. Steps

The work, in order. Number the steps, because the order matters. One action per step.

## Steps

1. Read the notes once, start to end.
2. Mark every sentence where someone agreed to do something.
3. For each one, find the owner. If no name is given, write "unassigned".

3. Output format

Show the exact shape of the result. A table, a list with fixed fields, a file in a fixed place. The more exact, the more stable the output.

4. Rules

The things that must always be true. Short, testable sentences. “Never invent a deadline” is a rule. “Be careful with deadlines” is not, because nobody can check it.

5. Examples

One short example of input and output does more than three paragraphs of explanation. Claude copies the pattern it sees. Make sure the example shows the result you want.

6. What NOT to do

List the mistakes you expect. This sounds negative, but it works. If you have seen the skill do something wrong once, write it down here so it doesn’t happen again.

Tip: write rules as facts, not hopes. “Always end with the open questions” works better than “Try to include open questions where possible.”

Supporting files: keep SKILL.md short

A skill folder can hold more than one file. The docs suggest keeping SKILL.md under 500 lines and moving detail into separate files. Once the skill loads, every line stays in Claude’s memory for the rest of the conversation. Long files cost space on every turn.

A typical layout:

meeting-notes-to-tasks/
├── SKILL.md            the job: input, steps, output, rules
├── reference.md        detail Claude reads only when needed
├── examples/
│   └── good-output.md  one complete example
└── scripts/
    └── to_csv.py       a script the skill runs (not read into memory)

Two things make this work:

• Link each file from SKILL.md and say when to read it. For example: “For the full priority rules, read reference.md.” Claude doesn’t read a file it doesn’t know about.
• Scripts are run, not read. If a step is mechanical (convert to CSV, count words, rename files), a script does it the same way every time. Claude only sees the result.

I keep the job description in SKILL.md and everything that’s “nice to know” in the other files.

Read the business context, don’t hardcode it

A common way for a skill to break: someone writes their team, their products and their tone of voice straight into SKILL.md. It works for a week. Then a person joins, a product changes, and you have to fix ten skills.

I do it differently. The skill holds the method. A separate folder holds the business. I call that folder the brain: a set of plain files about your company that every skill reads. The founder brain guide shows how to set one up.

brain/
├── company.md      what you do, for whom
├── team.md         who does what, who owns which area
├── voice.md        how you write
└── offer.md        what you sell

In the skill you write: “Read brain/team.md to find who owns which area.” You don’t write the names themselves.

When someone joins, you update team.md once and every skill that reads it is up to date. A skill without your business inside it also works for anyone with their own brain folder, which is why the skills in the library can be given away. And if team.md is empty, the skill can say so instead of making something up.

Check: search your SKILL.md for names, prices, product names and team members. Each one you find should probably live in the brain folder.

Testing: three real inputs

A skill is not done when it runs once. It’s done when it gives the same quality on inputs you didn’t write it for.

My routine:

1. Collect three real inputs. Not made-up ones. Three different meetings: a short one, a long one, a messy one.
2. Run the skill on all three. Save each output.
3. Compare them side by side. Same format? Same level of detail? Did it follow every rule?
4. Find the weakest output and ask why. Usually a step is vague or a rule is missing.
5. Tighten one thing. Add the rule, sharpen the step or add an example. Change one thing at a time, so you know what fixed it.
6. Run all three again. A fix for one input can break another.

Stop when three runs in a row give output you would use without editing.

Common mistake: testing on the example inside the skill. Of course it works on that. Test on inputs the skill has never seen.

A full example: meeting-notes-to-tasks

Example: this is a fictional skill for a neutral task. It’s not in the library. Use it as a template.

The folder:

.claude/skills/meeting-notes-to-tasks/
├── SKILL.md
└── reference.md

The full SKILL.md, with my notes in the comments:

---
name: meeting-notes-to-tasks
# The name becomes the command: /meeting-notes-to-tasks
description: Turns raw meeting notes into a task list with owner, deadline and next step. Use when the user pastes meeting notes, a call transcript or a summary and asks for tasks, action items, to-dos or follow-ups.
# Output first, then the trigger words people actually type.
argument-hint: "[path-to-notes]"
---

# Meeting notes to tasks

You turn meeting notes into a clear task list. You don't summarise the
meeting. You only extract what someone agreed to do.

<!-- One sentence on the job, one on what it does NOT do. -->

## Input

- Required: meeting notes, pasted or as a file path ($ARGUMENTS).
- Optional: the meeting date. If it's missing and a deadline says
  "next Friday", ask for the date once. Don't guess.

<!-- $ARGUMENTS is replaced by whatever the user typed after the command. -->

## Context

- Read `brain/team.md` to match first names to roles and areas.
- If `brain/team.md` doesn't exist or is empty, say so at the top of the
  output and continue with the names as written in the notes.

<!-- The business lives in the brain folder, not in this file. -->

## Steps

1. Read the notes once, start to end.
2. Mark every sentence where someone agreed to do something, or where a
   decision needs a follow-up.
3. For each one, write the task as a verb plus an object
   ("Send the draft contract", not "Contract").
4. Find the owner. Use the name in the notes. If no one is named, write
   "unassigned". Never pick an owner yourself.
5. Find the deadline. Only use dates or days that are in the notes. If
   there's none, write "none given".
6. Write one next step per task: the first small action.
7. List open questions: things discussed but not decided.

<!-- One action per step, in the order the work really happens. -->

## Output

A markdown table, then a short list:

| # | Task | Owner | Deadline | Next step |
|---|---|---|---|---|

**Open questions**
- ...

For how to sort tasks and what counts as a task, read `reference.md`.

<!-- Exact shape of the result. Detail moves to reference.md. -->

## Rules

- Every task comes from the notes. Never add a task that isn't there.
- Never invent a deadline or an owner.
- One task per row. Split "Anna sends the deck and books the room" into two.
- Keep the words of the notes where you can.

## Example

Input:
"Anna will send the draft to the client before Friday. We still need
to decide on the launch date. Someone should check the budget."

Output:

| # | Task | Owner | Deadline | Next step |
|---|---|---|---|---|
| 1 | Send the draft to the client | Anna | Friday | Do a final read of the draft |
| 2 | Check the budget | unassigned | none given | Assign an owner |

**Open questions**
- Launch date: not decided.

<!-- One short example. Claude copies the pattern. -->

## Don't

- Don't write a meeting summary.
- Don't add tasks you think are a good idea.
- Don't send the list to anyone. You only write it.

And reference.md, the detail Claude only reads when it needs it:

# Reference: meeting-notes-to-tasks

## What counts as a task
- A promise: "I'll do X", "Anna will do X".
- A request that was accepted: "Can you do X?" "Yes."
- A decision that needs action: "We go with supplier B" becomes
  "Inform supplier B".

## What doesn't count
- Ideas nobody picked up.
- Things that were already done in the meeting.

## Sorting
1. Tasks with a deadline, earliest first.
2. Tasks without a deadline.
3. Unassigned tasks last.

Notice what’s missing from both files: names of real people, your company, your clients. That all lives in brain/team.md.

Common mistakes

Mistake	What happens	Fix
Vague description	Skill never loads, or loads for the wrong task	Output first, then the words people actually type
One skill, five jobs	Output is average at everything	Split it. One skill, one output.
Business facts inside SKILL.md	Every change means editing many skills	Move them to the brain folder
No output format	Different shape every run	Show the exact table or template
Rules you can’t check	“Be concise” means nothing	Write rules you can test: “Max 12 words per task”
Testing on the built-in example	Looks perfect, fails on real input	Test on three real inputs
A huge SKILL.md	Fills Claude’s memory every turn	Move detail to supporting files
Typo in a frontmatter field	Field is ignored, no error	Check names against the docs

Common mistake: letting a skill send, post or publish. A skill writes. You decide what leaves the building. The human in the loop guide shows how to build that in.

Where the library fits

The hook writer (BX-003, keyword HOOKS) and the post reviewer (BX-004, keyword CHECK) are built exactly like this. One job each, the method in SKILL.md, a rules file next to it, and the brand read from separate files. Open one next to this guide and you’ll see every part I described.

Next

Read The delta hook to see the technique the hook writer uses, step by step.