Plugin Builder Skill

Purpose

This skill guides you through creating well-structured Claude Code plugins with all necessary components, following best practices for discoverability, maintainability, and user experience.

When to Use

Use this skill when:

• Creating a new Claude Code plugin from scratch
• Adding components (skills, commands, agents, hooks) to existing plugins
• Generating properly structured SKILL.md files
• Setting up marketplace plugin registration
• Validating plugin metadata and structure

Prerequisites

• Access to a Claude Code marketplace repository
• Understanding of the plugin's intended functionality
• Basic knowledge of JSON and Markdown formats
• Location of the marketplace root directory

Plugin Architecture Overview

A Claude Code plugin follows this structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json       # Required: Plugin metadata
├── skills/               # Optional: Agent Skills
│   └── skill-name/
│       ├── SKILL.md      # Skill instructions
│       ├── scripts/      # Optional: Executable code
│       └── resources/    # Optional: Templates, data
├── commands/             # Optional: Custom slash commands
│   └── command-name.md
├── agents/               # Optional: Custom agent definitions
├── hooks/                # Optional: Event handlers
│   └── hooks.json
└── .mcp.json            # Optional: MCP server configuration

Instructions

Step 1: Plan the Plugin

Before creating files, clarify:

1. Plugin name (use kebab-case: my-plugin-name)
2. Purpose (what problem does it solve?)
3. Components needed (skills, commands, agents, hooks?)
4. Target users (who will use this plugin?)

Step 2: Create Plugin Directory Structure

1. Navigate to the marketplace plugins/ directory
2. Create the plugin directory: plugins/category/plugin-name/
3. Create required subdirectories:

   mkdir -p plugins/category/plugin-name/.claude-plugin
   mkdir -p plugins/category/plugin-name/skills
   mkdir -p plugins/category/plugin-name/commands  # if needed
   

Step 3: Generate plugin.json

Create .claude-plugin/plugin.json with this structure:

{
  "name": "plugin-name",
  "description": "Clear, concise description of plugin functionality (1-2 sentences)",
  "version": "1.0.0",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  }
}

Required fields:

• name: Plugin identifier (kebab-case, no spaces)
• description: User-facing description (be specific about what it does)
• version: Semantic version (major.minor.patch)
• author.name: Author's name

Version Guidelines:

• Start with 1.0.0 for initial release
• Increment patch (1.0.1) for bug fixes
• Increment minor (1.1.0) for new features (backward compatible)
• Increment major (2.0.0) for breaking changes

Step 4: Create Skills (if applicable)

For each skill in the plugin:

1. Create skill directory:

   mkdir -p plugins/category/plugin-name/skills/skill-name
   

2. Create SKILL.md using progressive disclosure format:

# Skill Name

## Purpose
[1-2 sentences: What this skill does and its main value]

## When to Use
[Bullet list of specific scenarios where this skill applies]
- Creating X
- Automating Y
- Solving Z problem

