Build Custom Claude Code Plugins: A Complete Step‑by‑Step Guide

Understanding Claude Code Plugins

Claude Code, Anthropic's AI programming assistant, already supports code understanding, generation, and editing. Plugins let you tailor its behavior with custom slash commands, dedicated agents, and automated hooks, making the tool fit personal or team workflows.

Why Use Plugins?

Plugins are useful when you need configuration that applies only to a single project, experimental commands, or temporary settings that you don’t want to share globally.

Project‑specific custom functions

Personal experimental commands or agents

Temporary configurations that aren’t shared

Plugins also bring benefits such as team sharing, version control, cross‑project reuse, and namespace isolation to avoid command conflicts.

Creating Your First Plugin

Directory Structure

Start by creating a folder for the plugin: mkdir my-first-plugin The essential directories are: .claude-plugin/ – contains plugin.json (metadata) commands/ – slash command definitions agents/ – optional custom agents skills/ – optional reusable skill modules hooks/ – event‑trigger definitions

Plugin Manifest

Create .claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A simple plugin for learning",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

First Slash Command

Make the commands folder and add hello.md:

---
description: Send a friendly greeting
---
# Hello Command

向用户热情地问候，并询问今天可以帮他们做什么。

Test locally with: claude --plugin-dir ./my-first-plugin Run the command inside Claude Code: /my-first-plugin:hello The plugin namespace (the name field) prefixes the command, preventing conflicts. To change the prefix, edit plugin.json and modify the name value.

Making the Command Accept Arguments

Update hello.md to use $ARGUMENTS:

---
description: 向用户发送友好的问候
---
# Hello Command

向名叫 "$ARGUMENTS" 的用户热情问候，并询问今天可以帮他们做什么。

Now /my-first-plugin:hello 小明 greets "小明".

Plugin Capabilities

Custom Slash Commands – e.g., /my-plugin:deploy for one‑click deployment.

Dedicated Agents – define domain‑specific AI agents such as a "frontend optimizer".

Hooks System – run tasks automatically on events (e.g., format on file save).

Skills Extension – add professional skills like automatic API documentation.

MCP Integration – connect external tools via Model Context Protocol.

LSP Integration – provide real‑time language‑server support.

Advanced Slash Command Example

---
description: Deploy application to a specified environment
---
# 部署命令

准备将应用部署到 $1 环境。
使用配置文件：$ARGUMENTS

执行步骤：
1. 检查环境状态
2. 构建应用
3. 部署到 $1
4. 验证部署结果

Parameter shortcuts: $1, $2 – positional arguments $ARGUMENTS – all remaining arguments $FILE – current file path (specific scenarios)

Agent Development

Agents are AI entities with their own system prompts and tool access. Example agents/api-expert.md defines a REST‑API design expert:

---
name: api-expert
description: REST API 设计和最佳实践专家
---
你是一名经验丰富的 API 架构师，专门设计生产级 REST API。

你的专业包括：
- RESTful 设计原则（正确的 HTTP 方法、状态码、资源命名）
- API 安全（OAuth、JWT、速率限制、输入验证）
- 性能（缓存、分页、压缩、异步模式）
- 文档（带示例的 OpenAPI/Swagger 规范）

帮助设计 API 时：
1. 在建议方案前先澄清需求
2. 设计直观、可预测的 REST 端点
3. 提供有用的错误消息和处理
4. 考虑版本控制和向后兼容
5. 用用户熟悉的语言/框架提供示例代码

Agents keep conversation context and are suited for multi‑step tasks.

Hooks Configuration

Hooks react to events. Create hooks/hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Common event types include PreToolUse, PostToolUse, Notification, and Stop. Hook actions can be command, function, or url.

MCP Server Integration

Define external tool servers in .mcp.json (example shows a database server and an npm‑based API client):

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": { "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data" }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

When the plugin loads, the MCP servers start automatically and become available to commands, agents, and skills.

LSP Server Integration

Configure language‑server support in .lsp.json (Go example):

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": { ".go": "go" }
  }
}

This enables real‑time code intelligence for supported languages.

Advanced Plugin Development

Skill Development

Skills are auto‑triggered professional capabilities. Example skills/code-review/SKILL.md:

---
name: code-review
description: 审查代码的最佳实践和潜在问题。在审查代码、检查 PR 或分析代码质量时使用。
---
审查代码时，请检查：
1. 代码组织和结构
2. 错误处理机制
3. 安全考虑因素
4. 测试覆盖率
5. 性能影响

提供具体、可操作的改进建议。

Claude decides when to invoke a skill based on context, without explicit user calls.

Complex Plugin Organization

When a plugin grows, keep a clear hierarchy (commands, agents, skills, hooks, MCP, LSP) and follow naming conventions to avoid deep nesting.

Local Testing and Debugging

Use the --plugin-dir flag to load a plugin without installing it: claude --plugin-dir ./my-plugin After changes, restart Claude Code and verify:

Run /插件名:命令名 to test commands.

Use /agents to confirm agents are loaded.

Trigger events to check hooks.

For multiple plugins, specify the flag repeatedly:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Sharing Plugins

When the plugin is stable, add a README.md, follow semantic versioning in plugin.json, and distribute via the plugin marketplace or an internal repository.

Migrating Existing .claude Configurations to Plugins

If you already have custom configurations under .claude/, migrate them to a plugin to gain sharing and version control.

When to Migrate

Configuration needed across multiple projects.

Team members want to share the same custom functions.

Stable configuration that should be versioned.

Planning to publish the extension.

Migration Steps

Create a plugin skeleton ( my-plugin/.claude-plugin/plugin.json).

Copy existing .claude/commands, .claude/agents, and .claude/skills into the new plugin directories.

Extract any hook definitions from settings.json into my-plugin/hooks/hooks.json.

Test the migrated plugin with claude --plugin-dir ./my-plugin and verify each component.

After successful migration, delete the old .claude/ files to avoid duplicate loading.

Conclusion

Claude Code plugins provide a reusable, customizable, and shareable workflow layer. Whether you use community plugins or build internal ones, the system can dramatically improve development efficiency and consistency.

Reference resources:

Claude Code Plugins – official documentation

Plugin Marketplaces – how to publish and install plugins

MCP Documentation – Model Context Protocol details