# How the Skill Loading Mechanism Works in Claude: A Three-Level Demand-Driven Architecture > Discover how Claude's skill loading mechanism uses a three-level demand-driven architecture to minimize token usage while ensuring full functionality. Learn about efficient metadata loading and deferred script execution to boos... - Repository: [Anthropic/skills](https://github.com/anthropics/skills) - Tags: internals - Published: 2026-02-16 --- **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`](https://github.com/anthropics/skills/blob/main/SKILL.md)** file. According to the source code at [`skills/skill-creator/SKILL.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md), this includes: - **[`FORMS.md`](https://github.com/anthropics/skills/blob/main/FORMS.md)**: Structured schemas defining required inputs and parameters - **[`REFERENCE.md`](https://github.com/anthropics/skills/blob/main/REFERENCE.md)**: Short reference tables and lookup data - **[`EXAMPLES.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md) (excerpt)**: ```markdown ## 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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/FORMS.md), [`REFERENCE.md`](https://github.com/anthropics/skills/blob/main/REFERENCE.md), [`EXAMPLES.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md) file. According to line 312 in [`skills/skill-creator/SKILL.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/FORMS.md), [`REFERENCE.md`](https://github.com/anthropics/skills/blob/main/REFERENCE.md), [`EXAMPLES.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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.