How to Build Your Own Claude Code Plugin

So Claude Code got plugins last week. The announcements make it sound like you can customize everything now - slash commands, agents, workflows, the whole deal.

And yeah, you can. But here’s what nobody tells you: building a plugin that people actually want to use is different from building one that technically works.

I spent the last few days building plugins, breaking them, and figuring out what makes them actually useful vs. just another thing clogging up your .claude/plugins directory.

This is the practical guide I wish I had when I started.

---

What Actually is a Claude Code Plugin?

A plugin is basically a git repo that lives in ~/.claude/plugins/ and tells Claude about custom commands, agents, or MCP servers you want available.

The structure looks like this:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Plugin metadata
├── commands/
│   └── hello.md          # Custom slash command
├── agents/
│   └── helper.md         # Subagent definition
└── hooks/
    └── hooks.json        # Workflow hooks

The key insight: Everything is just markdown files with frontmatter. No complex APIs, no build process. Just write markdown and Claude understands it.

---

Your First Plugin in 5 Minutes

Let’s build something simple but useful: a plugin that reviews code for common bugs.

Step 1: Create the Structure

mkdir code-reviewer
cd code-reviewer
mkdir -p .claude-plugin commands

Step 2: Add Plugin Metadata

cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "code-reviewer",
  "description": "Reviews code for bugs and improvements",
  "version": "1.0.0",
  "author": {"name": "Your Name"},
  "commands": ["./commands/review.md"]
}
EOF

Step 3: Create the Command

cat > commands/review.md << 'EOF'
---
name: review
description: Review current file for bugs and improvements
---

Analyze the current file for:
- Potential bugs and edge cases
- Performance issues
- Security vulnerabilities
- Code style improvements

Be specific. Cite line numbers. Suggest fixes with code examples.
EOF

Step 4: Test It

Create a local marketplace for testing:

cd ~
mkdir dev-marketplace
cd dev-marketplace
mkdir .claude-plugin

cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "dev",
  "owner": {"name": "Me"},
  "plugins": [{
    "name": "code-reviewer",
    "source": "../code-reviewer",
    "description": "Code review plugin"
  }]
}
EOF

Now in Claude Code:

/plugin marketplace add ~/dev-marketplace
/plugin install code-reviewer@dev
/review

Pro tip: Keep your dev-marketplace around. You can add unlimited plugins to it for testing without cluttering the official marketplaces.

---

Making Commands Actually Useful

The difference between a meh plugin and a great one is specificity.

Bad Command

---
name: test
description: Write tests
---

Write tests for the current file.

Good Command

---
name: test
description: Generate unit tests with edge cases and mocks
---

Generate comprehensive unit tests for the current file:

1. **Happy path** - Test expected behavior with valid inputs
2. **Edge cases** - Empty strings, nulls, boundary values, special characters
3. **Error cases** - Invalid inputs, network failures, permission errors
4. **Mocks** - Mock external dependencies (APIs, database, file system)

Use Jest for JavaScript/TypeScript or pytest for Python.
Include setup/teardown as needed.
Aim for 80%+ code coverage.

The more context you give Claude, the better results you get.

---

Building an Agent (Not Just a Command)

Commands are one-shot. Agents are for back-and-forth conversations.

Let’s build an API design expert:

mkdir agents
cat > agents/api-expert.md << 'EOF'
---
name: api-expert
description: Expert in REST API design and best practices
---

You are an experienced API architect who specializes in designing production-grade REST APIs.

Your expertise includes:
- RESTful design principles (proper HTTP methods, status codes, resource naming)
- API security (OAuth, JWT, rate limiting, input validation)
- Performance (caching, pagination, compression, async patterns)
- Documentation (OpenAPI/Swagger specs with examples)

When helping with APIs:
1. Ask clarifying questions about requirements before suggesting solutions
2. Design intuitive, predictable endpoints that follow REST conventions
3. Include error handling with helpful error messages
4. Consider versioning and backwards compatability
5. Provide code examples in the user's language/framework

Be thorough but practical. Focus on solutions that work in production.
EOF

Update plugin.json:

{
  "name": "code-reviewer",
  "description": "Code review and API design tools",
  "version": "1.0.0",
  "author": {"name": "Your Name"},
  "commands": ["./commands/review.md"],
  "agents": ["./agents/api-expert.md"]
}

Now you can invoke it:

@api-expert Help me design an authentication API with JWT tokens

The agent will ask questions, suggest approaches, and help you iterate on the design.

---

Real-World Example: API Generator Plugin

Let’s build something you’d actually use every day.

mkdir api-generator
cd api-generator
mkdir -p .claude-plugin commands agents

Plugin manifest:

{
  "name": "api-generator",
  "description": "Generate complete API endpoints with tests and docs",
  "version": "1.0.0",
  "author": {"name": "Your Team"},
  "commands": ["./commands/generate-api.md"],
  "agents": ["./agents/api-architect.md"]
}

Command:

---
name: generate-api
description: Generate REST endpoint with validation, tests, and docs
---

Generate a production-ready REST API endpoint including:

1. **Route handler** - Express.js or FastAPI route with proper HTTP method
2. **Validation** - Input validation using Zod (TS) or Pydantic (Python)
3. **Error handling** - Proper status codes and error messages
4. **Tests** - Unit tests with Jest or pytest
5. **Documentation** - OpenAPI spec with request/response examples

