plugin-development

plugin-development

A comprehensive Claude Code plugin that assists developers in creating, validating, and distributing Claude Code plugins—from scaffold to release.

Overview

The plugin-development plugin provides a complete toolkit for plugin authorship using a hybrid architecture:

• Skill (plugin-authoring): Ambient, auto-discovered guidance with progressive disclosure
• 8 Slash Commands: Explicit actions for scaffolding, validation, testing, and submission
• Reviewer Agent: Deep, multi-file audits and readiness checks
• Hooks: Automated validation and formatting guardrails

Installation

This plugin is part of the cc-plugins community marketplace.

From GitHub

# Add the marketplace
/plugin marketplace add kossakovsky/cc-plugins

# Install the plugin
/plugin install plugin-development@cc-plugins

Local Development

# Clone the repository
git clone https://github.com/kossakovsky/cc-plugins.git
cd cc-plugins

# Add local marketplace
/plugin marketplace add .

# Install the plugin
/plugin install plugin-development@cc-plugins

Then use it to scaffold new plugins:

/plugin-development:init my-new-plugin

Quick Start

Before you begin: Make sure you've installed this plugin following the Installation instructions above.

Create a New Plugin

Once installed, you can scaffold a new plugin:

/plugin-development:init my-awesome-plugin

This scaffolds:

• .claude-plugin/plugin.json - Plugin manifest
• commands/ - Slash commands directory
• README.md - Documentation template

Additional directories (skills/, agents/, hooks/, scripts/) are created on demand when you add components via /plugin-development:add-skill, /plugin-development:add-agent, or /plugin-development:add-hook.

Add Components

# Add a command
/plugin-development:add-command format-code "Format code according to project standards"

# Add a skill
/plugin-development:add-skill code-review "Use when reviewing code or PRs"

# Add an agent
/plugin-development:add-agent security-auditor "Analyzes code for security vulnerabilities"

# Add a hook
/plugin-development:add-hook PreToolUse "Write|Edit"

Validate Your Plugin

/plugin-development:validate

Checks:

• Plugin structure and organization
• Manifest validity (plugin.json)
• Component configuration
• Naming conventions
• Hook safety

Test Locally

After creating your plugin and making it available in a marketplace:

# From your plugin directory
/plugin-development:test-local

This creates a dev marketplace and provides installation instructions for iterative testing. See the Testing Your Plugin section below for complete workflow details.

Commands Reference

Command	Description
/plugin-development:init [name]	Scaffold a new plugin with standard structure
/plugin-development:add-command [name] [desc]	Add a new slash command
/plugin-development:add-skill [name] [desc]	Add a new Skill with SKILL.md
/plugin-development:add-agent [name] [desc]	Add a new sub-agent
/plugin-development:add-hook [event] [matcher]	Add a hook configuration
/plugin-development:validate	Validate plugin structure and configuration
/plugin-development:test-local	Create dev marketplace for local testing
/plugin-development:submit [plugin-path]	Submit a plugin to the community marketplace via PR

Skill: plugin-authoring

The plugin-authoring Skill provides ambient guidance throughout your development session.

Triggers: Automatically activates when working with:

• .claude-plugin/plugin.json
• marketplace.json
• commands/, agents/, skills/, or hooks/ directories

Capabilities:

• Read-only analysis and guidance
• Progressive disclosure (links to detailed docs)
• Proposes safe actions via commands
• Escalates to plugin-reviewer agent for deep audits

Access: Automatic (no explicit invocation needed)

Agent: plugin-reviewer

Deep, comprehensive audits of plugins for release readiness.

Invoke: /agents plugin-reviewer

Provides:

• Structure audit
• Manifest validation
• Component analysis
• Hook safety checks
• Marketplace readiness assessment
• Prioritized issue list (Critical → Low)
• Specific fix recommendations

Runtime: 5-15 minutes (separate context window)

Hooks

Automated validation and formatting hooks are included:

PreToolUse

• Validates plugin structure before Write/Edit operations
• Exit code 2 blocks unsafe operations
• Provides actionable error messages

SessionStart

• Displays plugin load confirmation

Development Workflow

Prerequisites

Before starting plugin development:

1. Clone or download this template:

   git clone https://github.com/kossakovsky/cc-plugins.git
   cd cc-plugins

2. Install this plugin (see Installation above)

3. Create a new plugin:

   /plugin-development:init my-plugin
   cd my-plugin/

1. Initialize

Once installed, create your plugin:

cd my-projects/
/plugin-development:init my-plugin
cd my-plugin/

2. Add Components

/plugin-development:add-command hello "Greet the user"
# Edit commands/hello.md with your instructions

