Plugin-dev skill should warn against using plugin.json with explicit components

Problem

The plugin-structure skill in plugin-dev describes two approaches for defining plugin components:

1. Auto-discovery - Claude Code scans commands/, agents/, skills/ directories
2. Explicit plugin.json - Define components in .claude-plugin/plugin.json

However, using approach #2 (explicit plugin.json with components field) breaks plugin loading. Commands don't appear, even though the plugin shows as "installed."

Steps to Reproduce

1. Create a plugin with this structure:

``
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Has "components": { "commands": [...] }
└── commands/
└── my-command.md
``

1. Install via marketplace
2. Restart Claude Code
3. Commands don't appear in autocomplete

Expected Behavior

Either:

• Explicit plugin.json components should work, OR
• The plugin-structure skill should clearly warn that this approach doesn't work

Actual Behavior

• Plugin shows as installed
• Commands are never discovered
• No error messages indicate the problem

Solution Found

Removing .claude-plugin/plugin.json entirely and relying on auto-discovery fixed the issue. The working plugin-dev plugin itself doesn't have a plugin.json - it uses pure auto-discovery.

Suggested Documentation Update

Add a warning to the plugin-structure skill:

⚠️ Important: Most production plugins rely on auto-discovery and do NOT include a plugin.json. Having an explicit components field may interfere with command/agent loading. Only use plugin.json if you need custom metadata - omit the components field and let auto-discovery handle component registration.

Environment

• Claude Code v2.0.54
• macOS

---

🤖 Generated with Claude Code