--- title: "Write Your First Skill" description: "SKILL.md — structured, portable knowledge Claude loads automatically." order: 15 duration: "15 min" chapter: "04-making-your-org-legible" type: lesson --- ## Markdown instructions, not code A skill is a markdown file — a `SKILL.md` — that teaches Claude how to do something specific to your organization. Not code. Not a plugin. A document. Claude scans your installed skills at the start of a conversation and loads the right one when the task matches — and skills work across surfaces: Claude Code, the desktop app, and claude.ai. The difference between project knowledge and a SKILL.md is the difference between notes and a manual. Project knowledge and CLAUDE.md are informal, workspace-scoped, and accumulate organically. A skill is structured, portable, and designed to be shared. Think of it as the formalization step: the knowledge has been tested through use, refined through corrections, and is now ready for wider deployment. Here is the anatomy of a real skill — the Pocket Casts integration we use for our content pipeline: ``` # .claude/skills/pocketcast/SKILL.md --- name: pocketcast description: This skill should be used when the user asks to "list starred episodes", "check my podcasts", "podcast history", or "show notes". Provides read-only access to Pocket Casts. --- ## Usage Run scripts via: npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts ### Available Commands - `starred` — List all starred episodes - `recent [--limit=N]` — Recent listening history - `search ` — Search by title or podcast name - `shownotes ` — Get episode show notes - `episode ` — Detailed episode metadata ``` Two frontmatter fields do all the work. `name` identifies the skill. `description` is how Claude decides when to load it — write it as "use this when…" with the exact phrases people actually say. That description is the trigger; there is no separate trigger configuration. That skill has a code component — it calls TypeScript scripts. But skills do not need code at all. A skill can be pure knowledge. Here is what the Cornwall Market categorization skill looks like — the knowledge Sarah dictated in Chapter 02, in its mature form: ``` # .claude/skills/categorization/SKILL.md --- name: cornwall-market-categorization description: Use when categorizing a transaction or invoice, or deciding which account code applies. Contains Cornwall Market's chart of accounts, vendor rules, and exception flags. --- ## Account Code Reference | Account | Name | Used For | |---------|------|----------| | 5100 | Cost of Goods — Produce | Fresh fruits, vegetables, herbs | | 5110 | Cost of Goods — Dairy | Milk, cheese, butter, eggs | | 5120 | Cost of Goods — Bakery Ingredients | Flour, sugar, yeast, baking supplies | | 5130 | Cost of Goods — Dry Goods | Canned goods, pasta, rice, shelf-stable items | | 5200 | Cost of Goods — Beverages | All drinks including coffee, juice, water | | 6100 | Operations — Supplies | Cleaning supplies, packaging, disposables | | 6250 | Building Improvements | Renovation, capital improvements (by location) | ## Vendor Rules ### Chen's Produce - Account: 5100 - Invoices arrive Tuesdays and Thursdays - Always rounds up by $1-2 on totals — this is normal, do not flag - IMPORTANT: Do not confuse with Chen's Bakery Supplies (account 5120) - Identifier: invoice items are fresh produce (lettuce, tomatoes, herbs) ### Chen's Bakery Supplies - Account: 5120 - Invoices arrive Monday mornings - Identifier: invoice items are baking ingredients (flour, sugar, yeast) ### Pacific Foods (broad-line distributor) - SPLIT invoices across departments: - Produce items → 5100 - Dairy items → 5110 - Dry goods → 5130 - Cleaning supplies → 6100 (NOT Cost of Goods) - FLAG any single line item over $500 — likely case quantity error ## Exception Rules - Contractor payments over $2,500: flag for 1099 review - Q4 (Oct-Dec): cross-reference all contractor payments against year-to-date totals for 1099 threshold tracking - Building improvements: track by store location for insurance ``` No code. Just structured knowledge. Claude reads this and gains the ability to categorize Cornwall Market's transactions correctly — something that previously lived only in Sarah's head. ## Turn your captured knowledge into a SKILL.md Go back to the document in your Project — the one you captured in Chapter 02 and tested when you created the Project. Now turn it into a skill. The format is straightforward: 1. **Frontmatter** — a `name` and a `description` that says when to use the skill, including the phrases people actually say 2. **Reference tables** — the mappings, codes, categories your work uses 3. **Rules** — the logic, organized by entity (vendor, customer, department) 4. **Exceptions** — the edge cases, the "watch out for this" items You can ask Claude to help. Paste your structured document and say: "Format this as a SKILL.md for Claude. Use frontmatter with a name and a description that explains when to use it." Where it lives: put project skills in `.claude/skills//SKILL.md` inside the project, or personal skills in `~/.claude/skills/` so they follow you across every project. On claude.ai and the desktop app, upload the same file under Settings → Capabilities.
Try This

Take the structured document from your Project. Convert it into a SKILL.md file. Use Claude (in app or browser) to help format it — paste your document and ask it to structure it as a skill with frontmatter, reference tables, vendor/entity rules, and exception rules.

Read the result back. Does it capture what a new hire would need to know? Is anything missing? Add it.

Save the file. You will use it in Chapter 06 when you install Claude Code — and you can upload it to claude.ai (Settings → Capabilities) right now so your Project chats use it too.

## Check your understanding Answer in your own words — write it down before opening the key. Your tutor grades against the criteria and generates fresh variants on retries. **Q1.** A well-written SKILL.md never gets used — Claude simply doesn't load it. What is the most likely cause, and how would you rewrite the offending part? Include a before/after example.
Answer key — attempt every question first ## Answer key ### Q1 **Model answer:** The description frontmatter is the trigger — Claude loads a skill when the task matches it. A description written like documentation ("Contains vendor categorization rules") never matches what people say. Rewrite with usage phrases: "Use when categorizing a transaction or invoice, or deciding which account code applies." **Pass criteria:** identifies the description-as-trigger mechanism; rewrite includes 'use when' phrasing with the words users actually say
**Next:** [Make It Shareable](/mastering-claude/04-making-your-org-legible/16-make-it-shareable/)