Plugin Creation

Create complete Claude Code plugins with any combination of components.

When to Use

• •"Create a plugin" / "Make a new plugin"
• •"Add a skill" / "Create command" / "Make agent"
• •"Add hooks" / "Setup MCP server"
• •"Configure settings" / "Setup output directory"
• •"Package for marketplace"
• •NOT for: Using existing plugins (see /plugin command)

Quick Reference

Before Creating

1. •Read references/01-overview/component-comparison.md to decide which components needed
2. •Determine if this should be a new plugin or add to existing

Plugin Project Setup

When creating any plugin, also consider:

• •.claude/rules/ with modular project rules (path-scoped if needed for different component directories)
• •CLAUDE.md at plugin root for project conventions
• •README.md and CHANGELOG.md at plugin root (for humans — never inside skill directories)

Documentation Principles

All plugin documentation should follow lean principles:

• •Current truth only — no historical narratives or "previously we did X"
• •Replace, don't append — superseded content gets replaced entirely
• •Delete what's irrelevant — every edit is a chance to prune
• •Read references/02-philosophy/core-philosophy.md for full philosophy

Plugin Initialization

When user says "create plugin", "initialize plugin", "new plugin":

Option A - Use init script:

python scripts/init_plugin.py my-plugin --path ./plugins --components skill,command,hook

Option B - Manual creation:

1. •

   Create plugin directory structure:

   code

   plugin-name/
   ├── .claude-plugin/
   │   └── plugin.json
   ├── commands/        # if needed
   ├── agents/          # if needed
   ├── skills/          # if needed
   │   └── skill-name/
   │       └── SKILL.md
   ├── hooks/           # if needed
   │   └── hooks.json
   └── .mcp.json        # if needed
   

2. •

   Copy template from templates/plugin.json.template

3. •

   Ask user which components they need

Creating Skills

When user says "add skill", "create skill", "make skill":

1. •Read references/03-skills/writing-skillmd.md for structure
2. •Copy template from templates/skill/SKILL.md.template
3. •Key requirements:
   • •Name: lowercase, hyphens, max 64 chars
   • •Description: WHAT it does + WHEN to use it, max 1024 chars, third person
   • •Body: imperative instructions, under 500 lines
   • •Use progressive disclosure - reference files for details

Critical: SKILL.md files are INSTRUCTIONS for Claude, not documentation. Write imperatives telling Claude what to do.

Consider these optional frontmatter fields:

• •model: haiku for simple lookup/formatting skills, opus for complex reasoning
• •context: fork with agent: <type> for heavy operations that would pollute main context
• •disable-model-invocation: true for command-only skills (no auto-trigger)
• •user-invocable: false to hide from / menu (Claude can still invoke via Skill tool)

Dynamic context injection: Use !`command` in the skill body to inject runtime state (git status, file contents, etc.) when the skill loads.

Extended thinking: Include "ultrathink" in the skill body for tasks requiring deep reasoning.

Creating Commands

When user says "add command", "create command", "slash command":

1. •Read references/04-commands/writing-commands.md
2. •Copy template from templates/command/command.md.template
3. •Key requirements:
   • •Frontmatter: description, allowed-tools, argument-hint
   • •Support $ARGUMENTS, $1, $2 for arguments
   • •Prefix lines with exclamation mark for bash execution
   • •Prefix lines with at-sign for file references

Creating Agents

When user says "add agent", "create agent", "make agent":

1. •Read references/05-agents/writing-agents.md
2. •Copy template from templates/agent/agent.md.template
3. •Key requirements:
   • •Frontmatter: name, description, tools, model, permissionMode
   • •Description should include "Use proactively" for auto-delegation
   • •One agent = one clear responsibility

Consider these agent-specific features:

• •memory: project for agents that benefit from cross-session learning (architecture decisions, code review patterns)
• •memory: user for personal preferences that carry across projects
• •model: matched to task complexity — haiku for lookup/formatting, sonnet for balanced tasks, opus for complex reasoning
• •tools restriction to minimum needed (reduces cost and attack surface)
• •disallowedTools to block specific tools (e.g., Edit, Write for read-only agents)
• •hooks in agent frontmatter for scoped validation (runs only when that agent is active)

Agent teams: For tasks benefiting from multiple perspectives or parallel research, consider agent teams (competing perspectives, hypothesis investigation, parallel tasks). See references/05-agents/agent-patterns.md for team patterns. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Creating Hooks

When user says "add hooks", "setup hooks", "event handlers":

1. •Read references/06-hooks/writing-hooks.md
2. •Read references/06-hooks/hook-events.md for all 14 events
3. •Copy template from templates/hooks/hooks.json.template
4. •Key events:
   • •PreToolUse - before tool execution (can block)
   • •PostToolUse - after tool execution (formatting, logging)
   • •SessionStart - setup, output directories
   • •SessionEnd - cleanup
   • •UserPromptSubmit - validation, context injection (can block)
   • •SubagentStart/SubagentStop - agent lifecycle
   • •PreCompact - inject context before compaction
   • •Notification, Stop, TaskCompleted, TeammateIdle

