Claude Code Plugin Builder

Expert skill for developing professional Claude Code plugins.

Critical Directory Rules

Components MUST be at plugin root, NOT inside .claude-plugin/:

✅ CORRECT:
plugin/
├── .claude-plugin/plugin.json  # Only manifest here
├── commands/                    # At root
├── agents/                      # At root
├── skills/                      # At root
└── hooks/                       # At root

❌ WRONG:
plugin/.claude-plugin/
├── plugin.json
├── commands/      # Won't load
└── agents/        # Won't load

Plugin Creation Workflow

1. Initialize Structure

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/{commands,agents,skills,hooks}

2. Create Manifest

Minimal (my-plugin/.claude-plugin/plugin.json):

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does"
}

Complete:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief description",
  "author": {
    "name": "Your Name",
    "email": "email@example.com",
    "url": "https://github.com/user"
  },
  "repository": "https://github.com/org/repo",
  "license": "MIT",
  "keywords": ["tag1", "tag2"],
  "hooks": "./hooks/hooks.json",
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@org/package"],
      "env": {
        "API_KEY": "${API_KEY:-}"
      }
    }
  }
}

3. Add Components

Commands (user-invoked):

<!-- commands/deploy.md -->
---
description: Deploy to production
validation:
  requiresFiles: ["package.json"]
---

# Deploy Command

1. Verify deployment readiness
2. Execute: npm run deploy
3. Monitor deployment status
4. Report results

Agents (autonomous specialists):

<!-- agents/security-expert.md -->
---
description: Security vulnerability analysis expert
capabilities: ["vulnerability-scan", "audit", "remediation"]
---

# Security Expert

Specializes in OWASP vulnerabilities, CVE analysis, dependency scanning.

Invoke for: security audits, vulnerability assessments, compliance reviews.

Skills (model-invoked expertise):

<!-- skills/incident-response/SKILL.md -->
---
name: Incident Response
description: Production incident handling including rollback, root cause analysis, postmortem. Use when production outages, security breaches, critical bugs, or user mentions "incident", "production down", "rollback".
---

# Incident Response

## Protocol
1. Assess severity (P0-P4)
2. Contain: rollback/disable/rate-limit
3. Investigate: logs, metrics, recent changes
4. Resolve: fix, test, deploy, verify
5. Document: postmortem, lessons learned

See [incident-procedures.md](./incident-procedures.md) for detailed runbooks.

Hooks (event automation):

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/format.sh",
        "timeout": 30
      }]
    }]
  }
}

MCP Servers (external integration):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/db"],
      "env": {
        "PGPASSWORD": "${POSTGRES_PASSWORD}"
      }
    }
  }
}

Component Selection Guide

| Need | Component | Example | |------|-----------|---------| | User triggers action | Command | /deploy production | | Autonomous specialist | Agent | Security analysis | | Auto-invoked expertise | Skill | Incident response | | Event automation | Hook | Format after write | | External system | MCP Server | Database queries |

Testing Workflow

Local Development

Checklist:

[ ] Create dev marketplace
[ ] Add plugin to marketplace
[ ] Install for testing
[ ] Test each component
[ ] Iterate and reload

Setup:

# 1. Create marketplace
cat > .claude-plugin/marketplace.json <<EOF
{
  "name": "dev",
  "owner": {"name": "Dev"},
  "plugins": [{
    "name": "my-plugin",
    "source": {"source": "path", "path": "."}
  }]
}
EOF

# 2. Install
claude
/plugin marketplace add /path/to/dev-marketplace
/plugin install my-plugin@dev

# 3. Test
/my-plugin:command-name

# 4. Reload after changes
/plugin uninstall my-plugin@dev
/plugin install my-plugin@dev

Debug Mode

claude --debug  # Shows plugin loading, errors, registration

Common Issues

