User skills in ~/.claude/skills/ fully loaded into context instead of frontmatter-only
Description
User skills placed in ~/.claude/skills/ are being fully loaded into context at startup, consuming significant tokens. According to the documentation, skills should only load frontmatter (name + description) at discovery time, with full content loaded on-demand when the Skill tool is invoked.
Expected Behavior
From the skills documentation:
Discovery: "At startup, Claude loads only the name and description of each available Skill."
User skills should behave identically to plugin skills - load ~20-50 tokens per skill (just frontmatter), not the full file content.
Actual Behavior
User skills in ~/.claude/skills/ are fully loaded into context:
Skills and slash commands · /skills
User
└ multi-agent-patterns: 5.9k tokens ← Should be ~50 tokens
└ subagent-driven-development: 2.7k tokens ← Should be ~50 tokens
└ consulate: 1.7k tokens ← Should be ~50 tokens
Plugin
└ brainstorming: 566 tokens ← Plugin skills show correct behavior
└ writing-plans: 785 tokens
...
Total: ~10.3k tokens consumed instead of ~150 tokens expected.
Steps to Reproduce
- Create a skill file at
~/.claude/skills/my-skill/SKILL.mdwith frontmatter and substantial content - Start a new Claude Code session
- Run
/contextto view token breakdown - Observe user skills show full token count, not just frontmatter
Environment
- Claude Code version: 2.0.76
- Platform: macOS (Darwin 25.2.0)
Workaround
Converting user skills to a local plugin format (with .claude-plugin/plugin.json) causes them to load correctly (frontmatter-only at startup).
This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