Progressive Context Loading (Skills)

The three-level loading pattern Claude Code uses to keep skills lightweight. Level 1: initial search only reads the YAML frontmatter (name + description, ~100 tokens) of every skill. Level 2: once a skill is selected, the full skill.md is loaded (typically 1-2K tokens). Level 3: referenced files (scripts, templates, reference markdown) are loaded only if the skill's instructions explicitly require them. This lets a project carry dozens of skills without blowing context on unused ones.

Key points

  • Level 1 reads only YAML frontmatter of every skill in the project
  • Level 2 loads the full skill.md only after selection
  • Level 3 pulls referenced scripts, templates, and reference files on demand
  • Skill.md should stay under 500 lines per Anthropic guidance
  • Reference files can live inside the skill folder or anywhere the skill.md path points to
  • Enables dozens of skills in one project without proportional token cost
  • Mornati's CLI-plus-skill experiment shows why the loading boundary matters: the GitHub CLI skill is cheap when invoked for GitHub work, but expensive if copied into always-loaded files such as CLAUDE.md [src-041]
  • On-demand skills let low-frequency tools gain structured command guidance without paying the full Tool Schema Tax of Native MCP [src-041]
  • OpenAI's API & Codex Build Hour generalizes the same idea to tool search: GPT-5.4 can discover namespaced tools progressively rather than loading hundreds of tool definitions into context up front [src-084].
  • The Workspace Agents session gives the product version: agents can attach multiple skills, while concise skill descriptions and frontmatter-style summaries help the model decide when to load the detailed playbook [src-084].
  • [src-094] describes agent skills as the strongest pattern for managing dynamic context: the agent sees lightweight metadata first, loads detailed instructions only when a task matches, and pulls deeper reference material only when needed.
  • This pattern lets an agent carry many specialist capabilities without paying the full token cost for every capability in every interaction [src-094].

Related entities

Related concepts

Source references

  • [src-004] Nate Herk cluster — Nate Herk — Claude Code cluster (21 videos)

– Videos referenced: zKBPwDpBfhs, RAZVk5NPNtE

  • [src-041] Marco Mornati — "The Future of Agentic Tooling: MCP Servers vs. CLI A Data-Driven Comparison" (2026-04-27)
  • [src-084] OpenAI Codex, Workspace Agents, Prompt Caching, and Superintelligence Policy cluster (2026-02-09 to 2026-05-08)
  • [src-094] Addy Osmani, Shubham Saboo, Sokratis Kartakis – "The New SDLC With Vibe Coding" (2026-05)

Robin Cartier perspective

This page is part of Robin Cartier's working AI knowledge graph: a practical research layer for production AI, recommendation systems, experimentation, GEO, and agentic web readiness.

The useful next step is to connect this concept back to applied product leadership and operating models.

Recommended next

Keep reading from this thread

From 500 indexed pages and articles.

  1. Wiki concept On-Demand Skill Files Pattern for keeping service-specific CLI/API guidance out of the always-loaded project context until the agent actually needs that service. Related by loading
  2. Wiki concept Tool Schema Tax The fixed context cost paid when an agent runtime injects tool schemas into every prompt, regardless of whether those tools are used in Related by loaded
  3. Wiki concept Global vs Project Skills Claude Code skills can be scoped to a single project (live in .claude/skills/) or installed globally (live in ~/.claude/skills/) and available from Related by loading