Claude Code Plugins

Community-maintained marketplace

Feedback

Guide for creating Claude Code plugins with proper structure, metadata, and components. This skill should be used when creating plugins, writing manifests, or setting up marketplaces.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name plugins-scaffolding
description Guide for creating Claude Code plugins with proper structure, metadata, and components. This skill should be used when creating plugins, writing manifests, or setting up marketplaces.

Plugins Scaffold Skill

This skill provides guidance for creating Claude Code plugins, including structure, manifests, components (commands, agents, skills, hooks, MCP servers), and marketplace distribution.

When to Use This Skill

This skill should be used when:

  • Creating a new Claude Code plugin from scratch
  • Understanding plugin architecture and components
  • Writing plugin.json manifests
  • Creating plugin commands, agents, skills, hooks, or MCP servers
  • Setting up plugin marketplaces
  • Distributing plugins to teams or the community
  • Validating and testing plugins before distribution
  • Understanding plugin vs marketplace structure

Plugin Architecture Overview

What Are Plugins?

Plugins are extensions that add custom functionality to Claude Code, shareable across projects and teams. They can include:

  • Commands: Custom slash commands for interactive workflows
  • Agents: Specialized Claude instances with specific capabilities
  • Skills: Just-in-time expertise that Claude autonomously invokes
  • Hooks: Event handlers for automation and workflow customization
  • MCP Servers: External tool integrations via Model Context Protocol

Plugin vs Marketplace

Plugin:

  • A single package of functionality (one plugin = one purpose)
  • Contains commands, agents, skills, hooks, or MCP servers
  • Has a .claude-plugin/plugin.json manifest
  • Can be distributed via marketplaces or standalone

Marketplace:

  • A catalog of multiple plugins
  • Has a .claude-plugin/marketplace.json manifest
  • Enables centralized discovery and installation
  • Can host plugins from multiple sources (local paths, GitHub repos, git URLs)

Plugin Directory Structure

Every plugin must follow this standard structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                # Optional: Slash commands
│   ├── command-one.md
│   └── command-two.md
├── agents/                  # Optional: Custom agents
│   └── agent-name.md
├── skills/                  # Optional: Agent skills
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
├── hooks/                   # Optional: Event handlers
│   └── hooks.json
├── .mcp.json               # Optional: MCP server config
├── scripts/                # Optional: Utility scripts
├── README.md               # Recommended: Documentation
└── LICENSE                 # Recommended: License file

Critical Requirements:

  • The .claude-plugin/plugin.json file is REQUIRED for all plugins
  • All component directories (commands, agents, skills, hooks) must exist at plugin root, NOT within .claude-plugin/
  • Component directories are optional - only create what your plugin needs
  • Use kebab-case for plugin directory names (e.g., my-plugin, not MyPlugin or my_plugin)

Plugin Manifest (plugin.json)

The plugin.json file is your plugin's core configuration. It must be located at .claude-plugin/plugin.json.

Required Fields

{
  "name": "plugin-name"
}

Field Specifications:

  • name (required)
    • Unique identifier in kebab-case format
    • Examples: "deployment-tools", "ai-security", "git-helpers"
    • Should be descriptive and match the plugin directory name
    • Must be unique within a marketplace

Recommended Metadata Fields

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of what this plugin does",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://github.com/owner/plugin-repo",
  "repository": "https://github.com/owner/plugin-repo",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2", "keyword3"]
}

Field Specifications:

  • version (recommended)

    • Use semantic versioning: MAJOR.MINOR.PATCH
    • Example: "2.1.0"
    • See Versioning section below for details
  • description (recommended)

    • Brief explanation of plugin purpose
    • Should clearly state what the plugin does
    • Keep under 200 characters for marketplace display
  • author (recommended)

    • Object containing name, email (optional), and URL (optional)
    • Helps users know who maintains the plugin
  • homepage (recommended)

    • URL to plugin documentation
    • Often same as repository URL
  • repository (recommended)

    • Source code repository link
    • Enables users to view source and report issues
  • license (recommended)

    • SPDX license identifier (e.g., "MIT", "Apache-2.0", "GPL-3.0")
    • Critical for open source distribution
  • keywords (recommended)

    • Array of tags for discovery
    • Examples: ["git", "automation", "security", "devops"]
    • Helps users find your plugin in marketplaces

