claude-api skill inlines ~500KB (~130K+ tokens) of reference docs into every invocation

Summary

The bundled claude-api skill inlines nearly all of its reference documentation directly into the skill body via <doc path="..."> blocks, instead of using progressive disclosure (keeping reference docs on disk and letting the agent Read them on demand). As a result, a single Skill(claude-api) invocation injects roughly 500KB of raw markdown (~130K+ tokens) into the conversation context — even for narrow requests that touch only a small fraction of that content.

Measurements (CLI 2.1.220)

Skill directory: bundled-skills/2.1.220/<hash>/claude-api/

• shared/model-migration.md alone: 174KB — concatenates full migration guides for Opus 4.6→4.7→4.8→Opus 5, Sonnet 4.6→5, and Fable 5, each with extensive behavioral-shift writeups and checklists.
• 14 shared/managed-agents-*.md files (core, api-reference, tools, events, webhooks, memory, multiagent, onboarding, outcomes, overview, scheduled-deployments, self-hosted-sandboxes, client-patterns, environments) — roughly 230KB combined, all inlined even when the user's task has nothing to do with Managed Agents.
• Other large shared docs inlined regardless of relevance: tool-use-concepts.md (32KB), managed-agents-api-reference.md (32KB), managed-agents-core.md (24KB), live-sources.md (19KB), managed-agents-events.md (18.5KB), prompt-caching.md (16KB), anthropic-cli.md (16KB), error-codes.md / models.md (~12KB each).
• Total shared/ directory: 494KB.
• On top of that, when no target file/language is detected, the skill defaults to inlining the entire typescript/claude-api/*.md + typescript/managed-agents/README.md (~55KB) regardless of whether the user's project is TypeScript.
• Total for one invocation with no specific ask: ~549KB (~130K+ tokens).

By contrast, the per-language directories (python/, go/, java/, ruby/, csharp/, php/, curl/) are correctly not inlined — they're left on disk for on-demand Read. The shared/*.md docs (and the auto-selected language docs) don't follow that same pattern, even though they're the largest offenders.

Impact

A user invoking /claude-api for a small, narrow task (e.g. "why did my token count change", "what's the pricing for X") pays the full ~130K-token context cost up front, even though 90%+ of the inlined content (all of Managed Agents, migration guides for every model version except the one they're using, etc.) is irrelevant to that task. This bloats context on every invocation, crowds out the rest of the conversation, and increases cost regardless of whether any of it is used.

Suggested fix

Convert the shared/*.md docs — especially model-migration.md and the managed-agents-*.md family — from inline <doc> blocks into file references the agent is instructed to Read on demand, the same way the per-language folders already work. The routing tables already present in the skill (e.g. "Quick Task Reference", "Reading Guide") point to the right file per use case — they just need to stop being pre-loaded and instead trigger an on-demand Read of that specific file. This preserves full reference coverage while letting narrow requests skip the large majority of content that isn't relevant.