Unknown fields in plugin.json break skill and command registration
Summary
When plugin.json contains unknown root-level fields, Claude Code fails to register the plugin's skills and commands. However, the underlying scripts still execute when invoked directly. This indicates the issue is in component registration, not plugin loading.
See #20409 for a related feature request focused on discoverability and error disclosure for this class of issue.
Reproduction Steps
- Add an unknown field to a plugin's
plugin.json:
{
"name": "context-explorer",
"version": "0.1.0",
"test-unknown-field": "any value"
}
- Clear cache and restart Claude Code
- Test components:
Skill(skill: "context-exploration") → "Unknown skill"
/context-explorer:cx → "Unknown skill: context-explorer:cx"
python ~/.claude/plugins/cache/.../cx.py → Works fine
Observed Behavior
| Component | Status | Notes |
|-----------|--------|-------|
| Skills | ❌ Fail | "Unknown skill" error |
| Commands (slash) | ❌ Fail | "Unknown skill: plugin:command" |
| Scripts (direct) | ✅ Work | Python/bash scripts execute normally |
| Plugin in claude plugin list | ✅ Shows | Plugin appears to be loaded |
Expected Behavior
Either:
- Reject plugin at load time with clear error message, or
- Warn but register components anyway (lenient parsing)
Current silent partial failure is the worst outcome - plugin appears loaded but components don't work.
Root Cause Hypothesis
The plugin loader likely:
- Parses
plugin.json - Encounters unknown field
- Skips component registration (skills, commands)
- Still adds plugin to list (partial success)
Environment
- Claude Code version: (current)
- OS: Linux
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