| Issue | Solution | |-------|----------| | Plugin not loading | Validate JSON: jq . .claude-plugin/plugin.json | | Commands missing | Ensure commands/ at root, not in .claude-plugin/ | | Hooks not firing | chmod +x hooks/script.sh, use ${CLAUDE_PLUGIN_ROOT} | | MCP server fails | Use ${VAR:-} for optional env vars, test command independently | | Skill not activating | Add specific triggers: file types, error patterns, keywords |

Marketplace Creation

{
  "name": "company-plugins",
  "owner": {
    "name": "Company",
    "email": "dev@company.com"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "What it does",
      "source": {
        "source": "github",
        "repo": "org/repo"
      }
    }
  ]
}

Distribution:

GitHub: /plugin marketplace add owner/repo
Git URL: /plugin marketplace add https://git.server.com/plugins.git
Local: /plugin marketplace add ./marketplace

Gemini CLI Migration

Checklist:

[ ] Create .claude-plugin/ directory
[ ] Convert gemini-extension.json → plugin.json
[ ] Migrate GEMINI.md to SessionStart hook
[ ] Update README with Claude Code install
[ ] Test with claude --debug

Quick migrate:

#!/usr/bin/env bash
set -euo pipefail

mkdir -p .claude-plugin hooks

# Extract from gemini-extension.json
NAME=$(jq -r '.name' gemini-extension.json)
VERSION=$(jq -r '.version' gemini-extension.json)
DESC=$(jq -r '.description' gemini-extension.json)

# Create plugin.json
cat > .claude-plugin/plugin.json <<EOF
{
  "name": "$NAME",
  "version": "$VERSION",
  "description": "$DESC",
  "hooks": "./hooks/hooks.json"
}
EOF

# Create SessionStart hook
cat > hooks/hooks.json <<'EOF'
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/context.sh",
        "timeout": 10
      }]
    }]
  }
}
EOF

cat > hooks/context.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
CONTEXT="${CLAUDE_PLUGIN_ROOT}/hooks/CONTEXT.md"
if [ -f "$CONTEXT" ]; then
  jq -n --arg ctx "$(cat "$CONTEXT")" '{
    "hookSpecificOutput": {
      "hookEventName": "SessionStart",
      "additionalContext": $ctx
    }
  }'
fi
EOF

chmod +x hooks/context.sh
[ -f GEMINI.md ] && cp GEMINI.md hooks/CONTEXT.md

Best Practices

Manifest:

Use semantic versioning
Include keywords for discovery
Document env vars in README

Commands:

Clear descriptions for /help
Single responsibility per command
Add validation rules

Agents:

Define clear expertise boundaries
Specify invocation criteria
Document tool usage

Skills:

Descriptions with concrete triggers (file types, error patterns, keywords)
Keep SKILL.md under 500 lines
Use reference files for details: [details](./reference.md)
Focus on workflows, not explanations

Hooks:

Scripts executable: chmod +x
Use ${CLAUDE_PLUGIN_ROOT} for paths
Include timeouts
Return proper JSON

MCP Servers:

Prefer npx for npm packages: npx -y @org/package
Use ${VAR:-} for optional env vars
Use fully qualified tool names: ServerName:tool_name
Test command independently

Progressive Disclosure

For complex plugins:

Keep SKILL.md concise with workflows
Link to reference files one level deep
Organize by task, not by concept

Example structure:

skills/plugin-expert/
├── SKILL.md              # Core workflows
├── components.md         # Component details
├── testing.md            # Testing procedures
├── troubleshooting.md    # Common issues
└── examples/             # Example plugins

Quick Reference

Commands:

/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace
/plugin uninstall plugin-name@marketplace
/plugin list
claude --debug

Paths:

${CLAUDE_PLUGIN_ROOT} - Plugin directory
${VAR:-} - Optional env var
${VAR} - Required env var

Events:

SessionStart, SessionEnd
PreToolUse, PostToolUse
UserPromptSubmit
Notification, Stop, SubagentStop
PreCompact

Resources

For detailed information:

Component examples: examples.md
Ready-to-use templates: templates.md
Complete guides: README.md

Official docs: