How the Skill Loading Mechanism Works in Claude: A Three-Level Demand-Driven Architecture

Claude uses a three-level, demand-driven loading system that scans for triggers in SKILL.md files, loads lightweight metadata first, and defers heavy script execution until a skill is actually needed, minimizing token usage while maintaining full functionality.

The skill loading mechanism in Claude powers the dynamic execution of modular capabilities without bloating the model's context window. Implemented in the anthropics/skills repository, this architecture employs a sophisticated three-tier approach to balance performance with functionality. Understanding how Claude loads skills helps developers optimize their own skill implementations for token efficiency and response speed.

The Three-Level Demand-Driven Loading System

Claude's skill loading mechanism operates through distinct phases designed to keep the context window lean while ensuring complete functionality when required.

Level 1: Trigger Detection via SKILL.md

The process begins with trigger detection. Claude scans the user request for cues that match the "When to Use This Skill" sections defined in a skill's SKILL.md file. According to the source code at skills/skill-creator/SKILL.md line 312, when a matching cue is detected, the skill is marked as triggered and the loading process advances to the next level.

Level 2: Metadata Loading (FORMS.md, REFERENCE.md, EXAMPLES.md)

Once triggered, Claude loads only the lightweight metadata files rather than the full skill implementation. As documented at line 117 in skills/skill-creator/SKILL.md, this includes:

• FORMS.md: Structured schemas defining required inputs and parameters
• REFERENCE.md: Short reference tables and lookup data
• EXAMPLES.md: Concise usage examples that guide application

These metadata files contain sufficient information for Claude to decide how to apply the skill without pulling in the full implementation, keeping token usage minimal during the decision phase.

Level 3: Conditional Body Loading and Script Execution

The heavy-weight Body—containing executable scripts, large markdown bodies, or binary assets—is not loaded automatically. According to line 146 in skills/skill-creator/SKILL.md, Claude loads the Body only after it has confirmed the trigger and collected any required form data.

When execution is required, Claude pulls in the relevant script files (e.g., scripts/*.py inside the skill folder) and executes them in the runtime environment provided by the Claude API. The results are then returned to the model as part of the response.

Session Caching and Performance Optimization

Once a skill's Body has been loaded, it stays in the session's context for the remainder of the interaction. As noted at line 150 in skills/skill-creator/SKILL.md, this caching mechanism avoids repeated fetches if the same skill is used multiple times within a single conversation.

This architecture delivers significant token efficiency—only a few hundred tokens of metadata are kept in context most of the time, dramatically reducing the cost of long conversations. It also ensures deterministic behavior, as the Body only runs when explicitly needed, preventing irrelevant skill code from influencing the model's outputs.

Practical Example: Skill Directory Structure

Below is a minimal skill folder that demonstrates the loading stages described above:

my-skill/
├─ SKILL.md                # Contains "When to Use" and loading notes

├─ FORMS.md                # JSON schema loaded at step 2

├─ REFERENCE.md            # Reference tables loaded at step 2

├─ EXAMPLES.md             # Usage examples loaded at step 2

└─ scripts/
   └─ process.py           # Heavy implementation loaded only at step 4

SKILL.md (excerpt):

## When to Use This Skill

Ask the model to *summarize a CSV file* → trigger.

### Loading strategy

- Claude loads FORMS.md, REFERENCE.md, EXAMPLES.md first.  
- The full `process.py` body is fetched only after the trigger is confirmed.  

When a user says: "Please summarize the sales-data.csv I just uploaded," Claude matches the "When to Use" cue, loads the small metadata files, decides the skill applies, then pulls in scripts/process.py to actually read the CSV and generate the summary.

Summary

• Three-level architecture: Claude employs trigger detection, metadata loading, and conditional body loading to balance functionality with token efficiency.
• Demand-driven loading: Only lightweight metadata (FORMS.md, REFERENCE.md, EXAMPLES.md) enters the context initially; heavy scripts remain unloaded until execution is confirmed.
• Session caching: Once loaded, skill bodies persist for the duration of the conversation to avoid redundant fetches.
• Source locations: The loading logic is documented in skills/skill-creator/SKILL.md at lines 117, 146, 150, and 312.

Frequently Asked Questions

What triggers the skill loading mechanism in Claude?

The mechanism triggers when Claude detects cues in the user request that match the "When to Use This Skill" sections defined in a skill's SKILL.md file. According to line 312 in skills/skill-creator/SKILL.md, this pattern matching determines whether the skill is relevant to the current conversation before any heavy loading occurs.

Why does Claude load metadata before the skill body?

Claude loads metadata files (FORMS.md, REFERENCE.md, EXAMPLES.md) first to minimize token usage while still gathering enough information to decide how to apply the skill. As documented at line 117 in skills/skill-creator/SKILL.md, these lightweight files contain structured schemas and examples that guide Claude's decision-making without requiring the heavy implementation code to enter the context window.

How does session caching affect skill performance?

Once a skill's body is loaded, it remains in the session's context for the remainder of the interaction. According to line 150 in skills/skill-creator/SKILL.md, this caching prevents repeated fetches when the same skill is invoked multiple times within a single conversation, significantly reducing latency and API costs for multi-turn interactions that rely on the same skill.

Where is the skill loading logic documented in the source code?

The primary documentation for the skill loading mechanism resides in skills/skill-creator/SKILL.md within the anthropics/skills repository. Key implementation details are found at specific line references: line 312 covers trigger detection, line 117 explains metadata loading, line 146 details conditional body loading, and line 150 describes session caching behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}