Max FableClaude Skills, explained
If you use Claude Code and keep seeing the word "skill," this is the short, practical version: what a skill actually is, how the file is structured, when a skill beats an MCP server, and a checklist for writing one that Claude will actually pick up and use.
1. What a Claude skill actually is
A skill is a folder with a SKILL.md file inside it. The file holds two things: a short description of when the skill applies, and a body of instructions the agent reads only when that situation comes up.
The key idea is progressive disclosure. The agent does not load every skill's full instructions into its context all the time — that would be wasteful and confusing. Instead it scans the one-line descriptions, decides which skill fits the task in front of it, and only then reads that skill's full body. Think of it as a table of contents the model consults before opening a chapter.
That's the whole mechanism. A skill is not code that runs; it's context that loads on demand. The power is in writing the description sharply enough that it loads at the right moment, and the body clearly enough that following it produces a reliable result.
2. The anatomy of a SKILL.md
A minimal, well-formed skill looks like this:
---
name: invoice-pdf
description: Use when the user asks to turn an order or
line items into a clean PDF invoice with totals and VAT.
---
# Invoice PDF
## When this applies
The user has order data (items, quantities, prices) and
wants a finished invoice document, not raw numbers.
## Steps
1. Collect: seller details, buyer details, line items.
2. Compute subtotal, VAT, and total. Show your math.
3. Render to HTML using the template below, then to PDF.
4. Save as invoice-<number>.pdf and report the path.
## Rules
- Never invent a VAT rate. Ask if it is missing.
- Currency formatting: two decimals, symbol before amount.Two parts do the heavy lifting:
- The frontmatter
descriptionis the trigger. It is the only thing the agent sees before deciding whether to open the skill. Write it as "Use when…" and name the concrete situation, not the topic. - The body is the procedure. The best bodies read like a senior colleague's runbook: numbered steps, explicit rules, and the hard edge cases called out ("never invent a VAT rate").
3. Why your skill isn't being triggered
The single most common problem is not the instructions — it's that the skill never loads. Usually the description is too vague or too broad. Some fixes that consistently help:
- Start the description with "Use when…" and describe the user's situation, not your skill's subject. "Use when the user wants to summarise a long article or webpage" beats "A summarisation skill."
- Name the artifacts and verbs the user will actually say: "PDF," "invoice," "standup," "changelog." Those words are what match.
- Keep one skill to one job. A skill that claims to do five things competes badly against five focused skills.
- Don't overlap descriptions. If two skills both say "use for documents," the agent can't choose well. Make the boundaries sharp.
4. Skill vs MCP server: which one?
People mix these up because both "extend" the agent. They solve different problems:
| Use a skill when… | Use an MCP server when… |
|---|---|
| You want to encode know-how: a procedure, a standard, a style, a checklist. | You need a new capability: live data, an API, a database, a system the agent can't otherwise reach. |
| The agent already has the tools (files, shell, browser) and just needs to be told how to use them well. | You're exposing real functions with inputs and outputs the agent calls at runtime. |
| Shipping it is writing Markdown. No server to host. | Shipping it means running and maintaining a process. |
Rule of thumb: if you can write it as instructions, write a skill. Reach for an MCP server only when the agent genuinely cannot do the thing without new wiring. Many teams build an MCP server when a three-paragraph skill would have done the job.
5. A build checklist
Before you call a skill done, run it against this:
- Description starts with "Use when" and names a concrete situation + the words the user will say.
- One job per skill. If you used the word "and" twice in the description, consider splitting.
- Numbered steps in the body — an agent follows a sequence far more reliably than a paragraph.
- Explicit rules and refusals. Say what not to do and when to stop and ask.
- No placeholders left behind (
TODO,FIXME,<your value>). Grep for them. - Tested on a real task from a cold start, not just the one you wrote it for.
That last point is where most skills quietly fail: they work for the author who knows the intent, and fall apart for everyone else. Test from cold.
Grab three working skills, free My free starter pack ships three ready-to-use skills (link summariser, prompt library, standup writer) you can read as worked examples — pay what you want, including €0.Once the free pack makes sense, the paid packs go further: a full Claude Code dev skills bundle, an OpenClaw power skills pack, and n8n automation workflows — all built and QA'd the same way this guide describes. The whole toolkit lives at ai-max.dev.
More from the cluster: OpenClaw skills, explained and, for automations, n8n AI agent workflows, without the breakage. Curious how crowded the niche is? See the live AI-agent niche density tracker. All guides: ai-max.dev/guides.