---
name: skills-reference
description: CC skills — auto-invoked domain modules with SKILL.md, frontmatter triggers, and file-hierarchy discovery.
layer: reference
cc_feature: skills
source: https://docs.claude.com/en/docs/claude-code/skills
concept: skills-system
last_verified: 2026-04-18
ngram_overlap_score: null
review_status: approved
---

# Skills — Reference

Claude Code's skill system is a way to package domain knowledge,
workflows, and supporting files so Claude can load them on demand. A
skill is a directory with a `SKILL.md` manifest and any auxiliary
files (scripts, templates, references).

## Anatomy

- **`SKILL.md`** — the entry point. Markdown file with YAML
  frontmatter and a body. The frontmatter declares when the skill
  triggers; the body is instructions Claude follows after loading.
- **Auxiliary files** — any files in the skill directory. Loaded on
  demand (typically by Claude reading them when the body references
  them). Common: `scripts/`, `templates/`, `references/`.

## Frontmatter

```yaml
---
name: <skill-name>
description: <one-line trigger hint>
---
```

The `description` is what Claude sees when deciding whether to invoke.
It should describe *when* to use the skill, not *what* it does.

## Invocation

- **Auto-invocation** — Claude loads the skill when the user's prompt
  matches the description's triggers. The trigger model is implicit
  (natural-language match), not regex.
- **Manual invocation** — the user types `/<skill-name>` and Claude
  calls the Skill tool.
- **Never auto-invoked** — if the description explicitly says so
  ("Internal catalog for X — not invoked directly"), Claude typically
  respects the hint.

## Discovery

Skills are discovered from:

- **Built-in skills** — shipped with the CLI.
- **Plugin skills** — packaged inside a plugin's `skills/` directory.
- **User skills** — `~/.claude/skills/`.
- **Project skills** — `.claude/skills/` inside the repo.

The CLI surfaces available skills via `--allowedTools` and in the
system prompt.

## Progressive disclosure

Skills use progressive disclosure:

1. Claude sees only the name + description at session start.
2. When a skill triggers, the body loads into context.
3. Files referenced by the body load only when Claude reads them.

This keeps the baseline context small; depth is paid for on demand.

## Relationship to other features

- **Skills vs subagents** — a skill lives in the parent's context when
  loaded. A subagent runs in its own context. Choose skill when the
  context flows through; subagent when it should not.
- **Skills vs hooks** — hooks are deterministic harness-level rules.
  Skills are context that Claude interprets. A skill cannot enforce;
  only guide.
- **Skills vs MCP** — MCP exposes *tools*. Skills are *knowledge*. An
  MCP tool + a skill that explains when to use it is a common pairing.