Creating an Api generator plugin for Claude Code

Claude Code plugins allow you to extend the capabilities of your AI assistant with custom commands, specialized agents, and tool integrations. In 3 minutes, create your first functional plugin. Read the full Docs

Why create plugins?

Intelligent Automation: Transform your repetitive workflows into reusable slash commands. A simple /deploy prod can orchestrate tests, build, and deployment.
Standardized Team Tooling: Share your best practices via automatically installed plugins. Your team uses the same code conventions, deployment scripts, and integrations.
Limitless Extensibility: Connect Claude to your existing tools (databases, APIs, internal services) via MCP, create specialized agents for your business domains, and trigger automatic actions with hooks.

Prerequisites

Claude Code installed on your machine
Basic command line knowledge
Understanding the Plugin Architecture
A Claude Code plugin follows a simple modular pattern:

api-generator-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── commands/                 # Custom slash commands
├── agents/                   # Specialized agents (optional)
├── hooks/                    # Automations (optional)
└── .mcp.json                # External integrations (optional)

Creating an API Generator Plugin in 5 Steps

We will create a practical plugin that generates a complete REST API from a simple description.

1. Create the marketplace structure

mkdir -p ~/claude-marketplace/plugins
cd ~/claude-marketplace/plugins
mkdir api-generator-plugin
cd api-generator-plugin

2. Create the plugin manifest

Create .claude-plugin/plugin.json:

{
  "name": "api-generator-plugin",
  "version": "1.0.0",
  "description": "Generates complete REST APIs with models, routes, and controllers"
}

3. Add the API generation command

Create commands/api-generate.md:

---
description: "Generates a complete REST API for an entity"
args:
  - name: entity
    description: "Name of the entity (ex. User, Product, Post)"
    required: true
  - name: fields
    description: "Comma-separated fields (ex. name:string,email:string,age:number)"
    required: true
  - name: framework
    description: "Framework to use (express, fastify, nestjs)"
    required: false
    default: express
---

# API Generation for the {{entity}} Entity

I will create a complete REST API with the following components:

## 📁 Generated Structure

src/
├── models/{{entity}}.model.js
├── controllers/{{entity}}.controller.js
├── routes/{{entity}}.routes.js
└── validators/{{entity}}.validator.js

## 📝 Detected Fields

{{fields}}

## 🔧 Generation Instructions

Create the following files, respecting {{framework}} conventions:

### 1. Data Model (`models/{{entity}}.model.js`)
- Define the schema with fields: {{fields}}
- Add timestamps (createdAt, updatedAt)
- Validate data types

### 2. Controller (`controllers/{{entity}}.controller.js`)
Implement these methods:
- `getAll{{entity}}s`: GET - Paginated list
- `get{{entity}}ById`: GET - Single item by ID
- `create{{entity}}`: POST - Create an item
- `update{{entity}}`: PUT - Update
- `delete{{entity}}`: DELETE - Delete

Handle errors with try/catch and return appropriate HTTP codes.

### 3. Routes (`routes/{{entity}}.routes.js`)
Create these endpoints:

GET /api/{{entity}}s
GET /api/{{entity}}s/:id
POST /api/{{entity}}s
PUT /api/{{entity}}s/:id
DELETE /api/{{entity}}s/:id

### 4. Validators (`validators/{{entity}}.validator.js`)
Validate the fields: {{fields}}
- Correct data types
- Required fields
- Business constraints

## ✅ After Generation

1. Import the routes into `app.js`:
```

javascript
const {{entity}}Routes = require('./routes/{{entity}}.routes');
app.use('/api', {{entity}}Routes);

1. Test the endpoints with curl or Postman
2. Document the API with Swagger (optional)

Now generate the 4 complete files with production-ready code.

Key Pattern: This command uses complex templates with structured instructions to guide Claude in code generation.

4. Add a command for a unique endpoint

Create commands/api-endpoint.md:

`markdown
---
description: Adds a custom endpoint to an existing API
args:
  - name: entity
    description: Name of the entity concerned
    required: true
  - name: method
    description: HTTP Method (GET, POST, PUT, DELETE, PATCH)
    required: true
  - name: endpoint
    description: Endpoint path (ex. /search, /export)
    required: true
  - name: description
    description: Description of what the endpoint does
    required: true
---

# Adding a {{method}} {{endpoint}} endpoint for {{entity}}

## 📋 Specifications