/plugin-development:add-skill my-expertise "Use when working with X"
# Edit skills/my-expertise/SKILL.md

3. Validate

/plugin-development:validate

Fix any errors or warnings.

4. Test Locally

/plugin-development:test-local
/plugin marketplace add ../dev-marketplace
/plugin install my-plugin@dev-marketplace

Test your commands:

/my-plugin:hello

5. Iterate

After making changes:

/plugin-development:validate
/plugin uninstall my-plugin@dev-marketplace
/plugin install my-plugin@dev-marketplace
# Test again

6. Review Before Release

/agents plugin-reviewer

Fix any critical or high-priority issues identified.

7. Submit

Submit your plugin to the community marketplace:

/plugin-development:submit

See CONTRIBUTING.md for manual submission instructions.

Documentation

The plugin includes comprehensive reference material:

Schemas

• schemas/plugin-manifest.md - plugin.json structure
• schemas/hooks-schema.md - Hooks configuration
• schemas/marketplace-schema.md - Marketplace structure

Templates

• templates/plugin-manifest.json - Starter plugin.json
• templates/marketplace-manifest.json - Marketplace template
• templates/command-template.md - Command structure
• templates/skill-template.md - Skill structure
• templates/agent-template.md - Agent structure

Examples

• examples/simple-plugin.md - Complete minimal plugin example
• examples/testing-workflow.md - Step-by-step testing guide

Best Practices

• best-practices/organization.md - Plugin structure guidelines
• best-practices/naming-conventions.md - Naming standards

Architecture

Hybrid Design

Skill (Read-First):

• Ambient, automatic activation
• Read-only by default (Read, Grep, Glob)
• Proposes commands for execution
• Progressive disclosure keeps it concise

Commands (Explicit):

• User-triggered actions
• Deterministic operations
• Template-based generation
• Clear consent for modifications

Agent (Deep Analysis):

• Separate context window
• Multi-file analysis
• Comprehensive reporting
• Use for release readiness

Hooks (Automation):

• Validation before writes
• Formatting after writes
• Automated guardrails
• Safety first

Safety & Permissions

Default Safety

• Skill is read-only by default
• All writes go through explicit commands
• Hooks block unsafe operations (exit code 2)
• Agent proposes changes, doesn't execute

Recommended Permissions

For enhanced security, configure in .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "SlashCommand:/plugin-development:*"
    ]
  }
}

Troubleshooting

Plugin not loading?

• Check /plugin list to verify installation
• Verify plugin.json doesn't include component fields for standard paths
• If using custom paths, ensure they're relative (e.g., ["./custom/cmd.md"])
• Run /plugin-development:validate

Commands not showing?

• Check /help for command list
• Ensure commands/ has .md files with frontmatter
• Verify description field in frontmatter
• Reinstall the plugin

Skills not triggering?

• Check SKILL.md frontmatter name matches directory (kebab-case)
• Verify description includes both what the Skill does AND when to use it
• Include specific trigger keywords users would naturally mention
• Description must be max 1024 characters
• Skills are model-invoked (automatically activate based on context)

Hooks not running?

• Make scripts executable: chmod +x scripts/*.sh
• Use ${CLAUDE_PLUGIN_ROOT} in hook commands
• Verify hook config in hooks/hooks.json matches expected events
• Use claude --debug to see hook execution

Contributing

This plugin follows its own best practices:

• kebab-case naming throughout
• Progressive disclosure in skills
• Template-based generation
• Comprehensive validation

To extend:

1. Add new commands in commands/
2. Enhance the skill with new reference docs
3. Update the reviewer agent with new checks
4. Add hooks for new automation

Resources

Official Documentation

• Claude Code Plugins
• Plugin Marketplaces
• Plugins Reference
• Slash Commands

Local Documentation

See skills/plugin-authoring/ for:

• Schemas (plugin manifest, hooks, marketplace)
• Templates (reusable starter files)
• Examples (complete working plugins)
• Best practices (organization, naming)

License

MIT License - See LICENSE file for details

Version

1.3.0

Changelog

• 1.3.0 - Streamlined hooks, removed stub format-or-lint script, improved validation
• 1.2.0 - Added plugin-reviewer agent, enhanced skill guidance, added best practices docs
• 1.1.0 - Added add-skill, add-agent, add-hook commands, test-local workflow
• 1.0.0 - Initial release with init, add-command, validate commands, plugin-authoring skill

Support

For issues or questions:

• Using the template: See the main README for template setup instructions
• Plugin issues: Check validation output: /plugin-development:validate
• Best practices: Review skills/plugin-authoring/best-practices/
• Deep audit: Request deep audit: /agents plugin-reviewer
• Debug mode: Test with debug mode: claude --debug