[BUG] User-defined Skills load full content at startup, violating the documented progressive disclosure mechanism

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

According to the official documentation, Skills should follow a progressive disclosure mechanism:

As explicitly stated in the docs: - "At startup, Claude scans every skill's metadata for the name and description" - "When you're chatting with Claude and ask it to do something relevant, it realizes it needs the skill and reads the rest of the primary file" - "Skills use a filesystem-based architecture that enables progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront"

However, the actual behavior contradicts the documented behavior.

What Should Happen?

Expected Behavior ✅

1. At startup: Only the name and description fields (metadata) of each skill are loaded.
2. On invocation: The full content of SKILL.md is loaded only when the user actually triggers the skill (e.g., via /skill-name).
3. Token usage: Skills should consume minimal tokens at startup (metadata only).

Error Messages/Logs

When inspecting token usage with the `/context` command, the following is observed:


Skills and slash commands · /skills

User
└ feat-exec: 1.2k tokens
└ feat-plan: 651 tokens


**Issues:**
- These two user skills consumed **1.85k tokens at startup**
- The skills were **never invoked**
- This indicates the system loaded the **entire skill content** at startup, not just the description

Steps to Reproduce

1. Define one or more user skills in ~/.claude/skills/ or .claude/commands/
2. Start a new Claude Code session
3. Without invoking any skill, run the /context command
4. Check the "Skills and slash commands" section for token usage

Expected: Minimal token usage (~50 tokens per skill for metadata only)
Actual: Full skill content loaded (hundreds to thousands of tokens per skill)

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.76 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_