claude-plugin-development（Claude plugin 开发）

Claude Plugin Development

Complete lifecycle for developing, validating, and distributing Claude Code plugins.

Quick Start

# 1. Scaffold plugin
./scripts/scaffold-plugin.sh my-plugin --with-commands

# 2. Add components (commands, agents, hooks, skills)
# 3. Test locally
/plugin marketplace add ./my-plugin
/plugin install my-plugin@my-plugin

# 4. Distribute
git push origin main --tags

Lifecycle Overview

Discovery -> Init -> Components -> Validate -> Distribute -> Marketplace
    |         |          |            |            |             |
    v         v          v            v            v             v
 Purpose   Scaffold   Commands    Structure    Package      Catalog
  Scope    plugin.json  Agents     Testing     Version      Publish
  Type      README      Hooks      Quality     Release       Share

Phase 1: Discovery

Before creating a plugin, clarify:

Phase 2: Initialization

Minimal Plugin Structure

my-plugin/
├── plugin.json          # Required: metadata
├── README.md            # Required for distribution
└── commands/            # Optional components

plugin.json (Required)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what this plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "license": "MIT"
}

Using the Scaffold Script

./scripts/scaffold-plugin.sh my-plugin \
  --author "Your Name" \
  --with-commands \
  --with-agent \
  --with-hooks

See references/structure.md for complete plugin structure and plugin.json schema.

Phase 3: Components

Add components based on plugin needs. For detailed component authoring, load the appropriate skill:

Slash Commands

Create custom commands in commands/ directory.

Example: commands/review.md

---
description: "Review code for quality issues"
---

Review the following code: {{0}}

Check for:
- Code style and formatting
- Potential bugs
- Performance issues
- Security concerns

For complex commands, load the claude-command-authoring skill.

Custom Agents

Define specialized agents in agents/ directory.

Example: agents/security-reviewer.md

---
name: security-reviewer
description: "Security-focused code reviewer"
---

You are a security expert. When reviewing code:
1. Check for vulnerabilities
2. Verify input validation
3. Review authentication flows
4. Report issues with severity levels

For agent design patterns, load the claude-agent-development skill.

Event Hooks

React to Claude Code events via plugin.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"
          }
        ]
      }
    ]
  }
}

Hook types: PreToolUse, PostToolUse, PrePromptSubmit, PostPromptSubmit

For hook implementation, load the claude-hook-authoring skill.

Skills

Add reusable methodology patterns in skills/ directory.

For skill authoring, load the skills-development skill.

MCP Servers

Integrate MCP servers for external capabilities:

{
  "mcpServers": {
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Path variables:

• ${CLAUDE_PLUGIN_ROOT} - Plugin installation directory
• ${MY_API_KEY} - Environment variable expansion

Phase 4: Validation

Before distribution, validate the plugin:

Validation Checklist

Structure:

• plugin.json exists and is valid JSON
• Required fields present (name, version, description)
• Plugin name matches directory name (kebab-case)

Commands:

• YAML frontmatter with description
• Parameter syntax correct ({{0}}, {{1}})

Agents:

• YAML frontmatter with name and description
• Tool restrictions appropriate

Hooks:

• Scripts executable (chmod +x)
• JSON input/output format correct
• Matchers are valid regex

Documentation:

• README.md with installation instructions
• CHANGELOG.md for version history
• LICENSE file included

Validation Commands

# Validate JSON
jq empty plugin.json

# Check command frontmatter
for f in commands/**/*.md; do
  head -n 5 "$f" | grep -q '^---$' || echo "Missing: $f"
done

# Verify scripts executable
for f in hooks/**/*.sh; do
  test -x "$f" || echo "Not executable: $f"
done

Local Testing

# Add as local marketplace
/plugin marketplace add ./my-plugin

# Install and test
/plugin install my-plugin@my-plugin

# Test commands
/my-command arg1 arg2

Phase 5: Distribution

Semantic Versioning

Follow semver (MAJOR.MINOR.PATCH):

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Release Workflow

# 1. Update version in plugin.json
# 2. Update CHANGELOG.md
# 3. Commit
git add plugin.json CHANGELOG.md
git commit -m "chore: release v1.0.0"

# 4. Tag
git tag v1.0.0

# 5. Push
git push origin main --tags

# 6. Create GitHub release
gh release create v1.0.0 \
  --title "v1.0.0" \
  --notes "Initial release"

Distribution Methods

See references/distribution.md for packaging, CI/CD, and release automation.

Phase 6: Marketplace

What is a Marketplace?

A catalog of plugins defined in .claude-plugin/marketplace.json that enables discovery, installation, and version management.

Creating a Marketplace

mkdir -p .claude-plugin

.claude-plugin/marketplace.json:

{
  "name": "my-marketplace",
  "owner": {
    "name": "Team Name",
    "email": "team@example.com"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "Plugin description",
      "version": "1.0.0"
    }
  ]
}

Plugin Sources

Relative path:

{"source": "./plugins/my-plugin"}

GitHub:

{
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v1.0.0"
  }
}

Git URL:

{
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Team Configuration

Configure automatic marketplace installation in .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  }
}

Marketplace Commands

# Add marketplace
/plugin marketplace add owner/repo
/plugin marketplace add ./local-path

# List available
/plugin marketplace list

# Install from marketplace
/plugin install plugin-name@marketplace-name

# Update
/plugin marketplace update marketplace-name

See references/marketplace.md for full schema, team setup, and hosting strategies.

Best Practices

Naming Conventions

• Plugin name: kebab-case (e.g., dev-tools)
• Commands: kebab-case (e.g., review-pr)
• Agents: kebab-case (e.g., security-reviewer)
• Scripts: kebab-case with extension (e.g., validate.sh)

Security

• Never hardcode secrets in plugin files
• Use environment variables for sensitive data
• Validate all user inputs in hooks
• Review third-party dependencies
• Document security requirements

Documentation

• README.md: Overview, installation, usage examples
• CHANGELOG.md: Version history with semver
• LICENSE: Appropriate license file
• Commands/Agents: Clear description in frontmatter

Testing

• Test all commands with various inputs
• Verify hooks don't block normal workflow
• Check MCP servers connect properly
• Test installation and removal
• Validate cross-platform compatibility

Troubleshooting

Plugin not loading:

• Verify plugin.json syntax: jq empty plugin.json
• Check plugin name matches directory
• Ensure required fields present

Commands not appearing:

• Verify YAML frontmatter exists
• Check files in commands/ directory
• Ensure markdown syntax correct

Hooks not executing:

• Check scripts executable: chmod +x
• Verify matcher regex correct
• Test hook script independently
• Review JSON output format

MCP servers failing:

• Verify server binary exists
• Check environment variables set
• Test with MCP Inspector
• Review logs: ~/Library/Logs/Claude/

References

• references/structure.md - Directory layout, plugin.json schema
• references/distribution.md - Packaging, versioning, release automation
• references/marketplace.md - Marketplace schema, hosting, team setup

Related Skills

• claude-command-authoring - Slash command development
• claude-agent-development - Custom agent design
• claude-hook-authoring - Event hook implementation
• skills-development - Skill creation patterns