User skills in ~/.claude/skills/ fully loaded into context instead of frontmatter-only

Resolved 💬 6 comments Opened Jan 7, 2026 by kfirba Closed Feb 22, 2026

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

  1. Create a skill file at ~/.claude/skills/my-skill/SKILL.md with frontmatter and substantial content
  2. Start a new Claude Code session
  3. Run /context to view token breakdown
  4. 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).

View original on GitHub ↗

This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