Plugin Development Toolkit

A comprehensive toolkit for developing Claude Code plugins with expert guidance on hooks, MCP integration, plugin structure, and marketplace publishing.

Table of Contents

• Overview
• Prerequisites
• Installation
• Quick Start
• Skills
• Guided Workflows
• Validation Agents
• Utility Scripts
• Development Workflow
• Use Cases
• Best Practices
• FAQ
• Contributing
• Getting Help
• Attribution
• Changelog
• License

Overview

The plugin-dev toolkit provides 8 specialized skills, 3 validation agents, and 3 slash commands to help you build high-quality Claude Code plugins:

• Skills provide domain expertise loaded on-demand via trigger phrases
• Agents automate validation and generation tasks
• Workflows guide you through complete plugin or marketplace creation

Each component follows progressive disclosure: lean core documentation with detailed references and working examples available when needed.

Prerequisites

Required

• Claude Code CLI installed and configured
• Git (for version control and marketplace publishing)

For Utility Scripts

The plugin includes utility scripts for validation and testing. These require:

Tool	Version	Purpose
bash	3.2+	Shell scripting (macOS default works)
jq	1.6+	JSON parsing and validation
grep	-	Pattern matching (with -E support)
sed	-	Stream editing (GNU or BSD)

Check your environment:

bash --version | head -1
jq --version
grep --version 2>&1 | head -1

Note: jq may need to be installed. macOS: brew install jq, Linux: apt install jq

Installation

Add this marketplace and install the plugin:

/plugin marketplace add sjnims/plugin-dev
/plugin install plugin-dev@sjnims/plugin-dev

Or for development, use directly:

claude --plugin-dir /path/to/plugin-dev/plugins/plugin-dev

Quick Start

New to plugin development? Start with the guided entry point:

/plugin-dev:start

This will help you choose between creating a plugin (most users) or a marketplace (for distributing multiple plugins).

Learning by Asking

You can also learn progressively by asking questions. Skills load automatically:

1. Plan your plugin structure:

   • Ask: "What's the best directory structure for a plugin with commands and MCP integration?"
   • The plugin-structure skill will guide you

2. Add MCP integration (if needed):

   • Ask: "How do I add an MCP server for database access?"
   • The mcp-integration skill provides examples and patterns

3. Implement hooks (if needed):

   • Ask: "Create a PreToolUse hook that validates file writes"
   • The hook-development skill gives working examples and utilities

Skills

Skills load automatically when you ask relevant questions. Each skill includes core documentation, reference guides, working examples, and utility scripts.

Skill	Trigger Phrases	Use For
Hook Development	create a hook, PreToolUse hook, validate tool use, prompt-based hooks, block dangerous commands	Event-driven automation, operation validation, policy enforcement
MCP Integration	add MCP server, integrate MCP, .mcp.json, Model Context Protocol, stdio/SSE server	External service integration, API connections, database access
Plugin Structure	plugin structure, plugin.json, auto-discovery, component organization	Starting new plugins, organizing components, manifest configuration
Plugin Settings	plugin settings, .local.md files, YAML frontmatter, per-project settings	Configuration storage, user preferences, per-project state
Command Development	create a slash command, command frontmatter, command arguments	Slash commands, argument handling, command organization
Agent Development	create an agent, write a subagent, agent frontmatter, autonomous agent	Autonomous agents, AI-assisted generation, agent behavior
Skill Development	create a skill, add a skill, skill description, progressive disclosure	Creating new skills, improving skill quality
Marketplace Structure	create a marketplace, marketplace.json, distribute plugins, host plugins	Marketplace creation, plugin distribution, team sharing

Skill Resources

Each skill provides:

• Core SKILL.md (~1,000-2,200 words) - Essential API reference
• references/ - Detailed guides and patterns
• examples/ - Complete working code for copy-paste
• scripts/ - Validation and testing utilities

For detailed documentation on any skill, ask Claude Code or browse the skills/ directory.

Guided Workflows

/plugin-dev:start

A guided entry point to help you choose between creating a plugin (most users) or a marketplace (for distributing multiple plugins).

/plugin-dev:create-plugin

A comprehensive, end-to-end workflow for creating plugins from scratch.