**Entity**: {{entity}}
**Method**: {{method}}
**Endpoint**: `/api/{{entity}}s{{endpoint}}`
**Function**: {{description}}

## 🔧 Generation

Add this new endpoint to the existing file:

1. **Controller** (`controllers/{{entity}}.controller.js`):
   - Create the method that implements: {{description}}
   - Handle errors and validations
   - Return an appropriate JSON response

2. **Route** (`routes/{{entity}}.routes.js`):
   - Add: `router.{{method}}('{{endpoint}}', controller.methodName);`

3. **Suggested Tests**:
```bash
curl -X {{method}} http://localhost:3000/api/{{entity}}s{{endpoint}}
````

Generate the complete code for this endpoint.

**5. Configure the local marketplace**

At the root `~/claude-marketplace/`, create `marketplace.json`:

```json
{
  "name": "My Local Marketplace",
  "plugins": [
    {
      "source": "./plugins/api-generator-plugin"
    }
  ]
}
```

**6. Install and Test**

```bash
# Add your local marketplace
claude marketplace add file://~/claude-marketplace

# Install your plugin
claude marketplace install api-generator-plugin

# Test API generation
/api-generate User "name:string,email:string,age:number" express

# Add a search endpoint
/api-endpoint User GET /search "Search users by name or email"
```

Check your new commands with `/help`.

**Concrete Usage Example**

```bash
# Generate a complete API for a blog
/api-generate Post "title:string,content:text,authorId:number,published:boolean" express

# Add a publication endpoint
/api-endpoint Post PATCH /publish "Publish a blog post"

# Generate an e-commerce API
/api-generate Product "name:string,price:number,stock:number,category:string" fastify
```

**Design Concepts**

**Naming Convention**

  * Plugins: kebab-case (`api-generator-plugin`)
  * Commands: action verbs (`/api-generate`, `/api-endpoint`)
  * Variables: double curly braces (`{{entity}}`, `{{fields}}`)

**Structured Instruction Pattern**
Complex commands use markdown sections to guide Claude:

  * Clear instructions: Numbered steps
  * Code examples: Concrete snippets
  * Checklist: Post-generation actions

**Organization for Advanced Plugins**

```
advanced-api-plugin/
├── commands/
│   ├── generate/
│   │   ├── api-generate.md
│   │   └── api-crud.md
│   ├── enhance/
│   │   ├── api-auth.md
│   │   └── api-cache.md
│   └── deploy/
│       └── api-deploy.md
├── agents/
│   └── api-architect.json
└── hooks/
    └── hooks.json
```

**Advanced Components**

**Specialized Agents**

Create `agents/api-architect.json`:

```json
{
  "name": "api-architect",
  "instructions": "You are an expert API architect. You analyze needs, propose RESTful patterns, optimize performance, and ensure scalability. You are proficient in Express, Fastify, NestJS, and security best practices.",
  "model": "claude-sonnet-4-5"
}
```

Use the agent: `/agents` then select "api-architect"

**Automation Hooks**

Create `hooks/hooks.json`:

```json
{
  "pre-commit": "commands/api-lint.md",
  "post-generate": "commands/api-test-setup.md"
}
```

**MCP Integration (Databases)**

Create `.mcp.json` to connect your plugin to a database:

```json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}
```

**Sharing and Deployment**

**For your Team**

Add to the repository's `.claude/settings.json`:

```json
{
  "marketplaces": [
    "file://./team-plugins"
  ],
  "plugins": [
    "api-generator-plugin"
  ]
}
```

Members automatically install the plugin by trusting the folder.

**Best Practices**

  * **Version**: Semantic versioning (1.0.0 → 1.1.0 → 2.0.0)
  * **Document**: `README.md` with usage examples
  * **Test**: Validate each command with real cases
  * **Iterate**: Add features progressively

**Quick Debugging**

Common Issues:

  * Plugin not recognized → Check that `commands/` is at the plugin root
  * Variables not replaced → Use `{{variable}}` with double curly braces
  * Command invisible → Validate the YAML frontmatter (3 dashes, correct syntax)
  * Installation errors → `claude marketplace validate file://~/claude-marketplace`

**Next Steps**

  * **Explore Marketplaces**: Get inspiration from community plugins
  * **Create Agents**: Specialize Claude for your domains (DevOps, Data, Security)
  * **Automate with Hooks**: Pre-commit checks, post-deploy notifications
  * **Integrate Your Tools**: Connect Jira, GitHub, Slack via MCP
  * **Share**: Contribute to the Claude Code ecosystem