Central authority for Claude Code plugins. Covers plugin creation, plugin structure (plugin.json, commands/, agents/, skills/, hooks/), plugin manifest configuration, plugin installation and management (/plugin command), plugin marketplaces (marketplace.json, adding marketplaces), team plugin workflows, plugin development and testing, plugin debugging, plugin sharing and distribution, MCP servers in plugins, and plugin settings. Assists with creating plugins, installing from marketplaces, configuring team plugins, and troubleshooting plugin issues. Delegates 100% to docs-management skill for official documentation.
Central authority for Claude Code plugin management. Triggers when users create plugins, configure manifests, install from marketplaces, or debug plugin issues. Delegates all official documentation to docs-management skill.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install claude-code-observability@melodic-softwareThis skill is limited to using the following tools:
references/audit-framework.mdreferences/plugin-hook-consumer-config.mdreferences/plugin-hook-utilities.mdreferences/reserved-marketplace-names.mdSTOP - Before providing ANY response about Claude Code plugins:
- INVOKE
docs-managementskill- QUERY for the user's specific topic
- BASE all responses EXCLUSIVELY on official documentation loaded
Skipping this step results in outdated or incorrect information.
Before responding, verify:
If ANY checkbox is unchecked, STOP and invoke docs-management first.
Central authority for Claude Code plugins. This skill uses 100% delegation to docs-management - it contains NO duplicated official documentation.
Architecture: Pure delegation with keyword registry. All official documentation is accessed via docs-management skill queries.
Keywords: plugins, plugin creation, plugin structure, plugin.json, plugin manifest, plugin commands, plugin agents, plugin skills, plugin hooks, plugin marketplaces, marketplace.json, /plugin command, plugin install, plugin uninstall, plugin enable, plugin disable, plugin browse, team plugins, plugin development, plugin testing, plugin debugging, plugin sharing, plugin distribution, MCP servers plugins, plugin settings, enabledPlugins, extraKnownMarketplaces, plugin hook configuration, disable plugin hook, CLAUDE_HOOK_ENABLED, hook environment variables, configurable hooks, hook enforcement mode
Use this skill when:
Use these keywords when querying docs-management skill for official documentation:
| Topic | Keywords |
|---|---|
| Overview | "plugins", "plugin system", "extend Claude Code" |
| Quickstart | "plugin quickstart", "first plugin", "create plugin" |
| Structure | "plugin structure", "plugin directory structure" |
| Manifest | "plugin.json", "plugin manifest", "plugin metadata" |
| Topic | Keywords |
|---|---|
| Commands | "plugin commands", "commands directory plugins" |
| Agents | "plugin agents", "agents directory plugins" |
| Skills | "plugin skills", "skills directory plugins" |
| Hooks | "plugin hooks", "hooks.json plugins" |
| MCP Servers | "MCP servers plugins", ".mcp.json plugins" |
| Topic | Keywords |
|---|---|
| Install Commands | "/plugin command", "plugin install", "plugin management" |
| Enable/Disable | "plugin enable", "plugin disable", "plugin uninstall" |
| Interactive Menu | "plugin browse", "/plugin interactive" |
| Verification | "verify plugin installation", "plugin /help" |
| Topic | Keywords |
|---|---|
| Overview | "plugin marketplaces", "marketplace catalogs" |
| Adding Marketplaces | "marketplace add", "add marketplaces" |
| Marketplace Manifest | "marketplace.json", "marketplace manifest" |
| Marketplace Sources | "plugin sources", "marketplace sources" |
| Schema Fields | "metadata.pluginRoot", "strict field marketplace", "plugin entry schema" |
| Reserved Names | "reserved marketplace name", "marketplace name validation" |
| Topic | Keywords |
|---|---|
| Team Plugins | "team plugin workflows", "repository-level plugins" |
| Auto Installation | "automatic plugin installation", "team plugins setup" |
| Configuration | "team marketplaces configuration", ".claude/settings.json plugins" |
| Topic | Keywords |
|---|---|
| Development Workflow | "plugin development", "develop plugins" |
| Local Testing | "test plugins locally", "local marketplace" |
| Iteration | "plugin iteration", "reinstall plugin" |
| Organization | "organize complex plugins", "plugin organization" |
| Environment Variables | "CLAUDE_PLUGIN_ROOT", "plugin environment variables" |
| Topic | Keywords |
|---|---|
| Debugging | "debug plugin issues", "plugin debugging" |
| Debug Mode | "claude --debug", "plugin loading debug" |
| Validation | "plugin validation", "claude plugin validate" |
| Common Issues | "plugin not working", "plugin troubleshooting" |
| Topic | Keywords |
|---|---|
| Sharing | "share plugins", "plugin distribution" |
| Documentation | "plugin documentation", "plugin README" |
| Versioning | "plugin versioning", "semantic versioning plugins" |
| Marketplace Registration | "marketplace.json", "register plugin", "plugin entry", "marketplace plugins array" |
| Topic | Keywords |
|---|---|
| Plugin Settings | "plugin settings", "enabledPlugins" |
| Marketplace Settings | "extraKnownMarketplaces", "marketplace configuration" |
| Topic | Keywords |
|---|---|
| Hook Basics | "plugin hooks", "hooks.json plugins" |
| Auto-Discovery | "hooks auto-discovery", "default hooks location", "hooks.json default" |
| Manifest Format | "hooks field format", "hooks path", "hooks.json path" |
| Consumer Control | "disable plugin hook", "hook environment variables" |
| Enforcement Modes | "hook enforcement mode", "CLAUDE_HOOK_ENFORCEMENT" |
| Disable Hooks | "CLAUDE_HOOK_ENABLED", "disable specific hook" |
Note: Plugin hook configuration uses environment variables (not YAML configs like local hooks). See Plugin Hook Utilities Reference for implementation patterns and Consumer Configuration Reference for end-user guidance.
| Topic | Keywords |
|---|---|
| Auto-Discovery | "plugin auto-discovery", "default locations", "component discovery" |
| Default Paths | "plugin default paths", "default directory", "path behavior" |
| Optional Fields | "plugin optional fields", "required vs optional", "manifest optional" |
| Path Formats | "component path fields", "path format", "hooks path format" |
| Field Validation | "plugin field validation", "manifest validation", "field format" |
| Topic | Keywords |
|---|---|
| Technical Reference | "plugins reference", "plugin specifications" |
| Component Reference | "plugin components reference", "plugin schemas" |
| Manifest Path Fields | "component path fields", "custom plugin paths", "path behavior rules" |
What do you want to do?
/user-config:reset-plugins (clears cache + registry + settings)Plugin components may be auto-discovered from default locations. Query docs-management for current behavior:
Query Keywords:
Key Principle: Before flagging missing manifest fields, query docs-management to verify whether the component uses auto-discovery from a default location. Many manifest fields are optional when components exist at their default paths.
⚠️ ALWAYS register new plugins in marketplace.json - plugins are NOT discoverable until registered.
When creating a new plugin, you MUST:
.claude-plugin/plugin.json, components)marketplace.json with proper entry format/plugin command lists the new pluginQuery docs-management for current marketplace.json schema:
Common oversight: Creating a plugin but forgetting to add it to marketplace.json - the plugin will exist but be invisible to users.
IMPORTANT: Plugin data is stored in TWO locations. Both must be cleared for a complete reset:
| Location | Contains | Cleared By |
|---|---|---|
~/.claude/plugins/ | Plugin cache, registry, marketplace cache | /clear-plugin-cache (partial), /user-config:reset-plugins (complete) |
~/.claude/settings.json → enabledPlugins | Plugin enable/disable state | /user-config:reset-plugins only |
Common Confusion: /clear-plugin-cache only clears the cache directory, preserving the registry. If you see "Plugin not found in marketplace" errors after cache clearing, the enabledPlugins in settings.json still references the old plugins.
Solution: Use /user-config:reset-plugins for complete plugin reset.
Plugin hooks are automatically merged when a plugin is enabled. Unlike local hooks (.claude/hooks/), plugin hooks use environment variables for consumer control:
Environment Variable Convention:
| Variable | Values | Purpose |
|---|---|---|
CLAUDE_HOOK_{NAME}_ENABLED | 1/true (enabled), 0/false (disabled) | Enable/disable hook |
CLAUDE_HOOK_ENFORCEMENT_{NAME} | block, warn, log | Control enforcement behavior |
CLAUDE_HOOK_LOG_LEVEL | debug, info, warn, error | Logging verbosity |
Consumer Configuration via settings.json:
{
"env": {
"CLAUDE_HOOK_MARKDOWN_LINT_ENABLED": "1",
"CLAUDE_HOOK_ENFORCEMENT_SECRET_SCAN": "warn"
}
}
For Plugin Authors: See Plugin Hook Utilities Reference For Plugin Consumers: See Consumer Configuration Reference
User asks: "How do I create a plugin?"
1. Invoke docs-management skill
2. Use keywords: "plugin quickstart", "create plugin"
3. Load official documentation
4. Provide guidance based EXCLUSIVELY on official docs
User asks: "I want to create a plugin with commands, hooks, and MCP servers"
1. Invoke docs-management skill with multiple queries:
- "plugin structure", "plugin.json"
- "plugin commands", "commands directory plugins"
- "plugin hooks", "hooks.json plugins"
- "MCP servers plugins", ".mcp.json plugins"
2. Synthesize guidance from official documentation
User reports: "My plugin commands aren't showing up"
1. Invoke docs-management skill
2. Use keywords: "debug plugin issues", "verify plugin installation"
3. Check official docs for plugin structure requirements
4. Guide user through debugging based on official docs
| Issue | Keywords for docs-management |
|---|---|
| Plugin not installing | "/plugin command", "plugin install" |
| Commands not appearing | "plugin commands", "verify plugin installation" |
| Agents not available | "plugin agents", "agents directory plugins" |
| Hooks not triggering | "plugin hooks", "hooks.json plugins" |
| Marketplace not found | "marketplace add", "plugin marketplaces" |
| Team plugins not syncing | "team plugin workflows", "automatic plugin installation" |
| Plugin structure invalid | "plugin structure", "debug plugin issues" |
| MCP server not starting | "MCP servers plugins", "CLAUDE_PLUGIN_ROOT" |
| Custom paths not loading | "component path fields", "path behavior rules" |
| Plugin validation errors | "claude plugin validate", "plugin validation" |
| Hook not running | Check CLAUDE_HOOK_{NAME}_ENABLED env var in settings.json |
| Hook enforcement wrong | Check CLAUDE_HOOK_ENFORCEMENT_{NAME} env var in settings.json |
| "hooks: must end with .json" | hooks field must be file path (e.g., "./hooks.json"), not directory |
| "Name is reserved" error | See Reserved Marketplace Names Reference |
| Plugin not showing in /plugin | Check if registered in marketplace.json - see Marketplace Registration |
| Plugin errors after clearing cache | Plugin data in TWO locations: ~/.claude/plugins/ AND enabledPlugins in ~/.claude/settings.json - use /user-config:reset-plugins for complete reset |
This repository does not currently use plugins. Plugin documentation is relevant for:
When working with plugin topics, always use the docs-management skill to access official documentation.
See Reserved Marketplace Names Reference for:
This skill provides the validation criteria used by the plugin-auditor agent for formal audits.
| Resource | Location | Purpose |
|---|---|---|
| Audit Framework | references/audit-framework.md | Query guides and scoring criteria |
| Category | Points | Key Criteria |
|---|---|---|
| Manifest Structure | 25 | Valid plugin.json, required fields |
| Component Organization | 25 | Proper directories for all components |
| Namespace Compliance | 20 | Consistent naming, no conflicts |
| Documentation | 15 | README, descriptions, examples |
| Distribution Readiness | 15 | Version, marketplace requirements |
Thresholds: 85+ = PASS, 70-84 = PASS WITH WARNINGS, <70 = FAIL
The plugin-auditor agent (Haiku model) performs formal audits using this skill:
skills: plugin-development/audit-plugins commandWhen auditing plugins that use external technologies (scripts, packages, runtimes), the auditor MUST validate claims using MCP servers before flagging findings.
Technologies Requiring MCP Validation:
Validation Rule:
Never flag a technology usage as incorrect without first:
Stale Data Warning:
Official Documentation (via docs-management skill):
Repository-Specific:
.claude/settings.json (enabledPlugins, extraKnownMarketplaces)/user-config:reset-plugins commandclaude-code-plugins name is reserved for anthropics organizationCLAUDE_HOOK_{NAME}_ENABLED pattern (from deprecated CLAUDE_HOOK_DISABLED_*)is_hook_enabled() function supporting defaultsDate: 2025-12-30 Model: claude-opus-4-5-20251101
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.