8-Phase Process:

1. Discovery - Understand plugin purpose and requirements
2. Component Planning - Determine needed skills, commands, agents, hooks, MCP
3. Detailed Design - Specify each component and resolve ambiguities
4. Structure Creation - Set up directories and manifest
5. Component Implementation - Create each component using AI-assisted agents
6. Validation - Run plugin-validator and component-specific checks
7. Testing - Verify plugin works in Claude Code
8. Documentation - Finalize README and prepare for distribution

Usage:

/plugin-dev:create-plugin [optional description]

# Examples:
/plugin-dev:create-plugin
/plugin-dev:create-plugin A plugin for managing database migrations

/plugin-dev:create-marketplace

A guided workflow for creating plugin marketplaces to distribute plugins.

8-Phase Process:

1. Discovery - Understand marketplace purpose and audience
2. Plugin Planning - Determine plugins to include
3. Metadata Design - Configure marketplace metadata and branding
4. Structure Creation - Create directory and manifest
5. Plugin Entry Configuration - Configure each plugin entry (paths, repos, versions)
6. Distribution Setup - Configure team settings or community guidelines
7. Validation - Run marketplace validators
8. Testing & Finalization - Test installation and finalize

Usage:

/plugin-dev:create-marketplace [optional description]

# Examples:
/plugin-dev:create-marketplace
/plugin-dev:create-marketplace A marketplace for our team's internal tools

Validation Agents

Use these agents proactively after creating components:

Agent	Purpose	Trigger
plugin-validator	Validates entire plugin structure, manifest, and marketplace.json	"validate my plugin", "check plugin structure"
skill-reviewer	Reviews skill quality, triggering reliability, and best practices	"review my skill", "check skill quality"
agent-creator	Generates new agents from natural language descriptions	"create an agent", "generate an agent that..."

Example usage:

> validate my plugin at plugins/my-plugin
> review the skill I just created
> create an agent that reviews code for security issues

Utility Scripts

