AIGuide
Reusable know-how for your agent

Skills

A Skill is a folder of expertise you hand to Claude — a SKILL.md file (plus any helper files) that teaches it how to do a specific task the way you want. Claude pulls it in only when it's relevant. This page covers what they are, how they load, how to invoke and create them, and exactly when to reach for a skill versus something else — all inside VS Code.

SKILL.md Progressive disclosure Model-invoked /slash-invoked
💡

Quick clarification of a common assumption

You're close — a skill is built around a Markdown file, but it's technically a folder whose entry point is a file named exactly SKILL.md. That folder can also carry scripts, reference docs, and templates that load only when needed. And you usually don't "call" it manually — Claude decides to use it based on its description (though you can call it with /skill-name).

The idea

A skill is packaged expertise

Think of a skill as an onboarding folder for one job. Instead of re-explaining "here's how we write commit messages" or "here's our PDF-export process" every time, you write it down once, and Claude reads it whenever the task comes up.

  • 📄SKILL.md — the required entry point: YAML frontmatter (name + description) followed by Markdown instructions.
  • 📎Supporting files — optional scripts/, references/, assets/, templates. Loaded on demand, not upfront.
  • 🔁Reusable & shareable — check them into a repo for your team, or keep personal ones across all projects.
A skill is a folder 📁 📁 pdf-export/ 📄 SKILL.md required · frontmatter + instructions 📁 references/  ·  api-spec.md 📁 scripts/  ·  build_pdf.py 📁 assets/  ·  template.html ↑ only SKILL.md is mandatory — the rest is optional
The single most important concept

Progressive disclosure

Skills stay cheap because Claude loads them in three layers — just enough to decide, then more only if needed. You can have dozens of skills installed and they barely touch your context window until one is actually used.

Level 1 · always on 🏷️ name + description of every installed skill ≈ a few dozen tokens each so Claude knows the skill exists & when to use it Level 2 · on trigger 📖 full SKILL.md body the actual instructions loads only when relevant Claude auto-detects it, or you type /skill-name Level 3 · as needed 🗂️ bundled files references · scripts · assets pulled in file-by-file only the exact doc or script the task requires token cost: tiny ▁ moderate ▄ only what's used █

The payoff: install 30 skills, pay for 30 short descriptions — full content arrives just-in-time.

Getting a skill to run

Two ways a skill fires

Most skills are model-invoked — Claude reads the description and decides. But you can also invoke one explicitly, and you can lock down either path in the frontmatter.

🤖

Model-invoked (automatic)

You describe a task in plain language. Claude compares it against every skill's description and, if one fits, loads it — no command needed. This is the default and the whole point.

You: "turn these notes into a branded PDF" # Claude matches the pdf-export skill # and loads it on its own ↓
⌨️

User-invoked (explicit)

Type /skill-name in the prompt box to load a skill immediately — great for deliberate workflows like /deploy where you never want it to fire on its own.

You: /pdf-export quarterly-report.md # runs the skill right now, # no guessing required

disable-model-invocation: true

Claude can't auto-fire it — only /skill-name works. Essential for anything with side effects (deploy, delete, send).

user-invocable: false

Hides it from the / menu — only Claude can invoke it. For background know-how you don't call by hand.

Both omitted (default)

Both paths work: Claude may auto-invoke and you can type /skill-name. The right setting for most skills.

Anatomy

Inside a SKILL.md

Frontmatter tells Claude when to use the skill; the body tells it how. Here's a complete, realistic example.

--- name: commit-helper description: Writes a Conventional-Commit message from staged changes. Use when the user asks to commit or wants a commit msg. allowed-tools: Bash(git diff *), Bash(git log *) --- # Commit helper Here are the staged changes: !`git diff --cached` # runs BEFORE Claude reads this ## Instructions Write ONE Conventional-Commit message: - format: type(scope): summary - imperative mood, ≤ 72 chars on line 1 - add a short body only if it clarifies why See [examples.md](examples.md) for our house style.

The !`command` syntax injects live output into the skill before Claude sees it. The [examples.md] link is Level-3 material — loaded only if Claude needs it.

Frontmatter fields

FieldWhat it does
nameLabel for the skill. Defaults to the folder name. Lowercase, hyphens, ≤ 64 chars.
descriptionThe critical field. Says what the skill does and when to use it, in third person. This is what Claude matches against.
when_to_useExtra trigger context, appended to the description.
allowed-toolsTools the skill may use without a permission prompt.
disable-model-invocationtrue → only you can run it via /name.
user-invocablefalse → hide from the / menu.
model / effortOverride the model or reasoning effort for this skill.
context: forkRun the skill in an isolated subagent context.
✍️

Write the description like a trigger

"Use when the user asks to commit…" beats "a helpful commit tool." Specific trigger phrases are what make auto-invocation reliable.

