# Skills

> Skills are reusable, on-demand task workflows defined in markdown with YAML frontmatter. Unlike CLAUDE.md (always loaded), skills load only when Claude matches the description to the current task. Skills can restrict tool access and accept arguments.

**Domain:** D3 · Agent Operations (20% of CCA-F exam)
**Canonical:** https://claudearchitectcertification.com/concepts/skills
**Last reviewed:** 2026-05-04

## Quick stats

- **Frontmatter fields:** 5
- **Scopes:** 2
- **Load pattern:** on-demand
- **Exam domain:** D3
- **Context isolation:** fork

## What it is

A skill is a self-contained folder of instructions that Claude Code discovers and activates automatically when it recognizes the task. Instead of repeating "review this PR for security" or "format commits this way" across sessions, you write a SKILL.md file once, with a name, description, and instructions in YAML frontmatter, and Claude applies it on demand. The mental model: a skill is a task-specific, portable teaching file that lives in ~/.claude/skills/ (personal) or .claude/skills/ (project, version-controlled, shared).

What makes a skill skill-like (not just a CLAUDE.md or a slash command) is automatic matching and progressive disclosure. CLAUDE.md always loads, burning tokens on rules you don't need. Slash commands require explicit invocation every time. Skills are different: Claude reads each skill's description, compares it against your request, and activates only the relevant ones. No token overhead when idle; no manual triggering. The description is the selector.

Skills support progressive disclosure through multi-file organization. Keep the core SKILL.md under 500 lines, then link to supporting files (references/, scripts/, assets/) that Claude reads only when needed. Scripts execute without loading their contents into context, only the output consumes tokens. A skill can restrict tool access via allowed-tools, perfect for read-only exploration or security-sensitive work where you don't want Claude to accidentally modify files.

The skill frontmatter pattern is minimalist by design. Two required fields: name (lowercase, hyphens, max 64 chars) and description (max 1,024 chars; this is where matching magic lives). Two optional: allowed-tools and model. Below the frontmatter, you write instructions in plain Markdown. Adoption reflex: "I'm repeating this to Claude across sessions" → a skill is waiting to be written.

## How it works

The discovery flow has four stages. Matching: Claude reads your request and compares it semantically against the descriptions of all available skills (personal and project). If your request mentions "review PR" and a skill says "reviews pull requests for code quality," it's a match. Loading: Claude loads only the matched skill's SKILL.md into context, not all skills. Execution: you interact with the skill (Claude references its instructions). Unloading: when the task finishes, the skill context is discarded.

Skill matching is semantic and probabilistic. Claude uses natural language understanding, not string matching. If your request is "please check this code change" and a skill describes itself as "ensures code quality in pull requests," Claude can match them even though exact words differ. This is why descriptions matter so much: vague descriptions like "helps with code" don't match reliably; explicit ones like "validates Python security patterns" consistently trigger.

Tool access is restricted at activation time, not at request time. When you set allowed-tools: Read, Grep, Glob, Bash in the frontmatter, Claude can only use those tools while the skill is active. It cannot call Edit or Write, even if you ask. Perfect for a "codebase-onboarding" skill where new developers should explore but not modify. If you omit allowed-tools, the skill inherits your normal permission model.

Progressive disclosure saves context budget. A big skill with a 3,000-line reference document burns 2,000 tokens just sitting in context. Instead, keep SKILL.md lean, then structure: skill-dir/references/guide.md, skill-dir/scripts/validate.sh. In SKILL.md, write: "if the user asks about X, run scripts/validate.sh and read references/guide.md." Claude loads only what's needed. Scripts execute in the background; their output (not their source) gets injected.

## Where you'll see it in production

### Domain-specific research workflow

Healthcare team has /healthcare-research skill that searches PubMed + extracts claims with sources + tags evidence tier (RCT vs observational). Description matches 'research medical' or 'clinical evidence' queries. Tools restricted to Read/WebSearch/WebFetch, no Edit, no Bash. Output is JSON.

### Headless CI code review