Ask the user:
- HTTP method (GET, POST, PUT, DELETE)
- Endpoint path (eg /api/users/:id)
- Request/response schema
- Auth requirements

Follow REST best practices. Use async/await. Include comments.

Agent:

---
name: api-architect
description: Expert at designing scalable REST APIs
---

You are a senior backend engineer specializing in API design.

Focus areas:
- Clean architecture (separation of concerns, dependency injection)
- Performance (database query optimization, caching strategies)
- Security (auth, input sanitization, rate limiting)
- Testing (unit, integration, e2e test strategies)

When generating APIs:
1. Use the project's existing patterns and conventions
2. Add TODO comments for things users should customize
3. Include error handling for common failure modes
4. Write tests that cover edge cases
5. Add inline documentation for complex logic

Always ask "what could go wrong?" and handle those cases.

This kind of plugin can save you 30+ minutes per endpoint.

---

Team Plugins: Share Across Your Org

Once you’ve built something useful, share it with your team.

Option 1: Team Marketplace

Create a repo called claude-plugins in your org:

claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── api-generator/
├── test-writer/
└── code-reviewer/

marketplace.json:

{
  "name": "acme-tools",
  "owner": {"name": "ACME Corp"},
  "plugins": [
    {
      "name": "api-generator",
      "source": "./api-generator",
      "description": "Generate REST endpoints with tests"
    },
    {
      "name": "test-writer",
      "source": "./test-writer",
      "description": "Generate comprehensive test suites"
    }
  ]
}

Team members add it once:

/plugin marketplace add github.com/acme/claude-plugins
/plugin install api-generator@acme-tools

Option 2: Project-Level Auto-Install

Even better - add plugins automatically when someone opens your repo.

In your project root, create .claude/settings.json:

{
  "marketplaces": [
    {
      "name": "team",
      "source": "github.com/acme/claude-plugins"
    }
  ],
  "plugins": [
    "api-generator@team",
    "test-writer@team"
  ]
}

Now when anyone opens the project, the plugins install automatically. No setup required.

Why this matters: Your whole team uses the same code generation, testing, and review workflows. No more “works on my machine” for tooling.

---

Common Mistakes (And How to Avoid Them)

Mistake 1: Commands That Are Too Vague

<!-- Bad -->
Analyze the code

<!-- Good -->
Analyze for memory leaks, race conditions, and improper error handling.
Check async/await usage. Look for unhandled promise rejections.

Mistake 2: Not Testing Edge Cases

Test your plugin on:

• Large files (1000+ lines)
• Files with syntax errors
• Binary files
• Empty files

Your commands should handle these gracefully.

Mistake 3: Forgetting About Token Limits

Claude has a context window limit. Every plugin adds to that.

Rule of thumb:

• Commands: < 200 tokens
• Agents: < 500 tokens
• Test with /mcp list to see total context usage

Mistake 4: No Error Handling

---
name: deploy
description: Deploy to production
---

Before deploying:
1. Verify tests pass (run `npm test`)
2. Check environment variables are set
3. Confirm current branch is `main`
4. **Ask user for explicit confirmation**

If any check fails, explain what's wrong and how to fix it.
Never deploy without confirmation.

Safety first.

---

Plugin Analytics: Know What Works

Here’s the thing nobody talks about: you have no idea if your plugins are actually useful.

You build them, share them, and… then what? Are people using them? Which commands get invoked? Which ones just sit there taking up space?

At Agnost AI, we track MCP and plugin usage so you can see what’s actually being used vs. what’s just installed. One team discovered 80% of their usage came from just 3 plugins out of 18 installed.

They removed the rest. Claude got faster. People were happier.

---

Quick Reference: Plugin Files

plugin.json

{
  "name": "my-plugin",
  "description": "What it does",
  "version": "1.0.0",
  "author": {"name": "You"},
  "commands": ["./commands/cmd.md"],
  "agents": ["./agents/agent.md"],
  "hooks": ["./hooks/hooks.json"]
}

Command template

---
name: command-name
description: What it does in one line
---

Detailed instructions for Claude.
Be specific. Include examples.

Agent template

---
name: agent-name
description: Agent expertise area
---

You are an expert in [domain].

Your approach:
1. First principle
2. Second principle

When helping users:
- Do this
- Not that

marketplace.json

{
  "name": "marketplace-name",
  "owner": {"name": "Your Org"},
  "plugins": [{
    "name": "plugin-name",
    "source": "./plugin-directory",
    "description": "What it does"
  }]
}

---

The Bottom Line

Building Claude Code plugins is surprisingly straightforward. The hard part isn’t the technical setup - it’s designing commands and agents that are actually useful.

Keys to success:

• Be specific in your instructions
• Test on real code, not just toy examples
• Share with your team via project-level configs
• Monitor what people actually use

The plugin ecosystem is brand new. There’s a ton of opportunity to build tools that become standard across teams. The plugins that win will be the ones that save real time on real tasks.

---

Resources

Official Docs:

• Claude Code Plugins Reference
• Plugin Marketplaces Guide
• MCP Documentation

Community:

• Claude Code Plugin Directory
• GitHub: claude-code-plugins

Related Posts:

• Testing MCP Servers: The Complete Developer’s Guide
• How to Get More Usage on Your MCP Server

---

Want to track which plugins your team actually uses? Check out Agnost AI for real-time analytics on your MCP servers and plugins. See what works, what doesn’t, and optimize your tooling based on actual data.