Skip to main content

Skills: On-Demand Expertise

Advanced
What you'll learn
  • Define what a Skill is and how it differs from stuffing everything into CLAUDE.md
  • Read and write a SKILL.md — frontmatter plus instructions — and understand why the description is the trigger
  • Explain progressive disclosure and why it lets many skills scale without bloating context
  • Know the three places skills live: personal, project, and bundled in a plugin
  • Choose correctly between Skill, slash command, subagent, and MCP
  • Avoid the four common mistakes that keep skills from triggering

A Skill packages expertise — instructions plus optional scripts and resources — that Claude loads only when relevant. Instead of stuffing everything into CLAUDE.md, you give Claude a library of capabilities it pulls in on demand.

Anatomy​

A skill is a folder with a SKILL.md: YAML frontmatter + instructions.

---
name: pdf-forms
description: Use when the user needs to fill, read, or generate PDF forms.
---

# PDF Forms
Steps and rules for working with PDF forms…
(optionally reference scripts/ or resources/ in this folder)
Pro tip
  • The description is the trigger — Claude reads it to decide when to activate the skill. Write it as "Use when…", specific enough that it loads at the right time and not otherwise.

Progressive disclosure (why skills scale)​

Claude doesn't load every skill's full body up front — it sees the lightweight name + description, and only pulls in the full instructions (and runs scripts) when a request matches. That keeps context lean even with many skills installed.

Where they live​

Guided walkthrough1 of 3
  1. ~/.claude/skills/<name>/SKILL.md — stays yours, available across all your projects.

AILmanac ships 7 ready-made skill packs — copy one in to try it.

Worked example: a skill that triggers itself​

Create ~/.claude/skills/release-notes/SKILL.md:

---
name: release-notes
description: Use when the user asks to write release notes or a changelog from git history.
---

# Release Notes
1. Run `git log <last-tag>..HEAD --oneline` to get the commits.
2. Group them into Features / Fixes / Breaking changes.
3. Write user-facing notes — what changed for *users*, not commit messages.
4. Output Markdown ready to paste into a GitHub release.

Later you type the prompt below. Claude never had these steps in context — but the request matches the description, so it pulls in the full SKILL.md, runs the git log, and produces grouped notes. You didn't invoke anything by name; the description did the routing. Add a scripts/ file in the same folder and the skill can run it as part of step 1.

Trigger the skill by intent — no name needed

Draft release notes since v1.4.

Skill vs command vs subagent vs MCP​

ToolWhat it isYou vs Claude triggers
Slash commandA saved promptYou invoke it
SkillOn-demand expertise + scriptsClaude loads it when relevant
SubagentA delegated agent with its own contextClaude delegates
MCPA connection to external tools/dataProvides tools to call
Key takeaways
  • You want to fire it on demand → slash command.
  • Claude should know the procedure and apply it when relevant → skill.
  • The work should happen in a separate context → subagent.
  • You need to reach an external system → MCP.

Common mistakes​

Watch out
  • A description that doesn't trigger. "Helps with PDFs" is too vague; "Use when the user needs to fill, read, or generate PDF forms" tells Claude exactly when to load it. The description is the whole activation mechanism — write it for matching, not for humans.
  • Putting everything in CLAUDE.md instead. CLAUDE.md loads every session and costs context always; a skill loads only when relevant. Move situational procedures into skills and keep CLAUDE.md for always-true project rules.
  • One giant skill. Many small, sharply-described skills route better than one catch-all — progressive disclosure only helps if each description is specific.
  • Forgetting it's shareable. A project skill in .claude/skills/ committed to git gives the whole team the capability; a personal one in ~/.claude/skills/ stays yours.

Recap the terms​

Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 6

Check yourself​

Check yourself

0/5
  1. In a SKILL.md, what actually decides when Claude activates the skill?
  2. What is progressive disclosure?
  3. You want the WHOLE TEAM to get a capability via git. Where do you put the skill?
  4. You want to fire something yourself, on demand, by name. Which tool fits?
  5. Why prefer a skill over putting a situational procedure in CLAUDE.md?

Next​