/ci-review skill runs in claude -p headless mode from GitHub Actions. Input is a PR diff; output is structured JSON of findings. context: fork keeps the verbose review out of the main session. Same skill works locally and in CI without changes.

### Vault search with depth control

/search-vault skill takes a query + depth argument. At depth=1 it returns frontmatter snippets; at depth=3 it returns full sections. Skill matches 'find in vault' / 'search notes' descriptions. Reduces context bloat by serving the right depth instead of dumping full files.

## Code examples

### .claude/skills/healthcare-research.md

```yaml
---
name: healthcare-research
description: |
  Use when the user asks for medical literature, clinical evidence,
  drug efficacy data, or similar healthcare-research queries.
  Returns structured JSON: {claims: [{claim, sources: [...], tier}]}.
context: fork
allowed-tools: [Read, WebSearch, WebFetch]
argument-hint: "Search query (e.g., 'CDK4/6 inhibitors HR+ breast cancer')"
---

# Healthcare Research Workflow

## Steps
1. Parse query into structured terms (disease, intervention, outcome)
2. Search PubMed and clinicaltrials.gov in parallel
3. For each result: extract claim, title, URL, date, journal
4. Label evidence tier:
   - 🟢 RCT or meta-analysis
   - 🟡 Observational study
   - 🟠 Case report
   - 🔴 Speculation / commentary
5. Deduplicate by URL; sort newest first
6. Return JSON only, no narrative text

## Output schema
{
  "query": "<original query>",
  "claims": [
    {
      "claim": "<one-sentence finding>",
      "sources": [{"title": "...", "url": "...", "date": "YYYY-MM-DD", "tier": "🟢"}]
    }
  ]
}

## Don't
- Scrape paywalled content
- Mix marketing claims with clinical claims
- Omit dates or URLs

```

> YAML frontmatter is parsed by Claude Code's routing. The description drives auto-match; allowed-tools enforces safety; context: fork isolates the verbose work.

### .claude/skills/ci-review.md (headless mode)

```yaml
---
name: ci-review
description: |
  Async PR code review for CI/CD pipelines. Reads diff, flags
  regressions, suggests refactors, emits structured JSON.
  Designed for headless invocation: claude -p --skill ci-review.
context: fork
allowed-tools: [Read, Glob, Grep, Bash]
argument-hint: "PR number or branch name"
---

# CI Review

Invoked from .github/workflows/pr-review.yml as:
  claude -p --skill ci-review "PR #${{ github.event.pull_request.number }}"

## Checklist
- [ ] No new console.error or unhandled rejections
- [ ] Type signatures on new functions
- [ ] Coverage did not decrease
- [ ] No secrets in committed files
- [ ] Migrations are idempotent

## Output (single JSON object on stdout)
{
  "pr_number": 42,
  "verdict": "approved" | "needs-rework" | "hold",
  "summary": "<two-sentence overview>",
  "findings": [
    {
      "file": "<path>",
      "line": <int>,
      "severity": "error" | "warning" | "info",
      "message": "<what's wrong>",
      "suggestion": "<concrete fix>"
    }
  ]
}

## Bash usage
- Read-only commands only: `git diff`, `git log`, `grep`, `ls`
- Never run tests, linters, or anything that mutates state

```

> Headless skills emit a single JSON object to stdout. CI parses it into a PR comment. Tool restrictions prevent the skill from accidentally mutating the repo.

## Looks-right vs actually-wrong

