D3 · Claude Code › Cluster 5 · Skills

5.1 · What Agent Skills Are

SKILL.md model-invoked capability

CONCEPT A skill is a folder with a SKILL.md

An Agent Skill is a directory whose entrypoint is a single file called SKILL.md. That file has two parts: YAML frontmatter between --- markers, and a markdown body of instructions. The frontmatter carries a name and a description; the body is the procedural knowledge Claude follows once the skill is in use. Alongside SKILL.md the folder may bundle optional supporting files — reference docs, templates, example outputs, and executable scripts.

🔑 Minimal skill = one folder + one SKILL.md. Everything else (scripts, references, assets) is optional and loaded only when needed.

Claude Code skills follow the Agent Skills open standard (agentskills.io), so the same folder format works across Claude products — Claude Code, the Claude API, and claude.ai — though each surface manages and stores skills differently. Create a skill "when you keep pasting the same instructions, checklist, or multi-step procedure into chat," or when a section of CLAUDE.md has grown from a fact into a procedure. Unlike CLAUDE.md — which is always in context — a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.

CONCEPT Model-invoked, not user-invoked

The defining trait of a skill is that it is model-invoked: Claude decides to use one by matching your request against the skill's description. You don't have to name it. Ask "what did I change?" and Claude loads a summarize-changes skill on its own if the description says so. This contrasts with a classic slash command, which is user-invoked — nothing happens until you type it. In Claude Code a skill is both by default: Claude can auto-trigger it, and you can also run it directly by typing /skill-name (the command name comes from the directory name).

AspectAgent Skill
What it isA folder with SKILL.md + optional bundled files
Required frontmattername and description (only description is truly recommended)
Who triggers itClaude, by matching the task to the description (also user-typable as /name)
When the body loadsOnly when the skill triggers — not upfront
StandardAgent Skills open standard (agentskills.io)
Because a skill is just files on disk, it is version-controllable, reviewable, and shareable — commit .claude/skills/ to your repo and the whole team gets the capability.

DIAGRAM Anatomy of a skill folder

flowchart TD R["Task from user"] --> M{"Does the request match
a skill's description?"} M -->|"yes"| LOAD["🟢 Claude loads SKILL.md body
(model-invoked)"] M -->|"or you type /name"| LOAD LOAD --> B["Body: markdown instructions"] B --> OPT{"Body references
bundled files?"} OPT -->|"reference.md / examples.md"| REF["📄 Read as needed"] OPT -->|"scripts/helper.py"| SCR["⚙️ Execute via bash
(code never enters context)"] M -->|"no match, not typed"| SKIP["⚪ Only name+description
stay in context"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class LOAD ok; class REF gate; class SCR gate; class SKIP bad;

CODE A minimal SKILL.md

The directory name (summarize-changes) becomes the command /summarize-changes. The description tells Claude what the skill does and when to use it — that string is what auto-invocation matches against.

# File: ~/.claude/skills/summarize-changes/SKILL.md
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the
  user asks what changed, wants a commit message, or asks to review their diff.
---

## Instructions

Summarize the current git diff in two or three bullet points, then list any risks
you notice such as missing error handling, hardcoded values, or tests that need
updating. If the diff is empty, say there are no uncommitted changes.
⚠️ Field rules from the standard: name ≤ 64 chars, lowercase letters, numbers, and hyphens only, and cannot contain the reserved words anthropic or claude. description must be non-empty and ≤ 1024 chars.

TRADE-OFFS Skill vs. stuffing it all into CLAUDE.md

✅ Put a procedure in a skill

  • Body loads only when the task matches — near-zero idle cost
  • Can bundle scripts and reference files
  • Directly invocable as /name
  • Reviewable, versioned, shareable per-folder

⚠️ Put the same procedure in CLAUDE.md

  • Always in context — pays tokens every turn, used or not
  • No bundled files, no scripts
  • Grows unwieldy as procedures pile up
  • Good only for short, always-true facts
Rule of thumb: facts that are always true → CLAUDE.md; procedures triggered by specific tasks → a skill.

EXAM TRAPS

Trap: "A skill is a single markdown file." → It's a directory; the file inside is SKILL.md. The folder can also hold scripts, references, and assets.
Trap: "Skills are user-invoked like old slash commands." → Skills are model-invoked by default — Claude triggers them by matching the description. You can also type /name, but auto-invocation is the point.
Trap: "You must set name." → Only description is recommended; name is optional and defaults to the directory name. But you can't skip the SKILL.md file itself.
Trap: "Skills only exist in Claude Code." → Agent Skills are an open standard; the same SKILL.md format is used on the Claude API and claude.ai too (Claude Code stores them on the filesystem, no upload needed).

PRACTICE

Q1 · What are the two required-ish pieces of a skill's frontmatter, and which matters most?

name and description. Only description is genuinely recommended — it's what Claude matches the task against to decide whether to auto-invoke. name is optional and defaults to the folder name.

Q2 · Why is "model-invoked" the key property of a skill?

Because Claude decides to load the skill on its own by matching your request to the description, without you naming it. That's the contrast with a plain slash command, which does nothing until the user types it. A skill can still be typed as /name, but auto-invocation is what makes it a skill.

Q3 · When should a procedure live in a skill rather than in CLAUDE.md?

When it's a task-triggered procedure (a checklist, a multi-step workflow) rather than an always-true fact. CLAUDE.md is always in context and pays tokens every turn; a skill's body loads only when the task matches, so long procedures cost almost nothing until used.