All scripts are located in plugins/plugin-dev/skills/*/scripts/ and can be run directly:

Agent Development

# Create a new agent skeleton
./skills/agent-development/scripts/create-agent-skeleton.sh my-agent agents/

# Validate agent frontmatter and structure
./skills/agent-development/scripts/validate-agent.sh agents/my-agent.md

# Test agent trigger phrases
./skills/agent-development/scripts/test-agent-trigger.sh agents/my-agent.md

Command Development

# Validate command structure
./skills/command-development/scripts/validate-command.sh commands/my-command.md

# Check frontmatter fields
./skills/command-development/scripts/check-frontmatter.sh commands/my-command.md

Hook Development

# Validate hooks.json schema
./skills/hook-development/scripts/validate-hook-schema.sh hooks/hooks.json

# Test a hook with sample input
./skills/hook-development/scripts/test-hook.sh hooks/my-hook.sh input.json

# Lint hook scripts
./skills/hook-development/scripts/hook-linter.sh hooks/my-hook.sh

Plugin Settings

# Validate settings file structure
./skills/plugin-settings/scripts/validate-settings.sh .claude/plugin.local.md

# Parse frontmatter from settings
./skills/plugin-settings/scripts/parse-frontmatter.sh .claude/plugin.local.md

Development Workflow

graph TD
    A[Design Structure] --> B[Add Components]
    B --> C[Integrate Services]
    C --> D[Add Automation]
    D --> E[Test & Validate]

    A -.- A1[plugin-structure skill]
    B -.- B1[command/agent/skill skills]
    C -.- C1[mcp-integration skill]
    D -.- D1[hook-development skill]
    E -.- E1[validation agents + scripts]

Loading

Workflow diagram (text version)

Design Structure → Add Components → Integrate Services → Add Automation → Test & Validate
       ↓                 ↓                  ↓                  ↓                ↓
plugin-structure   command/agent/     mcp-integration    hook-development   validation
    skill          skill skills           skill              skill         agents + scripts

Phase	Skill/Tool	What You Do
Design	plugin-structure	Define manifest, directory layout
Components	command/agent/skill development	Create commands, agents, skills
Services	mcp-integration	Configure MCP servers
Automation	hook-development	Add hooks for validation/automation
Validate	Agents + scripts	Run validators, test components

Use Cases

Building a Database Plugin

Step	Ask Claude Code	Skill Used
1	"What's the structure for a plugin with MCP integration?"	plugin-structure
2	"Configure an stdio MCP server for PostgreSQL"	mcp-integration
3	"Add a Stop hook to ensure connections close properly"	hook-development

Creating a Validation Plugin

Step	Ask Claude Code	Skill Used
1	"Create hooks that validate all file writes for security"	hook-development
2	"Test my hooks before deploying"	Use validate-hook-schema.sh
3	"Organize my hooks and configuration files"	plugin-structure

Integrating External Services

Step	Ask Claude Code	Skill Used
1	"Add Asana MCP server with OAuth"	mcp-integration
2	"Use Asana tools in my commands"	mcp-integration
3	"Structure my plugin with commands and MCP"	plugin-structure

Best Practices

Security First

• Input validation in all hooks
• HTTPS/WSS for MCP servers
• Environment variables for credentials
• Principle of least privilege
• Use [BANG] placeholder in skill documentation for shell patterns (see SECURITY.md)

Portability

• Use ${CLAUDE_PLUGIN_ROOT} for all paths
• Relative paths only within plugin
• Environment variable substitution for secrets

Testing

• Validate configurations before deployment
• Test hooks with sample inputs
• Use debug mode (claude --debug)
• Create separate test repositories to avoid polluting development

Documentation

• Clear README files for each plugin
• Document all environment variables
• Include usage examples

What to Avoid

Anti-Pattern	Why It's Bad	Better Approach
Hardcoded absolute paths	Breaks portability	Use ${CLAUDE_PLUGIN_ROOT}
Overly broad hook matchers (*)	Unexpected triggers, performance impact	Use specific patterns like Write|Edit
Large SKILL.md files (>2,000 words)	Slow loading, context bloat	Use references/ for detailed docs
Storing secrets in manifests	Security risk	Use environment variables
Testing in your main dev repo	File pollution, git noise	Use dedicated test repositories

FAQ

Q: How do I test my plugin without affecting my development environment?

Create a separate test repository and load the plugin from there. See CONTRIBUTING.md for detailed instructions.

Q: My skill isn't loading when I ask trigger questions. What's wrong?

Check that your skill description includes the specific phrases users might say. The description should start with "This skill should be used when..." and include example queries like "create a hook", "add MCP server".

Q: What's the [BANG] placeholder I see in documentation?

Due to a Claude Code issue, inline bash patterns (! followed by backtick) can execute during skill loading. The [BANG] placeholder prevents this. See SECURITY.md for details.

Q: How do I structure a plugin with both commands and MCP integration?

Start with /plugin-dev:create-plugin for a guided walkthrough, or ask: "What's the best directory structure for a plugin with commands and MCP integration?" The plugin-structure skill will guide you.

Q: Can I restrict which tools my skill or agent can use?

Yes, use the allowed-tools frontmatter field. For example: allowed-tools: Read, Grep, Glob creates a read-only skill.

Contributing

To contribute improvements:

1. Fork this repository
2. Make changes to plugins/plugin-dev/
3. Test locally with claude --plugin-dir plugins/plugin-dev
4. Run linters: markdownlint '**/*.md' and shellcheck plugins/plugin-dev/skills/*/scripts/*.sh
5. Create a PR with your changes

Getting Help

• Issues: GitHub Issues
• Documentation: Claude Code Plugins
• Skills Reference: Claude Code Skills

Attribution

This plugin was originally developed by Daisy Hollman at Anthropic. The original plugin can be found at:

• claude-code/plugins/plugin-dev
• claude-plugins-official/plugins/plugin-dev

This repository (sjnims/plugin-dev) is an expanded version with:

• Enhanced skill descriptions with stronger trigger phrases
• Additional utility scripts (test-agent-trigger.sh, create-agent-skeleton.sh)
• Expanded MCP integration documentation
• Comprehensive command development references
• CI/CD workflows for validation and quality assurance
• Improved cross-references between skills

Changelog

See CHANGELOG.md for release history and version details.

License

MIT License - See LICENSE for details