Three handler types — choose the right one:

• •command — shell script, fastest, no LLM cost. Use for logging, file ops, env setup.
• •prompt — single-turn LLM evaluation, zero script overhead. Use for lightweight validation.
• •agent — multi-turn subagent with tools (Read, Grep, Glob). Use for complex verification.

Async execution: Add "async": true on command hooks for background operations (logging, analytics) that shouldn't block the main flow.

MCP tool matching: Use mcp__<server>__<tool> pattern in matchers for PreToolUse/PostToolUse.

Configuring Plugin

When user says "configure plugin", "setup plugin.json":

1. •Read references/08-configuration/plugin-json.md for full schema
2. •Required fields: name
3. •Recommended fields: version, description, author, license
4. •Component paths: commands, agents, hooks, mcpServers

Settings and Output

When user says "configure settings", "setup output", "output directory":

1. •Read references/08-configuration/settings.md for settings hierarchy
2. •Read references/08-configuration/output-config.md for output patterns
3. •Key environment variables:
   • •${CLAUDE_PLUGIN_ROOT} - plugin installation directory
   • •${CLAUDE_PROJECT_DIR} - project root
   • •${CLAUDE_ENV_FILE} - persistent env vars (SessionStart only)
4. •Use SessionStart hook to create output directories

Testing Plugin

When user says "test plugin", "validate plugin":

1. •Read references/09-testing/testing.md
2. •Run claude --debug to see plugin loading
3. •Validate plugin.json syntax
4. •Test each component:
   • •Skills: Ask questions matching description
   • •Commands: Run /command-name
   • •Agents: Check /agents listing
   • •Hooks: Trigger events manually

Packaging for Marketplace

When user says "package plugin", "publish plugin", "marketplace":

1. •Read references/10-distribution/packaging.md
2. •Create marketplace.json in repository root
3. •Update README with installation instructions
4. •Version using semantic versioning (MAJOR.MINOR.PATCH)

Decision Framework

Before creating a component, verify it's the right choice:

The 5-10 Rule: Done 5+ times? Will do 10+ more? Create a skill or command.

References

Overview

• •references/01-overview/what-are-plugins.md - Plugin overview
• •references/01-overview/what-are-skills.md - Skills overview
• •references/01-overview/what-are-commands.md - Commands overview
• •references/01-overview/what-are-agents.md - Agents overview
• •references/01-overview/what-are-hooks.md - Hooks overview
• •references/01-overview/what-are-mcp.md - MCP overview
• •references/01-overview/component-comparison.md - When to use what

Philosophy

• •references/02-philosophy/core-philosophy.md - Design principles
• •references/02-philosophy/decision-frameworks.md - Decision trees
• •references/02-philosophy/anti-patterns.md - What to avoid

Components

• •references/03-skills/anthropic-skill-standards.md - Official Anthropic skill standards and checklist
• •references/03-skills/skill-patterns.md - Five skill patterns (Sequential, Multi-MCP, Iterative, Context-Aware, Domain-Specific)
• •references/03-skills/ - Skill creation guides
• •references/04-commands/ - Command creation guides
• •references/05-agents/ - Agent creation guides
• •references/06-hooks/ - Hook creation guides
• •references/06-hooks/cross-platform-hooks.md - Windows/macOS/Linux support
• •references/07-mcp/ - MCP overview

Configuration

• •references/08-configuration/plugin-json.md - Plugin manifest
• •references/08-configuration/marketplace-json.md - Marketplace config
• •references/08-configuration/settings.md - Settings hierarchy
• •references/08-configuration/output-config.md - Output configuration

Testing & Distribution

• •references/09-testing/testing.md - Testing guide (all components)
• •references/09-testing/debugging.md - Debugging guide
• •references/09-testing/cli-reference.md - CLI commands reference
• •references/10-distribution/packaging.md - Packaging guide
• •references/10-distribution/marketplace.md - Marketplace guide
• •references/10-distribution/versioning.md - Version strategy
• •references/10-distribution/complete-examples.md - Full plugin examples

Examples

Working example plugins in examples/:

• •examples/simple-greeter-plugin/ - Minimal plugin with one skill
• •examples/full-featured-plugin/ - Complete plugin with skill, commands, hooks

Templates

All templates are in the templates/ directory:

• •templates/skill/SKILL.md.template
• •templates/command/command.md.template
• •templates/agent/agent.md.template
• •templates/hooks/hooks.json.template
• •templates/hooks/run-hook.cmd.template - Cross-platform hook wrapper
• •templates/plugin.json.template
• •templates/marketplace.json.template
• •templates/settings.json.template
• •templates/mcp.json.template

Scripts

• •scripts/init_plugin.py - Initialize new plugin with selected components
• •scripts/init_skill.py - Initialize standalone skill
• •scripts/validate_skill.py - Validate skill structure
• •scripts/package_skill.py - Package skill for distribution