Plugin Initializer

Initialize complete Claude Code plugin directory structures with all necessary components and proper configuration.

When to Use This Skill

This skill should be used when:

• Creating a new Claude Code plugin from scratch
• User requests "create a plugin", "initialize a plugin", or "start a new plugin"
• Setting up plugin scaffolding for a new project
• Need to generate a complete plugin directory structure

What This Skill Does

Creates a complete plugin directory structure including:

• .claude-plugin/plugin.json manifest with proper schema
• Directory structure for all plugin components
• Template README.md file
• Placeholder directories for skills, agents, commands, hooks
• Optional example files to demonstrate structure

Instructions

Step 1: Gather Plugin Metadata

Collect the following information from the user (or use sensible defaults):

• Plugin name (required): Kebab-case identifier (e.g., my-plugin-name)
• Description (required): Brief explanation of plugin purpose
• Author information: Name, email, URL
• Version: Default to 1.0.0
• License: Default to MIT
• Keywords: For plugin discovery

Step 2: Run the Initialization Script

Execute the init_plugin.py script with the gathered information:

python scripts/init_plugin.py <plugin-name> --path <output-directory> \
  --description "Plugin description" \
  --author "Author Name" \
  --email "author@example.com" \
  --version "1.0.0" \
  --license "MIT"

The script will create:

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── .gitkeep
├── agents/
│   └── .gitkeep
├── skills/
│   └── .gitkeep
├── hooks/
│   └── hooks.json
├── .mcp.json
└── README.md

Step 3: Verify Structure

After initialization:

1. Confirm all directories were created
2. Validate plugin.json has all required fields
3. Check that README.md was generated
4. Inform the user of the plugin location and next steps

Step 4: Provide Next Steps Guidance

Suggest to the user:

• Add skills to skills/ directory using the skill-creator skill
• Add agents to agents/ directory using the agent-creator skill
• Add commands to commands/ directory using the command-creator skill
• Configure hooks in hooks/hooks.json using the hook-creator skill
• Add MCP servers to .mcp.json using the mcp-integrator skill

Using the Script

The scripts/init_plugin.py script is the core tool for plugin initialization.

Basic usage:

python scripts/init_plugin.py my-plugin-name --path /path/to/output

Full usage with all options:

python scripts/init_plugin.py my-plugin-name \
  --path /path/to/output \
  --description "My plugin description" \
  --author "Author Name" \
  --email "author@example.com" \
  --url "https://github.com/author" \
  --version "1.0.0" \
  --license "MIT" \
  --keywords "keyword1,keyword2,keyword3" \
  --with-examples

Options:

• --path: Output directory (default: current directory)
• --description: Plugin description
• --author: Author name
• --email: Author email
• --url: Author URL or homepage
• --version: Plugin version (default: 1.0.0)
• --license: License identifier (default: MIT)
• --keywords: Comma-separated keywords
• --with-examples: Include example skill/agent/command files

Plugin Manifest Schema

The generated plugin.json includes:

Required Fields

• name: Unique kebab-case identifier

Recommended Fields

• version: Semantic version (e.g., "1.0.0")
• description: Brief explanation of purpose
• author: Object with name, email, url
• keywords: Array of discovery tags
• license: License identifier

Optional Fields

• homepage: Documentation URL
• repository: Source code URL
• commands: Custom command paths
• agents: Custom agent paths
• hooks: Custom hooks path
• mcpServers: Custom MCP config path

Validation

After initialization, validate the plugin structure:

1. Ensure .claude-plugin/plugin.json exists and is valid JSON
2. Verify required fields are present
3. Check directory structure matches expectations
4. Confirm all paths are relative and start with ./ where required

Examples

Minimal plugin initialization:

python scripts/init_plugin.py my-first-plugin --path ~/plugins \
  --description "My first Claude Code plugin"

Full-featured plugin initialization:

python scripts/init_plugin.py advanced-tools \
  --path ~/plugins \
  --description "Advanced development tools for Claude Code" \
  --author "Development Team" \
  --email "dev@example.com" \
  --url "https://github.com/org/advanced-tools" \
  --keywords "tools,development,automation" \
  --with-examples

Troubleshooting

Directory already exists:

• Script will prompt to overwrite or choose different location
• Use --force flag to overwrite without prompting

Invalid plugin name:

• Must use lowercase letters, numbers, and hyphens only
• Cannot contain spaces or special characters
• Script will validate and reject invalid names

Permission errors:

• Ensure write permissions in output directory
• Check that parent directories exist

Best Practices

1. Use descriptive names: Choose plugin names that clearly indicate purpose
2. Complete metadata: Fill in all author fields for proper attribution
3. Semantic versioning: Start with 1.0.0 and follow semver
4. Keywords for discovery: Add relevant keywords for marketplace search
5. Initialize in clean directory: Avoid conflicts with existing files
6. Commit to git: Track plugin changes from initialization

Reference

For complete plugin structure documentation, see references/plugin-schema.md.