How Claude Skills Work Internally

Loading lesson…

Further Reading: The Internal Mechanism of Claude Skills

Next, we will go deeper into how Claude Skills work internally, so you not only know how to use them, but also understand why they are designed this way.

First-principles view: prompt-based dynamic context injection

First, understand one key fact: Skills are not executable code.

Skills are essentially advanced instructions, or prompts, that are "injected" into Claude's context when needed. This design is called "Prompt-based Dynamic Context Injection & Meta-Tool Architecture."

┌─────────────┐      ┌─────────────┐      ┌──────────────┐
│ User Request│ ───> │ LLM Matches │ ───> │ Trigger Skill│
└─────────────┘      │Description  │      └──────────────┘
                     └─────────────┘              │
                                                 ▼
                                          ┌──────────────┐
                                          │ Inject Full  │
                                          │ Instructions │
                                          └──────────────┘
                                                 │
                                                 ▼
                                          ┌──────────────┐
                                          │ Execute Task │
                                          └──────────────┘

Three-layer progressive loading architecture (token optimization)

To handle a large number of Skills without consuming too many tokens, Claude uses a smart three-layer loading mechanism:

Layer	Content	When loaded	Token cost
Layer 1: Metadata	YAML frontmatter (`name + description`)	When Claude starts	~30-50 tokens/skill
Layer 2: Instructions	Full `SKILL.md` content	When the Skill is triggered	~5,000 tokens
Layer 3: Resources	Scripts, templates, references	Accessed from the file system on demand	Not added to context

Advantages of this design:

Suppose you have 100 Skills. At startup, only about 3,000-5,000 tokens are consumed for metadata
Only the triggered Skill loads its full content
Resource files such as reference documents are never fully loaded into the context

Compared with no Skills:

Without Skills: every conversation needs 50,000+ tokens to describe all capabilities
With Skills: startup ~100 tokens/skill + 5,000 tokens loaded on demand
Savings: on average 40,000+ tokens saved per conversation

Dual context injection mechanism

When a Skill is activated, the system makes two modifications at the same time:

1. Conversation context injection

// What the user sees (visible message)
<command-message>The "pdf" skill is loading</command-message>

// What the AI actually receives (hidden meta-message)
{
  isMeta: true,  // marked as a meta-message, not shown in the UI
  content: `
    # PDF Analysis Expert Instructions

    You are a professional PDF analysis expert. Workflow:
    1. Use pdftotext to extract text
    2. Analyze the document structure
    3. Generate a summary report
    ...
  `  // full SKILL.md content, possibly thousands of words
}

2. Execution context modification

Besides injecting instructions, a Skill can also dynamically modify Claude's environment:

Modification type	Example	Explanation
Tool permissions	`allowed-tools: "Bash(pdftotext:*)"`	Temporarily grant access to a specific tool
Model switching	Switch from Sonnet to Opus	Some complex tasks require stronger reasoning
Context isolation	Create a child session space	Avoid polluting the main conversation context

A routing mechanism based entirely on LLM reasoning

This is a very important design decision: Claude Skills do not use hardcoded routing.

Traditional approach	Claude Skills
❌ Embedding vector matching	✅ Pure LLM reasoning
❌ Classifier	✅ Transformer forward pass
❌ Regex or keyword matching	✅ Natural language understanding
❌ Separate routing algorithm	✅ Unified model decision-making

Workflow:

1. The name and description of every Skill are formatted into the Skill tool description

2. Claude receives:
   - the user message
   - the list of available tools, including the Skill meta-tool
   - the Skill list, with name + description

3. Claude's natural language understanding matches the user's intent to a Skill description

4. When the match succeeds, it calls: command: "skill-name"

Why design it this way?

Hardcoded routing requires:

extra maintenance cost
no ability to understand complex semantic relationships
difficulty handling multiple languages
no support for fuzzy matching

Pure LLM reasoning:

leverages Claude's own language understanding
automatically handles multiple languages, synonyms, and fuzzy descriptions
requires no extra maintenance
makes routing decisions more intelligent

File parsing mechanism

SKILL.md file structure:

