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 <query>` — Search by title or podcast name
- `shownotes <uuid>` — Get episode show notes
- `episode <uuid>` — 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-name>/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.

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.

Next: Make It Shareable