From plugin-creator
Guides selection of plugin component types (commands, skills, agents, hooks, MCP servers) via decision tree, covers lifecycle phases, and organization for scaling multi-component plugins.
npx claudepluginhub jamie-bitflight/claude_skills --plugin plugin-creatorThis skill uses the workspace's default tool permissions.
Every plugin component goes through two phases — discovery at startup and activation at runtime.
Guides Claude Code plugin setup including directory structure, plugin.json manifest, component organization for commands/agents/skills/hooks, auto-discovery, and naming conventions.
Guides creation of Claude Code plugins including skills, commands, agents, hooks, MCP servers, and configuration. Use for 'create plugin', 'make skill', scaffolding structures.
Creates, converts, validates, and publishes Claude Code plugins with Agent Skills, hooks, agents, and servers. Automates manifest generation, scanning, structure validation, and marketplace prep.
Share bugs, ideas, or general feedback.
Every plugin component goes through two phases — discovery at startup and activation at runtime.
When Claude Code starts, it processes each enabled plugin:
.claude-plugin/plugin.jsonDiscovery happens once during Claude Code initialization, not continuously. Components added after startup require a session restart to become available.
Each component type activates through a different mechanism:
flowchart LR
User["User action"] --> Cmd["Command — user types /command"]
Context["Task context"] --> Skill["Skill — description matches task"]
Context --> Agent["Agent — capabilities match task"]
Event["System event"] --> Hook["Hook — event matches registration"]
ToolCall["Tool call"] --> MCP["MCP Server — capability matches call"]
SOURCE: Adapted from ../claude-plugins-official/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md lines 1-27
Use this decision tree to select the right component type for a given need.
flowchart TD
Start(["What do you need<br>to add to your plugin?"]) --> Q1{"Does it need to<br>intercept or validate<br>tool calls or events?"}
Q1 -->|"Yes — gate writes,<br>enforce policies,<br>inject context on events"| Hook["Use a Hook<br>Create with /plugin-creator:hook-creator"]
Q1 -->|No| Q2{"Does it provide<br>external tool access<br>via API or process?"}
Q2 -->|"Yes — database queries,<br>API calls, file processing<br>via external process"| MCP["Use an MCP Server<br>Create with /fastmcp-creator"]
Q2 -->|No| Q3{"Does it need its own<br>identity, tools, model,<br>or permission scope?"}
Q3 -->|"Yes — specialized worker<br>with restricted tools<br>or different model"| Agent["Use an Agent<br>Create with /plugin-creator:agent-creator"]
Q3 -->|No| Q4{"Is it domain knowledge,<br>a workflow, or a<br>procedural guide?"}
Q4 -->|"Yes — reference material,<br>multi-step process,<br>best practices"| Skill["Use a Skill<br>Create with /plugin-creator:skill-creator"]
Q4 -->|"No — simple user-triggered<br>action with bash execution"| Command["Use a Command (legacy)<br>See /plugin-creator:command-development"]
Hook --> HookNote["Events — PreToolUse, PostToolUse,<br>Stop, Notification, SubagentStop"]
MCP --> MCPNote["Transports — stdio, SSE,<br>HTTP, WebSocket"]
Agent --> AgentNote["Frontmatter — name, description,<br>tools, model, skills, hooks"]
Skill --> SkillNote["Progressive disclosure —<br>SKILL.md + references/"]
Command --> CmdNote["Legacy format —<br>prefer skills for new work"]
flowchart TD
subgraph Components["Component Capabilities"]
direction LR
H["Hook"]
M["MCP Server"]
A["Agent"]
S["Skill"]
C["Command"]
end
subgraph Traits["Key Differentiators"]
direction LR
H --- HT["Intercepts events and tool calls<br>Can block or modify operations<br>Runs on system events"]
M --- MT["Provides tools via external process<br>Persistent server with its own state<br>Accessed through tool calls"]
A --- AT["Has its own identity and tool scope<br>Can use a different model<br>Selected by capability matching"]
S --- ST["Provides knowledge and workflows<br>Activated by context matching<br>Progressive disclosure via references/"]
C --- CT["User-triggered via /name<br>Can execute bash commands<br>Legacy — skills preferred for new work"]
end
SOURCE: Decision framework derived from component capabilities documented in ../claude-plugins-official/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md and /plugin-creator:claude-plugins-reference-2026
For detailed organization patterns (directory structures, scaling strategies, when-to-use guidance) for each component type, see component organization reference.
Summary of available patterns:
flowchart TD
subgraph Commands["Command Patterns"]
CF["Flat — up to 15 commands"]
CC["Categorized — 15+ with functional groups"]
CH["Hierarchical — 20+ with nested structure"]
end
subgraph Agents["Agent Patterns"]
AR["Role-based — distinct non-overlapping roles"]
AC["Capability-based — technology or domain expertise"]
AW["Workflow-based — pipeline stage specialists"]
end
subgraph Skills["Skill Patterns"]
ST["Topic-based — knowledge and reference content"]
SL["Tool-based — specific tool or technology expertise"]
SW["Workflow-based — multi-step process automation"]
SR["Rich resources — SKILL.md + references/ + scripts/ + assets/"]
end
subgraph Hooks["Hook Patterns"]
HM["Monolithic — single hooks.json, up to 10 hooks"]
HE["Event-based — separate config per event type"]
HP["Purpose-based — grouped by security, quality, workflow"]
end
When plugins grow beyond simple single-component designs, these patterns help manage complexity.
Components can share common utilities via a lib/ directory at the plugin root:
plugin/
├── commands/
│ └── test.md # references lib/test-utils.sh
├── agents/
│ └── tester.md # references lib/test-utils.sh
├── hooks/
│ └── scripts/
│ └── pre-test.sh # sources lib/test-utils.sh
└── lib/
├── test-utils.sh
└── deploy-utils.sh
Access shared resources via ${CLAUDE_PLUGIN_ROOT}/lib/ in scripts.
Separate concerns into layers for large plugins (100+ files):
plugin/
├── commands/ # User interface layer
├── agents/ # Orchestration layer
├── skills/ # Knowledge layer
└── lib/
├── core/ # Core business logic
├── integrations/ # External service adapters
└── utils/ # Shared helper functions
Optional features as self-contained modules within the plugin:
plugin/
├── .claude-plugin/
│ └── plugin.json
├── core/
│ ├── commands/
│ └── agents/
└── extensions/
├── extension-a/
│ ├── commands/
│ └── agents/
└── extension-b/
├── commands/
└── agents/
Register extension paths in plugin.json under commands and agents arrays. Note that listing paths explicitly overrides auto-discovery — all paths must be listed or unlisted components become invisible.
SOURCE: Cross-component patterns adapted from ../claude-plugins-official/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md lines 448-535
commands/, agents/, skills/) before adding custom paths to plugin.json/plugin-creator:hook-creator/plugin-creator:agent-creator/plugin-creator:skill-creator/fastmcp-creator/plugin-creator:command-development/plugin-creator:plugin-lifecycle/plugin-creator:claude-plugins-reference-2026/plugin-creator:plugin-settings