Unknown fields in plugin.json break skill and command registration

Resolved 💬 4 comments Opened Jan 23, 2026 by kitaekatt Closed Apr 18, 2026

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

  1. Add an unknown field to a plugin's plugin.json:
{
  "name": "context-explorer",
  "version": "0.1.0",
  "test-unknown-field": "any value"
}
  1. Clear cache and restart Claude Code
  1. 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:

  1. Reject plugin at load time with clear error message, or
  2. 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:

  1. Parses plugin.json
  2. Encounters unknown field
  3. Skips component registration (skills, commands)
  4. Still adds plugin to list (partial success)

Environment

  • Claude Code version: (current)
  • OS: Linux

View original on GitHub ↗

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