| Looks right | Actually wrong |
|---|---|
| Drop a markdown file in .claude/skills/ and Claude will pick it up. | Skills require YAML frontmatter (name, description, optional allowed-tools / context / argument-hint). Without it, the file is plain markdown and won't auto-match queries. |
| Build one large mega-skill that covers all team workflows. | Skills should be granular, one workflow per skill. Mega-skills break context isolation and make tool restrictions too broad. Aim for skills under ~300 lines. |
| Use a Skill instead of CLAUDE.md so it doesn't load on every session. | Skills and CLAUDE.md serve different purposes. CLAUDE.md = always-on team standards. Skills = on-demand workflows triggered by description match. Use both, not one. |
| Skills and subagents are interchangeable, both "do a task in isolation." | Skills are stateless prompt packages loaded into the current conversation; subagents have their own isolated context window with their own message history. A skill cannot summarize 50 files into a single block, the work happens inline. A subagent can, the verbose work is discarded and only the summary returns. Pick subagents for context isolation, skills for reusable instructions. |
| A skill's description field is just a comment, the file name is what matters. | The description IS the matching key. Claude reads every skill's description and ranks them against the user's request semantically. A vague description like "helps with code" never reliably triggers; an explicit one like "reviews Python pull requests for security patterns" matches consistently. The file name is for humans only; the description is for the router. |

## Comparison

| Aspect | Skill | CLAUDE.md | Slash command (legacy) |
| --- | --- | --- | --- |
| Loading | On-demand (description match) | Every session | On explicit invocation |
| Tool restriction | Yes (allowed-tools) | No | No |
| Output isolation | Yes (context: fork) | No (in-session) | No |
| Best for | Reusable workflows | Always-on standards | Quick aliases (deprecating) |
| Discovery | Semantic match against description | Path-based (project root) | Manual /name typing |
| Model override | Yes (model: in frontmatter) | No (uses session model) | No |

## Decision tree

1. **Is this a reusable workflow you'll invoke many times?**
   - **Yes:** Make it a Skill in .claude/skills/. Write a description that matches likely user phrasings.
   - **No:** Keep it inline or in CLAUDE.md if it's a one-time rule.

2. **Should the workflow run with restricted tools (e.g., read-only)?**
   - **Yes:** Set allowed-tools in the frontmatter. Skills enforce the restriction; CLAUDE.md cannot.
   - **No:** Skill or CLAUDE.md both work. Pick by load pattern.

3. **Should the verbose work stay out of the main conversation?**
   - **Yes:** Add context: fork to the frontmatter. Skill output is summarized; intermediate work is hidden.
   - **No:** Skip fork; let work flow into the main context.

4. **Does the workflow need its own isolated context window with separate message history?**
   - **Yes:** Use a subagent, not a skill. Skills load into the current conversation; subagents spawn a fresh context.
   - **No:** A skill is sufficient. The instructions inline alongside your conversation.

5. **Will the skill's instructions exceed ~500 lines?**
   - **Yes:** Decompose with progressive disclosure: keep SKILL.md lean, move long content into references/ and reference scripts via scripts/. Claude loads the linked files only when the skill needs them.
   - **No:** Inline is fine. Aim for under 500 lines for sharp matching and minimal token cost.

## Exam-pattern questions

### Q1. Your skill description is "helps with code" and Claude activates it for every request. Fix?

Description is too generic. Rewrite as task-specific: "validates Python security patterns; use when reviewing code for SQL injection or hardcoded secrets." Specific descriptions enable accurate matching.

### Q2. A skill has allowed-tools: Read, Grep, Glob, Bash and you ask Claude to edit a file. It refuses. Why?

Skills enforce allowed-tools at activation time. While the skill is active, Claude can only use those tools. Either add Edit to allowed-tools, or invoke a different skill that has Edit.

### Q3. You wrote a 2,000-line SKILL.md. Claude responses are slow when the skill is active. Better structure?

Use progressive disclosure. Keep SKILL.md under 500 lines. Move detailed references to references/, examples to examples/, scripts to scripts/. Link from SKILL.md: "if user asks about X, read references/guide.md."

### Q4. Your skill works on your machine but a teammate can't trigger it. Where's the file?

Personal skills (~/.claude/skills/) don't sync. Move it to .claude/skills/ (project, version-controlled). Commit and push. Teammates pull and the skill is available.

### Q5. Two skills match the same request. Which one activates?

Both load into context simultaneously. If their instructions conflict, results are unpredictable. Make descriptions non-overlapping: each skill should describe a unique task with no semantic overlap.

### Q6. A skill has scripts in scripts/ but they don't execute when invoked. Why?