Placement

Where skills live

Drop a skill folder in one of these locations. Project skills win over personal ones with the same name, and everything is discovered automatically.

ScopePathReach
Personal~/.claude/skills/All your projects
Project.claude/skills/This repo (check into git for the team)
Plugin<plugin>/skills/Wherever the plugin is enabled
🔄

Live reload

Editing a SKILL.md takes effect within the current session — no restart. Adding a brand-new skill folder needs a restart so it gets discovered.

🏠 Personal — every project ~/.claude/skills/ 📁 commit-helper/ · SKILL.md 📁 code-review/ · SKILL.md 📦 Project — this repo only your-repo/.claude/skills/ 📁 deploy/ · SKILL.md (+ checklist.md) 📁 pdf-export/ · SKILL.md (+ scripts/) Same name in both? The project skill takes priority.
Hands-on

Create your first skill in 3 steps

No special tooling — a folder and a text file are all you need.

Make the folder

Create .claude/skills/commit-helper/ in your project (or under ~/.claude/skills/ to use it everywhere). The folder name becomes the skill's /command.

Write SKILL.md

Add the frontmatter (a sharp description is 90% of the work) and the Markdown instructions Claude should follow. Reference any big docs as separate files so they load lazily.

Test it both ways

In VS Code, describe the task naturally to confirm Claude auto-invokes it — then type /commit-helper to confirm the explicit path. Tweak the description until triggering feels reliable.

🧪

Tip: iterate on the description

If Claude doesn't reach for your skill when it should, the description is usually too vague. Add concrete trigger phrases — the words a user would actually say.

The big question

Skills vs. everything else — when to use what

Claude Code gives you several ways to steer it. They overlap, so here's the clean mental model for choosing.

ToolWhat it isReach for it when…
🧠 SkillPackaged instructions (+ optional files/scripts) Claude loads on demandYou have a repeatable task or reference material — a workflow, a house style, a domain playbook. Loads only when relevant.
📌 CLAUDE.mdAlways-in-context project rulesSomething must be true every single turn — "use pnpm", "never touch .env", "run tests before commit".
⌨️ Slash commandA user-typed prompt shortcut (skills are the modern form)You want to trigger a prompt yourself, deliberately, by typing /name.
🧑‍🔧 SubagentA worker with its own isolated contextA side-task would flood the main context, or you want parallel specialists. (See the Claude Code page.)
🔌 MCP serverA connection to an external tool/serviceYou need data or actions outside the codebase — a database, Slack, a browser, an API.
What do you need? start here reusable how-to 🧠 Skilla task done your way 📌 CLAUDE.mdmust apply every turn 🧑‍🔧 Subagentisolate / parallelize 🔌 MCPreach outside the repo has side effects? → disable auto big docs? → supporting files ✅ ship it

Rule of thumb: if you'd write it in an onboarding doc for a teammate, it's probably a skill.

Day-to-day

Using skills inside VS Code

The extension treats skills exactly like the CLI — they share the same folders and settings, so anything you create works in both.

  • Type / in the chat box to see every available skill with its description, and pick one.
  • Autocomplete suggests skill names as you type /comm….
  • Create them in the file explorer — make the .claude/skills/…/SKILL.md file right in your editor; edits reload live.
  • Plugins that bundle skills are managed from the same UI as the CLI.
Claude Code — VS Code
Type / to browse skills…
/commit-helper
Writes a Conventional-Commit message from staged changes
/pdf-export
Turn a Markdown doc into a branded PDF
/deploy
Release to production (manual only)
💡 …or just describe the task and Claude picks the skill for you.

Illustration of the / skill menu in the extension.

Do it well

Best practices, pitfalls & safety

✓ Best practices

  • ✓One skill, one job. Keep SKILL.md focused (aim well under ~500 lines).
  • ✓Push detail into files. Long references go in references/ and load lazily.
  • ✓Descriptions in third person with real trigger phrases.
  • ✓Say what to do, not a wall of why.

⚠️ Common pitfalls

  • ✗Vague descriptions → Claude never triggers the skill.
  • ✗Overstuffed body → context bloat, weaker results.
  • ✗Auto-invoking risky tasks → add disable-model-invocation.
  • ✗Hardcoded paths → breaks in other projects.

🔒 Safety

  • !Skills can run code via !`…` and allowed-tools.
  • !Review a repo's .claude/skills/ before trusting it.
  • !Gate side effects behind manual invocation.
  • !Admins can disable skill shell execution by policy.
Tie it together

Skills are the loop's memory of "how"

The agentic loop decides what to do; a skill supplies the how — your process, your standards, your reference material — pulled in exactly when the loop needs it. Combine skills with subagents and a well-designed loop and you've got a genuinely dependable assistant.

Next lesson: In Claude Code Browse the glossary
⌂ Back to all lessons