For Creators

Building Your First Plugin

Create and share your own Claude Code plugins with this step-by-step guide.

What You'll Create

A Claude Code plugin is just a GitHub repository with a specific directory structure and a manifest file. The manifest tells Claude Code what your plugin includes and how to use it.

Zero-friction publishing

Push your plugin to GitHub and we'll automatically discover it within an hour. No submission forms, no waiting for approval - just push and ship.

Plugin Directory Structure

Here's a typical plugin structure. Only the .claude-plugin/plugin.json manifest is required:

my-awesome-plugin/
├── .claude-plugin/          # Required: Plugin metadata
│   └── plugin.json          # Required: Plugin manifest
├── commands/                # Optional: Slash commands
│   ├── deploy.md
│   └── test.md
├── agents/                  # Optional: Specialized agents
│   ├── security-reviewer.md
│   └── test-writer.md
├── .mcp.json                # Optional: MCP server definitions
├── hooks/                   # Optional: Lifecycle hooks
│   └── hooks.json
├── README.md                # Recommended: Usage documentation
└── LICENSE                  # Recommended: License file

Only include what you need! A plugin can be as simple as a single manifest file, or as complex as dozens of commands, agents, and integrations.

The Plugin Manifest

The manifest file (.claude-plugin/plugin.json) describes your plugin:

Minimal Example

{
  "name": "my-formatter",
  "version": "1.0.0",
  "description": "Code formatting plugin for multiple languages",
  "keywords": ["formatter", "code-quality", "development"],
  "strict": true
}

name: Plugin identifier (lowercase, hyphens, no spaces)

version: Semantic version (e.g., "1.0.0", "2.1.3")

description: Clear, concise description of what your plugin does

keywords: Array of tags for discovery and categorization

strict: Enable strict mode (recommended: true)

Complete Example

{
  "name": "devops-suite",
  "version": "2.1.0",
  "description": "Complete DevOps automation with deployment, monitoring, and alerts",
  "keywords": ["devops", "deployment", "ci-cd", "monitoring", "automation"],
  "strict": true,
  "commands": ["./commands/deploy.md", "./commands/rollback.md"],
  "agents": ["./agents/infrastructure.md", "./agents/monitoring.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/test-runner.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["@aws-sdk/mcp-server"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

This example includes commands, agents, hooks, and MCP servers. Each component is optional - include only what your plugin needs. Note: commands and agents use arrays of file paths. hooks can be a path to hooks.json or inline configuration as shown.

Step-by-Step: Create Your First Plugin

Create a GitHub Repository

Initialize a new public GitHub repository for your plugin. You can use an existing repo too - just add the plugin structure to it.

git init my-awesome-plugin && cd my-awesome-plugin

Create the Plugin Directory

Make the required .claude-plugin directory:

mkdir .claude-plugin

Write Your Manifest

Create .claude-plugin/plugin.json with your plugin metadata. Start simple - you can add more features later.

Add Your Components (Optional)

Add commands, agents, hooks, or MCP servers as needed. Each component is a markdown file with frontmatter:

Command Example (commands/deploy.md):

---
description: Deploy your application to production
---

Deploy the application using the configured deployment strategy.
Include any validation checks and rollback procedures.

Agent Example (agents/security-reviewer.md):

---
description: Specialized security audit agent
capabilities: ["security-review", "vulnerability-scan", "code-audit"]
---

Expert in security best practices and vulnerability detection.
Reviews code for common security issues and compliance.

Write a README

Document how to use your plugin. The README is shown on your plugin's detail page in the marketplace.

Push to GitHub

Commit and push your plugin to GitHub. Make sure the repository is public.

git add . && git commit -m 'Initial plugin release'

git push origin main

✓

Wait for Auto-Discovery

That's it! Our system automatically discovers plugins with valid manifests every hour. Your plugin will appear in the marketplace once discovered and ingested.

Discovery runs every hour. Check back later to see your plugin in the marketplace.

Best Practices

Descriptive Names

Use clear, lowercase names with hyphens. Good: code-formatter. Avoid: MyPlugin123.

Semantic Versioning

Follow semver (major.minor.patch). Increment the major version for breaking changes, minor for new features, patch for bug fixes.

Good Keywords

Use relevant keywords from categories like "development", "productivity", "testing", etc. This helps users discover your plugin.

Comprehensive README

Document installation, configuration, usage examples, and troubleshooting. Clear docs = happy users.

Publishing to Marketplaces

If you're maintaining a marketplace repository with multiple plugins, you need to understand the relationship between marketplace.json and individual plugin manifests.

Multi-Plugin Repository Structure

Marketplace repositories bundle multiple plugins in a single repo:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json     # Marketplace manifest
├── plugin-one/
│   ├── .claude-plugin/
│   │   └── plugin.json      # Required if strict: true
│   └── commands/
├── plugin-two/
│   ├── .claude-plugin/
│   │   └── plugin.json      # Required if strict: true
│   └── agents/
└── README.md

Important: Strict Mode Default

By default, strict: true. This means each plugin directory MUST include .claude-plugin/plugin.json. If you want the marketplace entry to serve as the complete manifest, explicitly set strict: false for that plugin.

When to Use Strict: False

Set strict: false only when:

•Your marketplace entry provides the complete plugin manifest (name, version, description, commands, agents, etc.)
•You don't want to maintain separate plugin.json files
•All plugin metadata is centralized in marketplace.json

Example marketplace.json with strict: false:

{
  "name": "my-marketplace",
  "plugins": [
    {
      "name": "simple-plugin",
      "source": "./simple-plugin",
      "strict": false,
      "description": "Complete manifest here",
      "version": "1.0.0",
      "commands": ["./commands/deploy.md"],
      "agents": ["./agents/helper.md"]
    }
  ]
}

Marketplace Maintainer Checklist

Verify each plugin directory has .claude-plugin/plugin.json (if strict: true, the default)

OR set strict: false in marketplace entry and provide complete manifest metadata there

Test locally with /plugin marketplace add ./path before publishing

Include clear README explaining your repo structure and installation steps

Document any special configuration or safety considerations

For complete marketplace schema and examples, see Plugin marketplaces documentation.

Additional Resources

Official Plugin Guidelines

Read Anthropic's official documentation for plugin development standards and best practices.

View Documentation

Browse Examples

Explore existing plugins to see how others structure their manifests and components.

Browse Plugins

Ready to Ship?

Create your plugin, push to GitHub, and we'll discover it automatically. No forms, no waiting for approval.

Browse Existing Plugins Back to Learning Center