Scripts must be marked executable (chmod +x) and the SKILL.md must reference them with the correct relative path. Test the script standalone first; then verify SKILL.md instructions are clear about when/how to run it.

### Q7. When does a skill trump CLAUDE.md, and when does CLAUDE.md trump a skill?

CLAUDE.md is always-loaded, applying to every conversation. Skills load on-demand when their description matches. They're complementary: CLAUDE.md for universal team standards; skills for repeated task workflows. Neither trumps the other; they layer.

### Q8. Your CI pipeline invokes Claude with --skill ci-review but the skill isn't activated. What's wrong?

The flag must match the skill's name field exactly (lowercase, hyphenated). Check the SKILL.md frontmatter. Also verify the skill file is in .claude/skills/ (not ~/.claude/skills/ for project-scoped CI).

## FAQ

### Q1. What's the difference between a skill and a custom slash command?

Slash commands require explicit invocation (/review-pr); skills auto-match based on description. Skills also support allowed-tools, context: fork, and model overrides; slash commands don't. Anthropic is consolidating around skills; new work should use skills, slash commands stay for legacy.

### Q2. Can a skill call another skill?

Indirectly. A skill's instructions can reference another skill by name; Claude will load the second skill if the request matches its description. Direct invocation (call_skill("x")) is not a primitive, the routing happens via natural language matching, not a function call.

### Q3. Where do skills live, project or user?

Both. Project skills in .claude/skills/ (committed to git, shared with team); user skills in ~/.claude/skills/ (personal, global). Both are discoverable in any session within their scope. Project takes precedence on name conflicts.

### Q4. Does allowed-tools actually prevent Edit if I ask Claude to write a file?

Yes, structurally. Tool restrictions are enforced at the SDK layer, not in the prompt. If allowed-tools: [Read, Grep] and you ask to edit, Claude responds that it can't, the tool is unavailable for the duration of the skill. Strong sandboxing for read-only or audit workflows.

### Q5. How do I version skills?

Git versioning is the standard, project skills live in .claude/skills/ and travel with commits. For breaking changes, introduce a new skill name (e.g. pr-review-v2) rather than mutating the description, since users may have learned to invoke by phrasing.

### Q6. What happens when two skills match the same request?

Claude picks the highest semantic match by description. Ties are broken by project skills winning over user skills, then by description specificity. Two skills with similar descriptions is a smell, rewrite descriptions to disambiguate boundaries.

### Q7. Can a skill change the model used for that turn?

Yes, set model: claude-opus-4-5 in the frontmatter. The skill executes against the named model regardless of the session's default. Useful for sending heavyweight workflows to Opus while keeping the rest of the session on Sonnet/Haiku for cost.

### Q8. How does context: fork differ from spawning a subagent?

context: fork runs the skill in an isolated context window but with the same agent identity and tools (subject to allowed-tools). A subagent is a separate agent with its own system prompt, tools, and model. Forks are for verbose work that pollutes the main thread; subagents are for delegated specialization.

### Q9. Are skills loaded into the system prompt or as a separate message?

Loaded as part of the system prompt when a match fires. Token cost is paid for the duration of the skill being active. When the user moves on to an unrelated request, the skill unloads and its tokens are freed from subsequent turns.

### Q10. How do I debug a skill that isn't auto-matching?

Three checks: (1) the skill is in a discoverable location (~/.claude/skills/ or .claude/skills/), (2) it has valid YAML frontmatter (no parse errors, name and description present), (3) the description explicitly mentions phrasings the user is likely to type. Vague descriptions silently fail to match, treat the description as the prompt that triggers the skill.

---

**Source:** https://claudearchitectcertification.com/concepts/skills
**Vault sources:** ACP-T03 §4.3 skills; GAI-K04 §6 frontmatter; ASC-A01 Course 15
**Last reviewed:** 2026-05-04

**Evidence tiers** — 🟢 official Anthropic doc / API contract · 🟡 partial doc / inferred · 🟠 community-derived · 🔴 disputed.