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
4 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
This is still an issue
This was fixed in v2.1.76 — Unknown fields in plugin.json are now ignored instead of failing validation and breaking skill/command registration. If you're still seeing this in the latest version, please comment with your version and repro and we'll reopen.
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.