Plugin Creator
Overview
Plugins are shareable packages that bundle skills, agents, commands, hooks, MCP servers, and LSP servers into installable units for Claude Code. A plugin requires only a .claude-plugin/plugin.json manifest at minimum; all other components are optional and auto-discovered from conventional directories at the plugin root.
When to use: Sharing functionality across projects or teams, distributing through marketplaces, versioning reusable agent capabilities, bundling MCP servers with skills.
When NOT to use: Single-project customizations (use .claude/ directory instead), quick experiments before packaging, personal workflows that do not need distribution.
Quick Reference
| Component | Location | Format | Discovery | ||
|---|---|---|---|---|---|
| Manifest | .claude-plugin/plugin.json | JSON | Required | ||
| Skills | skills/*/SKILL.md | Markdown + YAML | Auto by context | ||
| Commands | commands/*.md | Markdown + YAML | Auto, namespaced | ||
| Agents | agents/*.md | Markdown + YAML | Auto, /agents UI | ||
| Hooks | hooks/hooks.json | JSON | Auto on events | ||
| MCP servers | .mcp.json | JSON | Auto on enable | ||
| LSP servers | .lsp.json | JSON | Auto on enable | ||
| Output styles | Custom path | Per config | Via manifest | ||
| Plugin env var | ${CLAUDE_PLUGIN_ROOT} | Absolute path | All configs/scripts | ||
| Project env | ${CLAUDE_PROJECT_DIR} | Absolute path | All configs/scripts | ||
| CLI test flag | --plugin-dir./my-plugin | Local dev | Manual load | ||
| CLI validate | claude plugin validate. | Local dev | Manual check | ||
| Install scope | `--scope user\ | project\ | local` | CLI flag | Per install |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Placing components inside .claude-plugin/ | Only plugin.json goes in .claude-plugin/; components at plugin root |
| Using absolute paths in configs | Use ${CLAUDE_PLUGIN_ROOT} for all plugin file references |
Missing plugin.json manifest | Create .claude-plugin/plugin.json with at least a name field |
Path traversal with ../ | Keep all files inside the plugin directory |
| Non-executable hook scripts | Run chmod +x on all scripts referenced by hooks |
| Forgetting namespacing | Plugin skills are invoked as /plugin-name:skill-name |
| Inline hooks missing event casing | Event names are case-sensitive: PostToolUse, not postToolUse |
| Expecting custom paths to replace defaults | Custom component paths supplement default directories, not replace them |
Delegation
- Plugin component creation: Build skills, agents, and commands following their respective standards
- Pattern discovery: Use
Exploreagent to find existing plugin patterns in the codebase - Code review: Use
Taskagent for plugin structure validation
If themeta-skill-creatorskill is available, delegate skill authoring within plugins to it. Otherwise, recommend:npx skills add oakoss/agent-skills --skill meta-skill-creator