## Prerequisites
[What's needed before using this skill]
- Required tools or libraries
- Necessary permissions or access
- Context or information needed

## Instructions

### Task 1: [First Major Step]
[Detailed step-by-step instructions]
1. Do this first
2. Then do this
3. Finally do this

### Task 2: [Second Major Step]
[More detailed instructions]

[Continue with all major tasks...]

## Examples

### Example 1: [Concrete Use Case]
[Show complete example with actual code/commands]

\`\`\`language
[actual code]
\`\`\`

### Example 2: [Another Use Case]
[Another complete example]

## Best Practices
- [Specific practice 1]
- [Specific practice 2]
- [Specific practice 3]

## Common Issues
- **Problem:** [Description]
  **Solution:** [How to fix]
- **Problem:** [Description]
  **Solution:** [How to fix]

3. Add optional resources:

   mkdir -p plugins/category/plugin-name/skills/skill-name/resources
   mkdir -p plugins/category/plugin-name/skills/skill-name/scripts
   

Skill Best Practices:

• Focus: Each skill should do ONE thing well
• Discoverability: Use clear, searchable names and descriptions
• Progressive disclosure: Start with overview, then details, then examples
• Actionable: Provide concrete steps, not generic advice
• Examples: Include real, working examples users can adapt
• Error handling: Document common issues and solutions

Step 5: Create Commands (if applicable)

For custom slash commands:

1. Create command file:

   touch plugins/category/plugin-name/commands/command-name.md
   

2. Write command markdown:

# Command Name

[Description of what this command does]

## Usage
/command-name [arguments]

## Examples
/command-name example-arg

## Parameters
- `arg1`: Description of first argument
- `arg2`: Description of second argument (optional)

## Instructions for Claude
[Detailed instructions for what Claude should do when this command is invoked]

1. Step 1
2. Step 2
3. Step 3

Step 6: Update Marketplace Registry

1. Open marketplace.json: Located at .claude-plugin/marketplace.json in the repository root

2. Add plugin entry:

   {
     "name": "marketplace-name",
     "plugins": [
       {
         "name": "plugin-name",
         "source": "./plugins/category/plugin-name",
         "description": "Plugin description"
       }
     ]
   }
   

   Important: For local plugins, the source field must start with ./ to specify a relative path from the marketplace root.

Step 7: Validate Plugin

Checklist:

• plugin.json exists and has all required fields
• Plugin name uses kebab-case (no spaces, lowercase with hyphens)
• Description is clear and specific
• Version follows semantic versioning (major.minor.patch)
• All SKILL.md files follow progressive disclosure format
• Examples are included in all SKILL.md files
• Commands have clear usage instructions
• Plugin is registered in marketplace.json
• File paths are correct and accessible

Step 8: Test Locally

1. Install the plugin locally:

   • User runs: /plugin install plugin-name@marketplace-name

2. Test skill invocation:

   • Verify skills are discoverable
   • Test with relevant prompts
   • Check that instructions are clear

3. Test commands:

   • Run each slash command
   • Verify behavior matches documentation

4. Iterate:

   • Fix any issues found
   • Update documentation as needed
   • Increment version number for changes

Complete Examples

Example 1: Creating a Data Validation Plugin

Scenario: Create a plugin that validates JSON schemas

Step-by-step:

1. Create structure:

   mkdir -p plugins/data/json-validator/.claude-plugin
   mkdir -p plugins/data/json-validator/skills/json-validator
   

2. Create plugin.json:

   {
     "name": "json-validator",
     "description": "Validates JSON data against schemas with detailed error reporting",
     "version": "1.0.0",
     "author": {
       "name": "Data Team"
     }
   }
   

3. Create SKILL.md:

   # JSON Validator Skill
   
   ## Purpose
   Validates JSON data against JSON Schema specifications and provides detailed error reports.
   
   ## When to Use
   - Validating API request/response payloads
   - Checking configuration files
   - Ensuring data structure compliance
   
   ## Prerequisites
   - JSON data to validate
   - JSON Schema definition
   - Understanding of JSON Schema syntax
   
   ## Instructions
   
   ### Validate JSON Data
   1. Receive or locate the JSON data to validate
   2. Receive or locate the JSON Schema
   3. Parse both JSON data and schema
   4. Validate data against schema
   5. Report validation results with specific errors
   6. Suggest fixes for validation errors
   
   ## Examples
   
   ### Example 1: Validate User Object
   Schema:
   \`\`\`json
   {
     "type": "object",
     "properties": {
       "name": {"type": "string"},
       "age": {"type": "number"}
     },
     "required": ["name"]
   }
   \`\`\`
   
   Valid data:
   \`\`\`json
   {"name": "Alice", "age": 30}
   \`\`\`
   
   Invalid data:
   \`\`\`json
   {"age": 30}
   \`\`\`
   Error: Missing required property 'name'
   
   ## Best Practices
   - Always show the full error path for nested objects
   - Suggest corrected JSON when possible
   - Validate schema itself before using it
   - Handle common schema mistakes gracefully
   
   ## Common Issues
   - **Problem:** Schema reference ($ref) not resolved
     **Solution:** Ensure all referenced schemas are accessible
   - **Problem:** Type coercion confusion
     **Solution:** Be explicit about type expectations
   

4. Update marketplace.json:

   {
     "plugins": [
       {
         "name": "json-validator",
         "source": "./plugins/data/json-validator",
         "description": "Validates JSON data against schemas"
       }
     ]
   }
   

Example 2: Adding a Skill to Existing Plugin

Scenario: Add a new skill to the json-validator plugin

1. Create new skill directory:

   mkdir -p plugins/data/json-validator/skills/schema-generator
   

2. Create SKILL.md:

   # Schema Generator Skill
   
   ## Purpose
   Generates JSON Schema definitions from example JSON data.
   
   ## When to Use
   - Creating schemas from existing data
   - Documenting API data structures
   - Reverse engineering schemas
   
   [... rest of SKILL.md ...]
   

3. Update plugin version: Edit plugin.json:

   {
     "version": "1.1.0"
   }
   

   (Minor version increment for new feature)

Naming Conventions

Plugins:

• Use kebab-case: my-plugin-name
• Be descriptive but concise
• Avoid generic names like "helper" or "utility"
• Good: json-validator, code-formatter, api-tester
• Bad: helper, utils, my_plugin

Skills:

• Use clear, action-oriented names
• Match the skill's primary function
• Good: json-validator, schema-generator, data-transformer
• Bad: skill1, helper, misc

Commands:

• Start with verb when possible
• Be specific about action
• Good: validate-json, generate-schema, format-code
• Bad: do-thing, run, help

Best Practices Summary

Plugin Design

• Single responsibility: Each plugin should have a clear, focused purpose
• Composability: Plugins should work well together
• Discoverability: Names and descriptions should make purpose obvious
• Documentation: Include examples for all features
• Versioning: Follow semantic versioning strictly

Skill Design

• Progressive disclosure: Overview → Instructions → Examples
• Concrete examples: Show real code, not pseudocode
• Error handling: Document common issues and solutions
• Prerequisites: List what's needed upfront
• Modularity: Keep skills focused on specific tasks

Testing

• Local testing: Always test before committing
• User perspective: Test as if you've never seen it before
• Documentation: Verify all examples work
• Edge cases: Test with unusual inputs
• Integration: Test with other plugins

Maintenance

• Version bump: Update version for any changes
• Changelog: Document what changed and why
• Backward compatibility: Don't break existing users
• Deprecation: Warn before removing features
• Updates: Keep dependencies and references current

Common Issues and Solutions

Issue 1: Skill Not Being Discovered

Problem: Claude doesn't load the skill when relevant

Solutions:

• Check SKILL.md filename is exactly SKILL.md (case-sensitive)
• Verify skill directory path: plugins/category/plugin/skills/skill-name/SKILL.md
• Ensure plugin is registered in marketplace.json
• Check that skill name and description are descriptive
• Verify plugin is installed: /plugin list

Issue 2: Invalid Plugin Metadata

Problem: Plugin fails to install or load

Solutions:

• Validate JSON syntax in plugin.json (no trailing commas, proper quotes)
• Ensure all required fields present: name, description, version, author.name
• Check name uses kebab-case with no spaces
• Verify version follows semantic versioning (X.Y.Z)
• Ensure file is named exactly plugin.json

Issue 3: Command Not Working

Problem: Slash command doesn't execute

Solutions:

• Verify command file is in commands/ directory
• Check filename matches command name
• Ensure markdown formatting is correct
• Verify plugin is installed and loaded
• Check command syntax matches documentation

Issue 4: Marketplace Registration Failed

Problem: Plugin not showing in marketplace

Solutions:

• Verify marketplace.json syntax is valid
• Check plugin source path is correct relative to marketplace root
• Ensure plugin name in marketplace.json matches plugin.json
• Verify marketplace.json is in .claude-plugin/ at repo root

Issue 5: Version Conflicts

Problem: Multiple versions causing issues

Solutions:

• Use semantic versioning consistently
• Document breaking changes clearly
• Test compatibility with existing plugins
• Update marketplace.json with correct version
• Consider version deprecation strategy

Resources

The plugin-builder includes templates in skills/plugin-builder/resources/:

• plugin-template.json: Starter plugin.json
• skill-template.md: SKILL.md boilerplate
• command-template.md: Command file structure
• marketplace-entry.json: Marketplace registration example

Support

For plugin system documentation, see:

• Claude Code Plugins: https://docs.claude.com/en/docs/claude-code/plugins
• Agent Skills: https://docs.claude.com/en/docs/claude-code/skills
• Skills Best Practices: https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices