Claude Skills: How to Write a SKILL.md (Format + Examples)

A Claude skill is a folder of instructions Claude loads on demand: at minimum a single SKILL.md file with a name, a description of when to use it, and a markdown body telling Claude how to perform a task. Skills can also bundle scripts, templates and reference files alongside the SKILL.md.

Anthropic introduced Agent Skills in October 2025 as a first-class way to package expertise, and they run across the Claude apps, Claude Code and the API — the same SKILL.md works on every surface. Partners like Box, Canva and Notion shipped skills at launch, but the interesting part for most teams is writing your own.

The mental model that makes skills click: a skill is an onboarding doc for an AI teammate. You are not programming — you are writing down the procedure a competent new hire would need, in the order they’d need it, with the judgment calls spelled out. If you browse our skills directory you’ll see the best ones read exactly like that.

Skills stay cheap because Claude doesn’t read them until they matter. Loading happens in three tiers:

The practical consequences: you can install many skills without burning your context window, the SKILL.md body should stay focused (Anthropic’s guidance is to keep it well under a few thousand tokens and push bulk material into reference files), and a skill with a vague description is effectively invisible — Claude has no other signal to activate it.

A valid SKILL.md needs just two things: YAML frontmatter between --- markers with a name and a description, and a markdown body with the instructions. Everything else — extra frontmatter fields, bundled files, scripts — is optional.

Here is a complete, working example — a skill that standardizes how a weekly metrics report gets written:

---
name: weekly-metrics-report
description: Writes the weekly growth report from analytics data. Use when the user asks for a weekly report, growth summary, KPI update, or "how did we do this week".
---

# Weekly metrics report

## Instructions

1. Pull visitors, leads, conversions and revenue for the last 7 days
   and for the 7 days before that.
2. Open with the two biggest changes — each as a number, a direction,
   and the comparison period. No adjectives without a number.
3. Then cover the funnel in order: traffic, leads, conversion rate,
   revenue. One short paragraph each.
4. Close with exactly three suggested actions, ranked by expected
   impact, each tied to a metric that motivated it.

## Guidelines

- Never invent or estimate a number. If a metric is unavailable,
  say so and move on.
- Flag any metric that moved more than 30% week-over-week for a
  deeper look before drawing conclusions.
- Keep the whole report under 400 words.

## Example opening

"Leads grew 22% week-over-week (61 vs 50) while conversion rate
dipped from 3.1% to 2.6% — traffic quality, not volume, is this
week's story."

Note what the body is doing: numbered steps for the procedure, guidelines for the judgment calls, and one concrete example of the desired output. That trio covers most skills. In Claude Code, personal skills live in the .claude/skills folder of your home directory and project skills in the repo’s .claude/skills folder — one subfolder per skill, each containing its SKILL.md.

Most skill problems are description problems. The rules we’ve converged on after writing and reviewing a lot of them:

• Write the description in two halves: what the skill does, then the literal phrases a user would say when they need it (“Use when the user asks for X, Y, or Z”). Trigger phrasing beats elegant prose.
• Front-load the procedure, not the philosophy. Claude follows numbered steps well; it follows mission statements poorly.
• Encode your standards as constraints, not vibes — “under 400 words”, “never invent a number”, “always cite the timeframe” are checkable; “be concise and accurate” is not.
• Show one example of great output. A single worked example does more than three paragraphs of description.
• Iterate against real transcripts. When the skill misfires, the fix is almost always sharpening the description or tightening a step — treat SKILL.md like code and revise it.

Anthropic also ships a skill-creator skill that scaffolds this interactively, and its public skills repository is a good source of working examples to imitate.

This is the most common point of confusion, and the honest answer is that they solve different halves of the same problem. Skills carry knowledge and procedure; MCP carries capability — live tools, data and systems the model can call. A skill can tell Claude *how* to write your weekly report; only an MCP server can give it the analytics tools to pull the real numbers.

The composition is the point. Our own platform pairs them deliberately: connected data arrives as MCP tools, while playbooks — our in-app equivalent of skills — teach the analyst *your* way of using them. If you’re deciding between building a skill and a server, the question is simply: does Claude lack knowledge (write a skill) or access (it needs an MCP server — start with our what-is-MCP doc)?

Skills work across the Claude surfaces: the Claude apps on paid plans, Claude Code (including via plugin marketplaces), and the API, which exposes a skills endpoint so the same packaged skill runs in your own agents. Anthropic’s Agent Skills documentation covers each surface’s specifics.

A sensible path from here:

1. 1Write one narrow skill for a task you do weekly, using the template above.
2. 2Test it by asking for the task in the words a colleague would use — not the words in your description.
3. 3Browse the skills directory for prior art before writing anything generic.
4. 4When your skill needs live data, pair it with the right server from setup guides like connecting Claude Desktop or the Claude Code MCP setup.