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 30 minutes. 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: User-invoked slash commands
│   ├── deploy.md
│   └── test.md
├── agents/                  # Optional: Specialized agents
│   ├── security-reviewer.md
│   └── test-writer.md
├── skills/                  # Optional: Model-invoked capabilities
│   └── api-integration/
│       └── SKILL.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, skills, and integrations.

Component Locations

All component directories (commands/, agents/, skills/, hooks/) must be at the plugin root, not inside .claude-plugin/. The manifest file is the only thing inside .claude-plugin/.

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.

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, skills, 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.

Skill Example (skills/api-integration/SKILL.md)

---
description: Interact with REST APIs
---

Expert in making HTTP requests and handling API responses.
Claude will automatically use this when API interaction is needed.

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 30 minutes. Your plugin will appear in the marketplace once discovered and ingested.

Discovery runs every 30 minutes. 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.

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 hooks or MCP servers with safety considerations

For complete marketplace schema and examples, see the 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

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 30 minutes. No submission forms, no waiting for approval - just push and ship.

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

{ "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" } } } }

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, skills, 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.

Skill Example (skills/api-integration/SKILL.md)

---
description: Interact with REST APIs
---

Expert in making HTTP requests and handling API responses.
Claude will automatically use this when API interaction is needed.

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 30 minutes. Your plugin will appear in the marketplace once discovered and ingested.

Discovery runs every 30 minutes. 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

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 hooks or MCP servers with safety considerations

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