Skills consume full token count at startup instead of progressive disclosure (frontmatter only)

[atournayre]

Problem

According to the skills documentation, skills should use progressive disclosure:

"Claude reads these files only when needed, using progressive disclosure to manage context efficiently."

The expected behavior:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude

Observed behavior

Running /context shows skills consuming their full token count at startup, not just the frontmatter:

Skills and slash commands · /skills

Plugin
└ Skill Development: 5.5k tokens
└ Command Development: 4.6k tokens
└ Hook Development: 3.9k tokens
└ plugin-dev:create-plugin: 3.7k tokens
└ Plugin Structure: 3.2k tokens
└ MCP Integration: 3.0k tokens
...

These are from the official claude-plugins-official/plugin-dev plugin.

The irony

The "Skill Development" skill (5.5k tokens) explicitly states:

"Keep SKILL.md lean: Target 1,500-2,000 words"

Yet it contains ~5000+ words in its body, and appears to be fully loaded at startup.

Questions

1. Is /context showing the total potential size or what's actually loaded?
2. If progressive disclosure works correctly, why do skills show full token counts?
3. If the full body IS loaded at startup, is this intended behavior or a bug?

Impact

With multiple plugins installed, skills alone consume 50k+ tokens before any conversation starts, severely limiting the usable context window.

Environment

• Claude Code version: 2.0.74
• OS: Linux
• Multiple plugins installed from official marketplace

Expected behavior

Only frontmatter (~100 tokens per skill) should be loaded at startup. The body should load only when the skill is invoked.

[atournayre]

Additional UX concern

If the workaround is to enable/disable plugins per task, this creates significant friction:

• Working on Symfony feature → enable symfony plugin, disable others
• Switching to git operations → enable git plugin, disable symfony
• Back to coding → re-enable dev plugins

This defeats the purpose of having a plugin ecosystem. Users shouldn't have to manually manage plugin state for every context switch.

Suggested solutions:

1. Fix progressive disclosure - Only load frontmatter at startup (as documented)
2. Lazy loading - Load skill bodies on first invocation, cache for session
3. Context-aware loading - Auto-detect relevant plugins based on current task/files
4. Plugin profiles - Quick-switch between plugin sets (e.g., "symfony-dev", "git-ops")

The current state makes multi-plugin workflows impractical for users with limited context windows.

[github-actions]

Found 2 possible duplicate issues:

1. [BUG] /context command shows full skill tokens instead of loaded metadata tokens #14834
2. [BUG] Commands are now apparently "skills" and are loaded into context without being invoked. This effectively removes command functionality from Claude Code #14851

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[dpaluy]

Controlled Test Confirms: Full Content Loading (Not Display Bug)

I ran a controlled experiment to definitively answer the question raised in this issue.

Test Methodology

Created a minimal test skill with known token sizes:

---
name: test-token-measurement
description: Test skill for measuring token loading behavior.
---

# Test Skill

This is additional content that should NOT load if only descriptions are loaded at startup.

## Section One
Lorem ipsum dolor sit amet...
[~200 tokens total content]

Expected vs Actual

Loading Behavior	Expected Tokens
Description only (per docs)	~10-15 tokens
Full content	~170-220 tokens

Actual result from /context:

└ test-token-measurement: 156 tokens

Conclusion

156 tokens ≈ full content, NOT description-only (~10-15)

This proves:

1. /context shows actual token consumption, not "potential maximum"
2. Skills are fully loaded at startup, contradicting documentation which states: "At startup, Claude loads only the name and description of each available Skill"
3. This is a loading behavior issue, not just a display bug (contra [BUG] /context command shows full skill tokens instead of loaded metadata tokens #14834)

Additional Evidence

Skill	Expected (description-only)	Actual	Matches
agent-sdk-guide	~60 tokens	1.8k tokens	Full content ✓
brainstorming	~50 tokens	566 tokens	Full content ✓
test-token-measurement	~15 tokens	156 tokens	Full content ✓

Environment

• Claude Code v2.0.76
• macOS Darwin 25.1.0
• Model: claude-opus-4-5-20251101

Related

• [Bug] Project skills loading full files instead of frontmatter during discovery phase #15530 - Same finding with project skills
• [BUG] /context command shows full skill tokens instead of loaded metadata tokens #14834 - Claims display-only bug (this test disproves that theory)