my-custom-skill/
├── SKILL.md              # Required: core definition file
├── config.json           # Optional: metadata config
├── README.md             # Recommended: usage documentation
├── scripts/              # Optional: executable scripts
├── templates/            # Optional: template folder
└── references/           # Optional: reference documents

Parsing flow:

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code startup                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Scan ~/.claude/skills/ and .claude/skills/ directories    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Use the gray-matter library to parse each SKILL.md        │
│  YAML frontmatter                                           │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Validate required fields (name and description)           │
│  - name: max 64 characters, only lowercase letters,        │
│    numbers, and hyphens                                     │
│  - description: used for LLM automatic matching            │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Extract metadata and build the Skill list                 │
│  (only load name + description, not the full body)         │
└─────────────────────────────────────────────────────────────┘

Example of the full execution flow

Let's look at the entire flow through a concrete example:

User: "Help me analyze this PDF file"

═══════════════════════════════════════════════════════════════

Step 1: LLM decision
────────────────
Claude finds the description of the "pdf" skill in the Skill list:
  description: "Analyze PDF document content, extract text, generate a summary"

═══════════════════════════════════════════════════════════════

Step 2: System intervention
────────────────
Claude Code executes:
  1. Read ~/.claude/skills/pdf/SKILL.md
  2. Generate a visible message: "The pdf skill is loading"
  3. Generate a hidden meta-message: the full SKILL.md content
  4. Modify session permissions: allowed-tools = ["Bash(pdftotext:*)"]

═══════════════════════════════════════════════════════════════

Step 3: LLM execution
────────────────
Now Claude's context contains:
  - the original user request
  - the PDF expert workflow instructions
  - access permission to the pdftotext tool

Claude executes:
  1. Use pdftotext to extract the PDF text
  2. Analyze the content structure
  3. Generate a summary report
  4. Present the result to the user

═══════════════════════════════════════════════════════════════

Step 4: Dispose after use
────────────────
After the task is completed, the full Skill content is removed from context
(only the conversation history remains, not the full Skill instruction)

Core design innovations

Innovation	Traditional approach	Skills approach	Advantage
Source of capability	Fixed in model weights	Dynamically loaded prompts	Extensible and updatable
Token efficiency	All capabilities always stay in memory	Load on demand	Save 80%+ tokens
Knowledge management	Scattered in conversation history	Modular file system	Version-controllable and shareable
Lifecycle	Continuously occupies space	Dispose after use	Cleaner context

Academic foundations

The design of Claude Skills draws on the following research:

Research field	Representative work	Applied here as
Reinforcement learning	Voyager (2023)	The idea of accumulating a skill library
Cognitive architecture	ACT-R, Soar	Separation of procedural memory and declarative memory
Hierarchical policy	Options Framework	Three-layer progressive loading

Core shift in thinking:

Traditional: AI needs to remember everything
      ↓
Skills: AI knows where to find specialized knowledge
      ↓
Result: more like the thinking pattern of a human expert

Relationship to the Agent Skills standard

Claude Skills follows the Agent Skills open standard, which means:

✅ Cross-platform compatibility: tools such as Cursor, Windsurf, and Aider also support it
✅ Unified file format: standardized SKILL.md structure
✅ Interoperability: Skills can be shared across different tools

Agent Skills standard defines:
├── Required: SKILL.md file (metadata + instructions)
├── Optional: scripts/ (executable code)
├── Optional: references/ (knowledge base documents)
└── Optional: assets/ (templates and resources)

Summary: why is this design brilliant?

Decouples capability from the model: specialized knowledge no longer depends on model training and can be updated at any time through Markdown files
Extreme token efficiency: the three-layer loading mechanism ensures only necessary content is loaded
Uses the LLM's own strengths: routing and matching rely entirely on Claude's language understanding, with no extra algorithm required
Developer-friendly: creating a Skill only requires writing Markdown, not programming
Composable: Skills can reference and combine with each other to form complex workflows
Dispose after use: automatically cleans up after completion and keeps context fresh

Summary

Skills are the key to turning Claude Code from a "general assistant" into a "team expert."

Through Skills, you can:

standardize workflows
reuse team knowledge
improve collaboration efficiency
reduce repeated explanation

Remember: if you find yourself repeating the same instruction twice, you should consider creating a Skill.

Now go create your first Skill.