How Claude Skills work

1. What a skill actually is

A skill is a folder containing one required file: SKILL.md (YAML frontmatter + markdown body), plus optional bundled assets — scripts, templates, reference docs, schemas.

There's no compilation step, no runtime, no framework. A skill is a piece of documentation Claude reads, plus files it can open or execute while the skill is active.

pdf/
├── SKILL.md
├── scripts/
│   ├── extract_text.py
│   ├── fill_form.py
│   └── merge.py
└── reference/
    ├── form_fields.md
    └── pypdf_cheatsheet.md

2. Why skills exist (vs. system prompts)

You could teach Claude how to fill PDF forms by jamming five pages of pypdf docs into the system prompt. That has three problems:

1. Bloat: every prompt pays the token cost, even ones unrelated to PDFs.
2. Distraction: a giant system prompt makes Claude worse at unrelated tasks.
3. Lock-in: the capability is welded to one prompt — not portable.

Skills solve all three. They're portable, lazy (only loaded when relevant), and composable.

3. Progressive disclosure

Claude doesn't see your skill's full body unless it decides to use it.

This is why you can install 50 skills without context bloat — Claude only spends tokens on descriptions until one triggers.

4. Frontmatter reference

---
name: string                # required, kebab-case, matches folder name
description: string         # required, ~1 sentence, drives triggering
allowed-tools: list          # optional, default: inherit session tools
  - Read
  - Write
  - Bash
model: string                # optional, override model for this skill
version: string              # optional, semver
author: string               # optional
license: string              # optional, SPDX id
---

• name — must match the folder name. Lowercase kebab-case.
• description — written for the model. Lead with when, then what. Concrete trigger phrases help.
• allowed-tools — cap the tools the skill can use. Useful for safety.
• model — pin a model. Rare. Mostly for cost-sensitive workflows.

5. How triggers work

There's no regex, no keyword list. When you send a message, Claude reads the descriptions of every installed skill and picks the ones that look relevant.

This is why the description matters so much. Bad descriptions never trigger. Good ones trigger reliably without false positives.

A bad description

description: Helps with files.

A good description

description: Extract text and form-field values from PDF documents, fill
  interactive PDF forms from JSON or CSV data, merge or split PDFs, and generate
  new PDFs from markdown. Triggers on phrases like "fill this form", "extract
  from PDF", "merge PDFs", or when a .pdf file is attached.

6. allowed-tools and trust

Skills can scope down which tools they're allowed to call. A "summarize this doc" skill has no business calling Bash.

If allowed-tools is omitted, the skill inherits session tools. If listed, those are the maximum — the skill can never exceed them even if the session is more permissive.

For high-trust skills, pair allowed-tools with explicit per-script permission rules in settings.json. See Hooks for blocking dangerous operations.

7. Composing multiple skills

Skills layer. A single prompt can activate several:

• "Generate a financial-projection deck from this Excel file" → activates xlsx, data-viz, pptx, and web-design.
• "Push the auth page design into Figma" → activates figma-use and figma-generate-design.
• "Review my branch for security issues" → activates security-review, plus github-pr-ops if there's an open PR.

Skills don't talk to each other — they each contribute instructions, and Claude orchestrates.

8. Skills vs. slash commands vs. MCP vs. memory

These layer. A skill can call MCP tools. A slash command can suggest a skill. See Commands and MCP for deeper dives.

9. Skill lifecycle in a session

1. Session start: loader scans skills directories, parses frontmatter, registers (name, description) pairs.
2. User sends a prompt: Claude sees prompt + all registered pairs.
3. Selection: Claude decides relevant skills and loads their full SKILL.md bodies.
4. Execution: skill body becomes part of working memory. It may call tools, read bundled files, or write outputs.
5. Hand-off: irrelevant skills "fade". New skills can activate later in the same session.

10. Best-practice patterns

• One job per skill. Split "do-everything-with-pdf" into fill / merge / extract.
• Front-load the description. Trigger phrases in the first sentence.
• Lazy-load heavy reference. Don't dump 10K tokens of API docs into SKILL.md.
• Prefer scripts to inline code for anything deterministic.
• Test the trigger. Ask Claude variations of expected prompts; confirm it activates.
• Version when you ship. Pin and bump on breaking changes.