Concept: Skill Loading Architecture
Skill Loading Architecture is the two-phase context loading mechanism employed by modern agentic LLM platforms (such as claude-code, codex, and ChatGPT Work) to manage capability tools without overwhelming model context limits.
Two-Phase Loading Mechanism
Instead of loading the complete instruction set of every installed tool or skill into context upon session initialization, agent systems execute a two-stage lazy-loading sequence:
+-------------------------------------------------------------------+
| Stage 1: Session Start (Routing Phase) |
| Agent loads ONLY Skill Name + Teaser Description (~20-50 tokens) |
+-------------------------------------------------------------------+
|
Matching Prompt Detected
v
+-------------------------------------------------------------------+
| Stage 2: Task Execution (Invocation Phase) |
| Agent loads full skill.md, instructions, scripts & templates |
+-------------------------------------------------------------------+
Stage 1: The Teaser Trailer (Routing Phase)
- During initial task evaluation, the agent scans an inventory of installed skills, loading only the
nameand shortdescriptionfield from each skill’s YAML frontmatter. - This lightweight inventory acts like a “teaser trailer,” allowing the agent to evaluate whether a skill matches the user’s intent without consuming substantial context tokens.
Stage 2: Deep Context Hydration (Execution Phase)
- Only when the task requirements match a skill’s description does the agent invoke the skill, dynamically reading the full
skill.mdfile, procedural guidelines, scripts, and edge-case templates into context.
Failure Modes & Optimization Rules
Because routing decisions depend entirely on Stage 1 descriptions, poorly authored skill descriptions create severe operational failure modes:
| Description Flaw | Operational Impact | Fix / Remediation |
|---|---|---|
| Vague / Sparse Description | The agent fails to recognize when the skill is required; the skill is never invoked (“invisible skill”). | Write explicit, trigger-focused descriptions defining exact input types and task goals. |
| Overly Broad Description | The skill description triggers on unrelated user queries, dragging massive instructions into context unnecessarily and causing token bloat. | Narrow the description boundaries to specific keywords, file extensions, or workflow triggers. |
| Bloated Frontmatter | Placing full procedural rules inside the Stage 1 description clutters the agent’s routing layer, triggering early routing failures (especially in chatgpt-5-6 / Codex). | Keep description text under 2-3 concise sentences; move procedural guidelines inside the body of skill.md. |