Custom Component Paths (Advanced)

{
  "name": "plugin-name",
  "commands": "./custom-commands",
  "agents": "./custom-agents/agent.md",
  "hooks": "./custom-hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}

Path Configuration Rules:

  • All paths must be relative to plugin root and begin with ./
  • Custom paths supplement (not replace) default directories
  • Use ${CLAUDE_PLUGIN_ROOT} environment variable for absolute path references in hooks and MCP configs

When to Use Custom Paths:

  • Organizing complex plugins with non-standard layouts
  • Migrating existing projects to plugin format
  • Keeping components in specific directories for workflow reasons

Plugin Components

Commands (Slash Commands)

Commands are markdown files in the commands/ directory that define interactive workflows.

File Structure:

commands/
├── setup-project.md
└── deploy-staging.md

Command File Format:

# Command Title

Brief description of what this command does.

## Instructions

Step-by-step instructions for Claude Code to execute when this command is invoked.

1. First step
2. Second step
3. Third step

## Important Notes

Any constraints, requirements, or special considerations.

Best Practices:

  • Use clear, imperative instructions
  • Specify what NOT to do (constraints)
  • Include examples when helpful
  • Keep commands focused on one task
  • Use commands for interactive setup and configuration

When to Use Commands vs Skills:

  • Commands: One-time interactive setup, configuration, scaffolding
  • Skills: Ongoing expertise that applies across multiple sessions

Agents (Custom Agents)

Agents are markdown files in the agents/ directory that describe specialized Claude instances.

File Structure:

agents/
└── security-auditor.md

Agent File Format:

---
description: Specialized agent for security auditing and vulnerability detection
---

# Security Auditor Agent

This agent specializes in identifying security vulnerabilities, reviewing authentication mechanisms, and conducting security audits.

## Capabilities

- Identify SQL injection vulnerabilities
- Review authentication and authorization flows
- Validate input sanitization
- Assess data protection measures
- Generate security audit reports

## When to Invoke

Use this agent when:
- Implementing authentication flows
- Reviewing security-sensitive code
- Conducting pre-deployment security audits

Best Practices:

  • Clearly define the agent's specialization
  • List specific capabilities the agent provides
  • Specify when the agent should be invoked
  • Use agents for complex, multi-step specialized tasks

Skills (Agent Skills)

Skills are directories in the skills/ folder containing SKILL.md files that provide just-in-time expertise.

File Structure:

skills/
├── brand-guidelines/
│   └── SKILL.md
└── security-standards/
    ├── SKILL.md
    └── references/
        └── standards.md

SKILL.md Format:

---
name: Skill Name
description: Guide for [topic]. This skill should be used when [specific use cases] (max 200 chars)
---

# Skill Name Skill

This skill provides guidance on [topic].

## When to Use This Skill

This skill should be used when:
- [Use case 1]
- [Use case 2]

## Guidelines

[Core expertise and instructions]

Best Practices:

  • See the skills-scaffold skill for comprehensive skill creation guidance
  • Use skills for ongoing expertise, not one-time setup
  • Write discoverable descriptions with keywords using third-person form
  • Keep skills focused on one domain
  • Use progressive disclosure (core content in SKILL.md, details in references/ directory)

Hooks (Event Handlers)

Hooks are JSON configurations in hooks/hooks.json that execute in response to events.

File Location:

hooks/
└── hooks.json

Hook Configuration Format:

{
  "hooks": [
    {
      "name": "pre-commit-check",
      "event": "PreToolUse",
      "tool": "Bash",
      "script": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
      "blockOnNonZeroExit": true
    },
    {
      "name": "session-setup",
      "event": "SessionStart",
      "script": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"
    }
  ]
}

Event Types:

  • PreToolUse: Before a tool is executed
  • PostToolUse: After a tool completes
  • UserPromptSubmit: When user submits a prompt
  • Notification: When a notification is triggered
  • Stop: When execution stops
  • SessionStart: When a new session begins

Best Practices:

  • Use ${CLAUDE_PLUGIN_ROOT} for script paths
  • Set blockOnNonZeroExit: true to halt execution on errors
  • Keep hook scripts fast to avoid workflow delays
  • Use hooks for automation, validation, and enforcement

MCP Servers (External Tool Integration)

MCP servers integrate external tools via the Model Context Protocol.

File Location:

.mcp.json

MCP Configuration Format:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/index.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Best Practices:

  • Use ${CLAUDE_PLUGIN_ROOT} for script paths
  • Document required environment variables
  • Provide clear setup instructions in README.md
  • Test MCP server functionality independently

Plugin Development Workflow

Step 1: Plan the Plugin

Before creating a plugin, determine:

  • Purpose: What problem does this plugin solve?
  • Components: What components does it need?
    • Commands for interactive workflows?
    • Agents for specialized tasks?
    • Skills for ongoing expertise?
    • Hooks for automation?
    • MCP servers for external tools?
  • Scope: Is this one plugin or should it be split?
  • Distribution: Will this be private (team) or public (community)?

Design Principle: One plugin = one purpose. When solving multiple unrelated problems, create multiple plugins.

Step 2: Create Directory Structure

mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/commands    # If needed
mkdir -p plugin-name/agents      # If needed
mkdir -p plugin-name/skills      # If needed
mkdir -p plugin-name/hooks       # If needed
mkdir -p plugin-name/scripts     # If needed

Step 3: Write Plugin Manifest

Create .claude-plugin/plugin.json:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief description of plugin purpose",
  "author": {
    "name": "Your Name",
    "url": "https://yoursite.com"
  },
  "repository": "https://github.com/owner/plugin-repo",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Step 4: Create Plugin Components

Add the components your plugin needs:

For Commands:

  • Create markdown files in commands/ directory
  • Use clear, imperative instructions
  • Specify constraints and requirements

For Agents:

  • Create markdown files in agents/ directory
  • Define specialization and capabilities
  • Specify invocation criteria

For Skills:

  • Create skills/{skill-name}/SKILL.md with YAML frontmatter
  • Follow the skills-scaffold skill guidance
  • Use progressive disclosure for token efficiency

For Hooks:

  • Create hooks/hooks.json configuration
  • Write hook scripts in scripts/ directory
  • Use ${CLAUDE_PLUGIN_ROOT} for paths

For MCP Servers:

  • Create .mcp.json configuration
  • Implement MCP server according to protocol spec
  • Document setup and environment variables

Step 5: Add Documentation

Create a comprehensive README.md:

# Plugin Name

Brief description of what this plugin does.

## Features

- Feature 1
- Feature 2

## Installation

\`\`\`bash
/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace-name
\`\`\`

## Usage

### Commands

- \`/command-name\`: Description of what it does

### Skills

- \`skill-name\`: Description of expertise provided

## Configuration

Any required setup or environment variables.

## License

License information.

Step 6: Validate and Test

Before distribution:

  1. Validate JSON syntax

    # Check plugin.json is valid JSON
    cat .claude-plugin/plugin.json | jq .
    
  2. Test locally

    # Add as local marketplace
    /plugin marketplace add ./path/to/plugin-parent-directory
    
    # Install the plugin
    /plugin install plugin-name@marketplace-name
    
  3. Test all components

    • Invoke each command and verify it works
    • Test agents by requesting their specialized tasks
    • Verify skills load when expected
    • Check hooks execute at correct events
    • Test MCP server integration
  4. Review security

    • Audit all scripts and code
    • Check for hardcoded credentials
    • Document required environment variables
    • Ensure no sensitive data in repository

Step 7: Distribute via Marketplace

See Marketplace Distribution section below.

Plugin Versioning

Follow Semantic Versioning:

  • MAJOR (x.0.0): Breaking changes or incompatible API changes
  • MINOR (0.x.0): New features added in a backward-compatible manner
  • PATCH (0.0.x): Backward-compatible bug fixes

When to Bump Version:

  • MAJOR: Changing command names, removing components, changing behavior in incompatible ways
  • MINOR: Adding new commands, agents, skills; enhancing existing features
  • PATCH: Fixing bugs, typos, documentation; minor improvements

Version Update Workflow:

  1. Update version in .claude-plugin/plugin.json
  2. Update version in marketplace.json (if applicable)
  3. Update CHANGELOG.md with changes
  4. Update README.md if functionality changed
  5. Create git tag for the release (e.g., v1.2.0)

Marketplace Distribution

Creating a Plugin Marketplace

A marketplace is a repository that catalogs multiple plugins.

Directory Structure:

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/                    # If using local plugins
│   ├── plugin-one/
│   └── plugin-two/
└── README.md

Marketplace Manifest (.claude-plugin/marketplace.json):

{
  "name": "marketplace-name",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Brief description of this marketplace",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "plugin-one",
      "source": "./plugins/plugin-one",
      "description": "What plugin-one does",
      "version": "1.0.0",
      "author": {
        "name": "Author Name",
        "url": "https://example.com"
      },
      "repository": "https://github.com/owner/plugin-one",
      "license": "MIT",
      "keywords": ["keyword1", "keyword2"]
    }
  ]
}

Required Fields:

  • name: Unique marketplace identifier (kebab-case)
  • owner: Maintainer information with name and email
  • plugins: Array of plugin entries

Optional Metadata:

  • metadata.description: Marketplace overview
  • metadata.version: Marketplace version
  • metadata.pluginRoot: Base path for relative plugin sources (e.g., "./plugins")

Plugin Source Types

Relative Paths (same repository):

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}
  • Best for: Curated marketplaces with bundled plugins
  • The pluginRoot metadata field sets the base directory

GitHub Repositories:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}
  • Best for: Distributed development, individual plugin repositories
  • Supports both public and private repositories

Git Repositories:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}
  • Best for: GitLab, Bitbucket, or self-hosted git servers
  • Works with any git-compatible URL

Distribution Methods

GitHub (Recommended):

  1. Create a repository with .claude-plugin/marketplace.json at root
  2. Add plugins either:
    • As subdirectories (with pluginRoot)
    • As external GitHub repositories (with source objects)
  3. Users add the marketplace:
    /plugin marketplace add owner/repo
    

Other Git Services:

/plugin marketplace add https://gitlab.com/company/plugins.git

Local Development:

/plugin marketplace add ./my-local-marketplace

Marketplace Operations

List configured marketplaces:

/plugin marketplace list

Update marketplace metadata:

/plugin marketplace update marketplace-name

Remove a marketplace:

/plugin marketplace remove marketplace-name

Install plugins:

/plugin install plugin-name@marketplace-name

Team Configuration

Configure .claude/settings.json in repositories to auto-install marketplaces:

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

When team members trust the folder, configured marketplaces install automatically.

Common Plugin Patterns

Pattern: Developer Productivity Plugin

Use Case: Streamline common development tasks (git, deployments, testing)

Structure:

  • Multiple commands for different workflows
  • Hooks for automation (pre-commit, pre-push)
  • Skills for best practices

Example:

git-helpers/
├── .claude-plugin/plugin.json
├── commands/
│   ├── commit-push.md
│   └── setup-repo.md
├── hooks/
│   └── hooks.json
└── scripts/
    └── pre-commit.sh

Pattern: Domain Expertise Plugin

Use Case: Provide specialized knowledge (security, performance, architecture)

Structure:

  • Agents for specialized tasks
  • Skills for ongoing guidance
  • Commands for audits and reports

Example:

security-expert/
├── .claude-plugin/plugin.json
├── agents/
│   └── security-auditor.md
├── skills/
│   ├── security-standards/
│   │   └── SKILL.md
│   └── owasp-guidelines/
│       └── SKILL.md
└── commands/
    └── security-audit.md

Pattern: External Tool Integration Plugin

Use Case: Integrate external services (Azure DevOps, Jira, Slack)

Structure:

  • MCP server for API integration
  • Skills for tool usage guidelines
  • Commands for configuration

Example:

ado-integration/
├── .claude-plugin/plugin.json
├── .mcp.json
├── commands/
│   └── ado-init.md
├── skills/
│   └── ado-work-items/
│       └── SKILL.md
└── mcp-server/
    └── index.js

Pattern: Project Scaffolding Plugin

Use Case: Generate boilerplate code and project structure

Structure:

  • Commands for interactive scaffolding
  • Templates in supporting files
  • Skills for architecture guidance

Example:

project-scaffold/
├── .claude-plugin/plugin.json
├── commands/
│   ├── create-react-app.md
│   └── create-api.md
├── skills/
│   └── architecture-patterns/
│       └── SKILL.md
└── templates/
    ├── react-component.tsx
    └── api-endpoint.ts

Best Practices for Plugin Development

1. Keep Plugins Focused

  • One plugin = one purpose or domain
  • Create multiple small plugins rather than one mega-plugin
  • Avoid creating plugins that try to do everything

Good Examples:

  • git-helpers (git automation)
  • security-auditor (security scanning)
  • deployment-tools (deployment workflows)

Bad Example:

  • developer-tools (git + security + deployment + testing + ...)

2. Use Appropriate Components

  • Commands for interactive setup and configuration
  • Skills for ongoing expertise and guidelines
  • Agents for complex specialized tasks
  • Hooks for automation and enforcement
  • MCP servers for external tool integration

Avoid:

  • Using commands for ongoing expertise (use skills instead)
  • Using skills for one-time setup (use commands instead)
  • Duplicating functionality across components

3. Write Clear Documentation

  • Create comprehensive README.md with installation and usage instructions
  • Provide examples for all commands and features
  • Document required environment variables
  • Include troubleshooting section

4. Follow Semantic Versioning

  • Use MAJOR.MINOR.PATCH format
  • Bump versions appropriately based on changes
  • Document changes in CHANGELOG.md
  • Create git tags for releases

5. Test Thoroughly

  • Test locally before distribution
  • Validate JSON manifests
  • Test all commands, skills, agents
  • Verify hooks execute correctly
  • Test MCP server integration

6. Security Considerations

  • Audit all scripts and code
  • Never hardcode credentials
  • Use environment variables for secrets
  • Document security requirements
  • Avoid bundling unvetted third-party code
  • Avoid including sensitive organizational data

7. Use Consistent Naming

  • Plugin names: kebab-case (my-plugin)
  • Command files: kebab-case (my-command.md)
  • Skill directories: kebab-case (my-skill/)
  • Use descriptive names that indicate purpose

8. Leverage Environment Variables

  • Use ${CLAUDE_PLUGIN_ROOT} in hooks and MCP configs
  • Document required environment variables
  • Provide examples for configuration
  • Use .env.example files for templates

9. Organize Supporting Files

plugin-name/
├── scripts/        # Executable scripts for hooks/automation
├── templates/      # Template files for scaffolding
├── examples/       # Example configurations
└── docs/          # Additional documentation

10. Provide Examples

  • Include example usage in README.md
  • Show before/after for commands
  • Demonstrate integration patterns
  • Provide sample configurations

Plugin Validation Checklist

Before distributing a plugin, verify:

Structure:

  • .claude-plugin/plugin.json exists with required fields
  • Component directories at plugin root (not in .claude-plugin/)
  • kebab-case naming for plugin and components
  • README.md with installation and usage instructions

Manifest:

  • Name is unique and descriptive
  • Version follows semantic versioning
  • Description clearly states plugin purpose
  • Author information included
  • Repository URL provided
  • License specified
  • Keywords for discoverability

Components:

  • All commands tested and working
  • All agents tested with appropriate tasks
  • All skills have proper YAML frontmatter
  • All hooks execute at correct events
  • All MCP servers integrate correctly

Documentation:

  • README.md is comprehensive
  • All features documented with examples
  • Environment variables documented
  • Installation instructions clear
  • Troubleshooting section included

Quality:

  • JSON manifests are valid (test with jq)
  • No hardcoded credentials or secrets
  • All scripts audited for security
  • Plugin tested locally before distribution
  • CHANGELOG.md documents changes

Marketplace (if applicable):

  • Plugin entry in marketplace.json
  • Source path/URL is correct
  • Marketplace metadata updated
  • Version numbers consistent across files

Troubleshooting Plugin Development

Problem: Plugin Not Loading

Possible Causes:

  • Missing .claude-plugin/plugin.json
  • Invalid JSON in plugin.json
  • Wrong directory structure
  • Components in .claude-plugin/ instead of plugin root

Solution:

  • Verify plugin.json exists at .claude-plugin/plugin.json
  • Validate JSON syntax: cat .claude-plugin/plugin.json | jq .
  • Check component directories are at plugin root
  • Review directory structure against standards

Problem: Commands Not Appearing

Possible Causes:

  • Commands directory in wrong location
  • Command files not markdown (.md)
  • Custom commands path misconfigured

Solution:

  • Place commands in commands/ directory at plugin root
  • Ensure all command files end with .md
  • If using custom path, verify it starts with ./

Problem: Skills Not Loading

Possible Causes:

  • Missing SKILL.md file (case-sensitive)
  • Missing YAML frontmatter
  • Description too vague for Claude to match

Solution:

  • Verify each skill directory has SKILL.md (uppercase)
  • Ensure YAML frontmatter with name and description
  • Make description specific with relevant keywords
  • See skills-scaffold skill for details

Problem: Hooks Not Executing

Possible Causes:

  • Wrong path to hook script
  • Script not executable
  • Missing ${CLAUDE_PLUGIN_ROOT} environment variable

Solution:

  • Use ${CLAUDE_PLUGIN_ROOT} for all script paths
  • Make scripts executable: chmod +x scripts/*.sh
  • Test hook scripts independently first

Problem: MCP Server Not Connecting

Possible Causes:

  • Wrong command or args in .mcp.json
  • Missing environment variables
  • Server code has errors

Solution:

  • Verify command and args in .mcp.json
  • Document and provide required environment variables
  • Test MCP server independently
  • Check server logs for errors

Problem: Marketplace Not Installing Plugin

Possible Causes:

  • Wrong plugin source path/URL
  • Repository not accessible
  • Plugin directory doesn't contain plugin.json
  • Network connectivity issues

Solution:

  • Verify source path is correct (relative or URL)
  • Check repository is public or credentials configured
  • Ensure plugin.json exists in plugin directory
  • Test repository access manually

Advanced Topics

Plugin Composition

Plugins can reference each other's capabilities:

For git automation, the git-helpers plugin provides comprehensive commands.

For security standards, refer to the security-expert plugin's skills.

Best Practice: Keep plugins independent where possible, but document complementary plugins in README.md.

Multi-Language Support

Plugins can include scripts in different languages:

scripts/
├── python/
│   └── analyzer.py
├── javascript/
│   └── formatter.js
└── shell/
    └── deploy.sh

Best Practice: Document runtime requirements (Python version, Node version) in README.md and plugin.json dependencies field.

Plugin Templates and Generators

Create meta-plugins that generate other plugins:

Example: The ai-plugins plugin includes:

  • /plugins-scaffold command for generating plugin structure
  • plugins-scaffold skill for plugin development guidance
  • skills-scaffold skill for skill creation guidance

Environment-Specific Configuration

Use environment variables for configuration:

{
  "mcpServers": {
    "api-service": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "API_URL": "${API_URL}",
        "API_KEY": "${API_KEY}",
        "ENVIRONMENT": "${ENVIRONMENT:-development}"
      }
    }
  }
}

Best Practice: Provide .env.example file with required variables.

Summary

Creating effective Claude Code plugins requires:

  1. Planning: Determine purpose, components, and scope
  2. Structure: Follow standard directory layout
  3. Manifest: Write comprehensive plugin.json metadata
  4. Components: Use appropriate component types for tasks
  5. Documentation: Provide clear README with examples
  6. Testing: Validate thoroughly before distribution
  7. Security: Audit code and avoid hardcoded secrets
  8. Versioning: Follow semantic versioning
  9. Distribution: Share via marketplaces for easy discovery

Following these guidelines will result in well-structured plugins that enhance Claude Code's capabilities and provide value to users.

For skill creation specifically, the skills-scaffold skill provides detailed guidance.