creating-a-plugin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating a Plugin

创建插件

Overview

概述

A Claude Code plugin packages reusable components (commands, agents, skills, hooks, MCP servers) for distribution. Create a plugin when you have components that work across multiple projects.

Don't create a plugin for:

Project-specific configurations (use
```
.claude/
```
in project root)
One-off scripts or commands
Experimental features still in development

Plugin storage locations:

Development: Anywhere during development, installed via
```
file:///
```
path
User-level:
```
~/.claude/plugins/
```
(after installation)
Project-level:
```
.claude/plugins/
```
(project-specific installations)

Claude Code插件用于打包可复用组件（commands、agents、skills、hooks、MCP服务器）以供分发。当你拥有可跨多个项目使用的组件时，就可以创建插件。

无需创建插件的场景：

项目特定配置（在项目根目录使用
```
.claude/
```
）
一次性脚本或命令
仍在开发中的实验性功能

插件存储位置：

开发阶段：开发期间可存放在任意位置，通过
```
file:///
```
路径安装
用户级：
```
~/.claude/plugins/
```
（安装后）
项目级：
```
.claude/plugins/
```
（项目专属安装）

Quick Start Checklist

快速入门清单

Minimal viable plugin:

Create directory:
```
my-plugin/
```

Create

.claude-plugin/plugin.json

with at minimum:

json

{
  "name": "my-plugin"
}

Add components (commands, agents, skills, hooks, or MCP servers)

Test locally:

/plugin install file:///absolute/path/to/my-plugin

Reload:
```
/plugin reload
```

最小可用插件：

创建目录：
```
my-plugin/
```

创建

.claude-plugin/plugin.json

，至少包含以下内容：

json

{
  "name": "my-plugin"
}

添加组件（commands、agents、skills、hooks或MCP服务器）

本地测试：

/plugin install file:///absolute/path/to/my-plugin

重新加载：
```
/plugin reload
```

Directory Structure

目录结构

my-plugin/
�� .claude-plugin/
   �� plugin.json              # Required: plugin manifest
�� commands/                    # Optional: slash commands
   �� my-command.md
�� agents/                      # Optional: specialized subagents
   �� my-agent.md
�� skills/                      # Optional: reusable techniques
   �� my-skill/
       �� SKILL.md
�� hooks/                       # Optional: event handlers
   �� hooks.json
�� .mcp.json                    # Optional: MCP server configs
�� README.md                    # Recommended: documentation

Critical: The

.claude-plugin/

directory with

plugin.json

inside must exist at plugin root.

my-plugin/
�� .claude-plugin/
   �� plugin.json              # 必填：插件清单
�� commands/                    # 可选：斜杠命令
   �� my-command.md
�� agents/                      # 可选：专用子代理
   �� my-agent.md
�� skills/                      # 可选：可复用技术
   �� my-skill/
       �� SKILL.md
�� hooks/                       # 可选：事件处理器
   �� hooks.json
�� .mcp.json                    # 可选：MCP服务器配置
�� README.md                    # 推荐：文档

关键要求： 插件根目录必须存在包含

plugin.json

的

.claude-plugin/

目录。

Component Reference

组件参考

Component	Location	File Format	When to Use
Commands	`commands/*.md`	Markdown + YAML frontmatter	Custom slash commands for repetitive tasks
Agents	`agents/*.md`	Markdown + YAML frontmatter	Specialized subagents for complex workflows
Skills	`skills/*/SKILL.md`	Markdown + YAML frontmatter	Reusable techniques and patterns
Hooks	`hooks/hooks.json`	JSON	Event handlers (format code, validate, etc.)
MCP Servers	`.mcp.json`	JSON	External tool integrations

组件	位置	文件格式	使用场景
Commands	`commands/*.md`	Markdown + YAML前置元数据	用于重复任务的自定义斜杠命令
Agents	`agents/*.md`	Markdown + YAML前置元数据	用于复杂工作流的专用子代理
Skills	`skills/*/SKILL.md`	Markdown + YAML前置元数据	可复用技术和模式
Hooks	`hooks/hooks.json`	JSON	事件处理器（格式化代码、验证等）
MCP服务器	`.mcp.json`	JSON	外部工具集成

plugin.json Format

plugin.json格式

Minimal valid manifest:

json

{
  "name": "my-plugin"
}

Complete annotated manifest:

json

{
  "name": "my-plugin",                    // Required: kebab-case identifier
  "version": "1.0.0",                     // Recommended: semantic versioning
  "description": "What this plugin does", // Recommended: brief description

  "author": {                             // Optional but recommended
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },

  "homepage": "https://github.com/yourname/my-plugin",
  "repository": "https://github.com/yourname/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "automation"],

  "commands": [                           // Optional: explicit command paths
    "./commands/cmd1.md",
    "./commands/cmd2.md"
  ],

  "agents": [                             // Optional: explicit agent paths
    "./agents/agent1.md"
  ],

  "hooks": [                              // Optional: inline hooks
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
    }
  ],

  "mcpServers": {                         // Optional: inline MCP configs
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--port", "8080"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Key points:

```
name
```
is required, everything else is optional
Use
```
${CLAUDE_PLUGIN_ROOT}
```
to reference plugin directory
Commands/agents auto-discovered from
```
commands/
```
and
```
agents/
```
directories if not listed explicitly
Skills auto-discovered from
```
skills/*/SKILL.md
```
pattern

最小有效清单：

json

{
  "name": "my-plugin"
}

完整带注释的清单：

json

{
  "name": "my-plugin",                    // 必填：短横线命名标识符
  "version": "1.0.0",                     // 推荐：语义化版本
  "description": "What this plugin does", // 推荐：简短描述

  "author": {                             // 可选但推荐
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },

  "homepage": "https://github.com/yourname/my-plugin",
  "repository": "https://github.com/yourname/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "automation"],

  "commands": [                           // 可选：显式命令路径
    "./commands/cmd1.md",
    "./commands/cmd2.md"
  ],

  "agents": [                             // 可选：显式代理路径
    "./agents/agent1.md"
  ],

  "hooks": [                              // 可选：内联钩子
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
    }
  ],

  "mcpServers": {                         // 可选：内联MCP配置
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--port", "8080"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

要点：

```
name
```
为必填项，其余为可选
使用
```
${CLAUDE_PLUGIN_ROOT}
```
引用插件目录
如果未显式列出，commands/agents会自动从
```
commands/
```
和
```
agents/
```
目录中发现
Skills会自动从
```
skills/*/SKILL.md
```
模式中发现

Creating Commands

创建Commands

File location:

commands/my-command.md

creates

/my-command

slash command

Nested commands:

commands/feature/sub-command.md

creates

/plugin-name:feature:sub-command

Template:

markdown

---
description: Brief description of what this command does
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
argument-hint: "[file-path]"
---

文件位置：

commands/my-command.md

会创建

/my-command

斜杠命令

嵌套命令：

commands/feature/sub-command.md

会创建

/plugin-name:feature:sub-command

模板：

markdown

---
description: Brief description of what this command does
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
argument-hint: "[file-path]"
---

Command Name

Your command prompt goes here.

You can use:

$1, $2, etc. for positional arguments
$ARGUMENTS for all arguments as single string
@filename to include file contents
!bash command to execute shell commands

Example implementation instructions...


**Frontmatter fields:**
- `description` - Brief description shown in `/help`
- `allowed-tools` - Comma-separated list: `Read, Grep, Glob, Bash, Edit, Write, TodoWrite, Task`
- `model` - Optional: `haiku`, `sonnet`, or `opus` (defaults to user's setting)
- `argument-hint` - Optional: shown in help text
- `disable-model-invocation` - Optional: `true` to prevent auto-run

**Complete example** (`commands/review-pr.md`):
```markdown
---
description: Review pull request for security and best practices
allowed-tools: Read, Grep, Glob, Bash
model: opus
argument-hint: "[pr-number]"
---

Your command prompt goes here.

You can use:

$1, $2, etc. for positional arguments
$ARGUMENTS for all arguments as single string
@filename to include file contents
!bash command to execute shell commands

Example implementation instructions...


**前置元数据字段：**
- `description` - 简短描述，显示在`/help`中
- `allowed-tools` - 逗号分隔列表：`Read, Grep, Glob, Bash, Edit, Write, TodoWrite, Task`
- `model` - 可选：`haiku`, `sonnet`, 或`opus`（默认使用用户设置）
- `argument-hint` - 可选：显示在帮助文本中
- `disable-model-invocation` - 可选：设为`true`可阻止自动运行

**完整示例** (`commands/review-pr.md`):
```markdown
---
description: Review pull request for security and best practices
allowed-tools: Read, Grep, Glob, Bash
model: opus
argument-hint: "[pr-number]"
---

Pull Request Review

Review pull request #$1 for:

Security vulnerabilities
Performance issues
Best practices compliance
Error handling

Steps:

Use Bash to run: gh pr diff $1
Use Read to examine changed files
Use Grep to search for common anti-patterns
Provide structured feedback with file:line references

Focus on critical issues first.

undefined

Review pull request #$1 for:

Security vulnerabilities
Performance issues
Best practices compliance
Error handling

Steps:

Use Bash to run: gh pr diff $1
Use Read to examine changed files
Use Grep to search for common anti-patterns
Provide structured feedback with file:line references

Focus on critical issues first.

undefined

Creating Agents

创建Agents

File location:

agents/code-reviewer.md

creates agent named "code-reviewer"

Template:

markdown

---
name: agent-name
description: When and why to use this agent (critical for auto-delegation)
tools: Read, Edit, Write, Grep, Glob, Bash
model: opus
---

文件位置：

agents/code-reviewer.md

会创建名为"code-reviewer"的代理

模板：

markdown

---
name: agent-name
description: When and why to use this agent (critical for auto-delegation)
tools: Read, Edit, Write, Grep, Glob, Bash
model: opus
---

Agent Name

Detailed instructions and system prompt for this agent.

Responsibilities

Task 1
Task 2

Task 1
Task 2

Tools Available

Read: File operations
Grep: Code search
Bash: Shell commands

Read: File operations
Grep: Code search
Bash: Shell commands

Workflow

Step 1
Step 2


**Frontmatter fields:**
- `name` - Required: kebab-case identifier
- `description` - Required: Max 1024 chars, used for auto-delegation
- `tools` - Comma-separated list of allowed tools
- `model` - Optional: `haiku`, `sonnet`, or `opus`

**Complete example** (`agents/security-auditor.md`):
```markdown
---
name: security-auditor
description: Use when reviewing code for security vulnerabilities, analyzing authentication flows, or checking for common security anti-patterns like SQL injection, XSS, or insecure dependencies
tools: Read, Grep, Glob, Bash
model: opus
---

Step 1
Step 2


**前置元数据字段：**
- `name` - 必填：短横线命名标识符
- `description` - 必填：最多1024字符，用于自动委托
- `tools` - 逗号分隔的允许工具列表
- `model` - 可选：`haiku`, `sonnet`, 或`opus`

**完整示例** (`agents/security-auditor.md`):
```markdown
---
name: security-auditor
description: Use when reviewing code for security vulnerabilities, analyzing authentication flows, or checking for common security anti-patterns like SQL injection, XSS, or insecure dependencies
tools: Read, Grep, Glob, Bash
model: opus
---

Security Auditor Agent

You are a security expert specializing in web application security and secure coding practices.

Your Responsibilities

Identify security vulnerabilities (SQL injection, XSS, CSRF, etc.)
Review authentication and authorization logic
Check for insecure dependencies
Verify input validation and sanitization
Review cryptographic implementations

Identify security vulnerabilities (SQL injection, XSS, CSRF, etc.)
Review authentication and authorization logic
Check for insecure dependencies
Verify input validation and sanitization
Review cryptographic implementations

Workflow

Scan for patterns: Use Grep to find common vulnerability patterns
Read suspicious code: Use Read to examine flagged files
Check dependencies: Use Bash to run security audit tools
Report findings: Provide severity ratings and remediation steps

Scan for patterns: Use Grep to find common vulnerability patterns
Read suspicious code: Use Read to examine flagged files
Check dependencies: Use Bash to run security audit tools
Report findings: Provide severity ratings and remediation steps

Common Vulnerability Patterns

SQL injection: String concatenation in queries
XSS: Unescaped user input in templates
CSRF: Missing CSRF tokens
Auth bypass: Missing authorization checks
Hardcoded secrets: API keys, passwords in code

SQL injection: String concatenation in queries
XSS: Unescaped user input in templates
CSRF: Missing CSRF tokens
Auth bypass: Missing authorization checks
Hardcoded secrets: API keys, passwords in code

Reporting Format

For each finding:

Severity: Critical/High/Medium/Low
Location:
```
file:line
```
Issue: What's vulnerable
Impact: What attacker could do
Fix: How to remediate

undefined

For each finding:

Severity: Critical/High/Medium/Low
Location:
```
file:line
```
Issue: What's vulnerable
Impact: What attacker could do
Fix: How to remediate

undefined

Creating Skills

创建Skills

REQUIRED SUB-SKILL: Use

writing-skills

for complete guidance on skill structure, testing, and deployment.

Skills follow a specific structure.

File location:

skills/my-skill/SKILL.md

Minimal template:

markdown

---
name: my-skill-name
description: Use when [specific triggers] - [what it does]
---

必填子技能： 使用

writing-skills

获取关于技能结构、测试和部署的完整指导。

Skills遵循特定结构。

文件位置：

skills/my-skill/SKILL.md

最小模板：

markdown

---
name: my-skill-name
description: Use when [specific triggers] - [what it does]
---

Skill Name

Overview

Core principle in 1-2 sentences.

When to Use

Symptom 1
Symptom 2
When NOT to use

Symptom 1
Symptom 2
When NOT to use

Quick Reference

[Table or bullets for common operations]

Implementation

[Code examples, patterns]

Common Mistakes

[What goes wrong + fixes]


**Key principles:**
- `name` uses only letters, numbers, hyphens (no special chars)
- `description` starts with "Use when..." in third person
- Keep token-efficient (<500 words if frequently loaded)
- One excellent example beats many mediocre ones
- Use `writing-skills` skill for complete guidance

[What goes wrong + fixes]


**关键原则：**
- `name`仅使用字母、数字、短横线（无特殊字符）
- `description`以"Use when..."开头，使用第三人称
- 保持token高效（如果频繁加载，控制在500词以内）
- 一个优秀的示例胜过多个平庸的示例
- 使用`writing-skills`技能获取完整指导

Creating Hooks

创建Hooks

File location:

hooks/hooks.json

or inline in

plugin.json

Standalone hooks file:

json

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Bash",
      "command": "echo 'About to run: $CLAUDE_TOOL_NAME'"
    },
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
    },
    {
      "event": "SessionStart",
      "matcher": "*",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"
    }
  ]
}

Hook events:

```
PreToolUse
```
- Before tool execution (can block)
```
PostToolUse
```
- After tool execution
```
UserPromptSubmit
```
- When user submits prompt
```
Stop
```
- When Claude finishes responding
```
SessionStart
```
- Session initialization
```
SessionEnd
```
- Session cleanup
```
Notification
```
- On Claude Code notifications
```
SubagentStop
```
- When subagent completes
```
PreCompact
```
- Before context compaction

Matcher patterns:

Specific tool:
```
"Bash"
```
Multiple tools:
```
"Edit|Write"
```
All tools:
```
"*"
```

Environment variables:

```
$CLAUDE_EVENT_TYPE
```
- Event type
```
$CLAUDE_TOOL_NAME
```
- Tool being used
```
$CLAUDE_TOOL_INPUT
```
- Tool input (JSON)
```
$CLAUDE_FILE_PATHS
```
- Space-separated file paths

文件位置：

hooks/hooks.json

或内联在

plugin.json

中

独立hooks文件：

json

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Bash",
      "command": "echo 'About to run: $CLAUDE_TOOL_NAME'"
    },
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
    },
    {
      "event": "SessionStart",
      "matcher": "*",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"
    }
  ]
}

Hook事件：

```
PreToolUse
```
- 工具执行前（可阻止）
```
PostToolUse
```
- 工具执行后
```
UserPromptSubmit
```
- 用户提交提示时
```
Stop
```
- Claude完成响应时
```
SessionStart
```
- 会话初始化
```
SessionEnd
```
- 会话清理
```
Notification
```
- 收到Claude Code通知时
```
SubagentStop
```
- 子代理完成时
```
PreCompact
```
- 上下文压缩前

匹配器模式：

特定工具：
```
"Bash"
```
多个工具：
```
"Edit|Write"
```
所有工具：
```
"*"
```

环境变量：

```
$CLAUDE_EVENT_TYPE
```
- 事件类型
```
$CLAUDE_TOOL_NAME
```
- 正在使用的工具
```
$CLAUDE_TOOL_INPUT
```
- 工具输入（JSON）
```
$CLAUDE_FILE_PATHS
```
- 空格分隔的文件路径

Creating MCP Server Configs

创建MCP服务器配置

File location:

.mcp.json

at plugin root or inline in

plugin.json

Standalone .mcp.json:

json

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}",
        "API_KEY": "${API_KEY:-default-key}"
      }
    },
    "web-scraper": {
      "command": "npx",
      "args": ["web-mcp-server", "--port", "3000"]
    }
  }
}

Configuration fields:

```
command
```
- Executable path or command name
```
args
```
- Array of arguments
```
env
```
- Environment variables (supports
```
${VAR}
```
or
```
${VAR:-default}
```
)

Special variable:

```
${CLAUDE_PLUGIN_ROOT}
```
- Resolves to plugin root directory

文件位置： 插件根目录的

.mcp.json

或内联在

plugin.json

中

独立.mcp.json：

json

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}",
        "API_KEY": "${API_KEY:-default-key}"
      }
    },
    "web-scraper": {
      "command": "npx",
      "args": ["web-mcp-server", "--port", "3000"]
    }
  }
}

配置字段：

```
command
```
- 可执行文件路径或命令名称
```
args
```
- 参数数组
```
env
```
- 环境变量（支持
```
${VAR}
```
或
```
${VAR:-default}
```
）

特殊变量：

```
${CLAUDE_PLUGIN_ROOT}
```
- 解析为插件根目录

Setting Up Dev Marketplace

设置开发市场

For local development, create a marketplace to organize your plugins:

File:

dev-marketplace/.claude-plugin/marketplace.json

json

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-dev-marketplace",
  "version": "1.0.0",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Local development marketplace for my plugins",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin-one",
      "version": "1.0.0",
      "description": "What this plugin does",
      "source": "./plugins/my-plugin-one",
      "category": "development",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      }
    },
    {
      "name": "my-plugin-two",
      "version": "0.1.0",
      "description": "Experimental plugin",
      "source": "./plugins/my-plugin-two",
      "category": "productivity",
      "strict": false
    }
  ]
}

Directory structure:

dev-marketplace/
�� .claude-plugin/
   �� marketplace.json
�� plugins/
    �� my-plugin-one/
       �� .claude-plugin/
          �� plugin.json
       �� commands/
    �� my-plugin-two/
        �� .claude-plugin/
           �� plugin.json
        �� agents/

Install dev marketplace:

bash

/plugin marketplace add file:///absolute/path/to/dev-marketplace
/plugin browse
/plugin install my-plugin-one@my-dev-marketplace

Plugin entry fields:

```
name
```
- Required: plugin identifier
```
source
```
- Required: relative path or git URL
```
version
```
- Recommended: semantic version
```
description
```
- Recommended: brief description
```
category
```
- Optional: development, productivity, security, etc.
```
author
```
- Optional: author details
```
strict
```
- Optional: default
```
true
```
(requires plugin.json), set
```
false
```
to use marketplace entry as manifest

Source formats:

json

// Local relative path
"source": "./plugins/my-plugin"

// GitHub repository
"source": {
  "source": "github",
  "repo": "owner/repo"
}

// Git URL
"source": {
  "source": "url",
  "url": "https://gitlab.com/team/plugin.git"
}

对于本地开发，创建一个市场来组织你的插件：

文件：

dev-marketplace/.claude-plugin/marketplace.json

json

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-dev-marketplace",
  "version": "1.0.0",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Local development marketplace for my plugins",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin-one",
      "version": "1.0.0",
      "description": "What this plugin does",
      "source": "./plugins/my-plugin-one",
      "category": "development",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      }
    },
    {
      "name": "my-plugin-two",
      "version": "0.1.0",
      "description": "Experimental plugin",
      "source": "./plugins/my-plugin-two",
      "category": "productivity",
      "strict": false
    }
  ]
}

目录结构：

dev-marketplace/
�� .claude-plugin/
   �� marketplace.json
�� plugins/
    �� my-plugin-one/
       �� .claude-plugin/
          �� plugin.json
       �� commands/
    �� my-plugin-two/
        �� .claude-plugin/
           �� plugin.json
        �� agents/

安装开发市场：

bash

/plugin marketplace add file:///absolute/path/to/dev-marketplace
/plugin browse
/plugin install my-plugin-one@my-dev-marketplace

插件条目字段：

```
name
```
- 必填：插件标识符
```
source
```
- 必填：相对路径或git URL
```
version
```
- 推荐：语义化版本
```
description
```
- 推荐：简短描述
```
category
```
- 可选：development, productivity, security等
```
author
```
- 可选：作者信息
```
strict
```
- 可选：默认
```
true
```
（需要plugin.json），设为
```
false
```
可使用市场条目作为清单

源格式：

json

// 本地相对路径
"source": "./plugins/my-plugin"

// GitHub仓库
"source": {
  "source": "github",
  "repo": "owner/repo"
}

// Git URL
"source": {
  "source": "url",
  "url": "https://gitlab.com/team/plugin.git"
}

Naming Conventions

命名规范

Use kebab-case everywhere:

Plugin names:
```
my-awesome-plugin
```
Command names:
```
review-code
```
Agent names:
```
security-auditor
```
Skill names:
```
test-driven-development
```

Filename mapping:

```
commands/my-command.md
```
�
```
/my-command
```

commands/project/build.md

�

/plugin-name:project:build

```
agents/code-reviewer.md
```
� agent name
```
code-reviewer
```
```
skills/my-skill/SKILL.md
```
� skill name
```
my-skill
```

所有地方都使用短横线命名：

插件名称：
```
my-awesome-plugin
```
命令名称：
```
review-code
```
代理名称：
```
security-auditor
```
技能名称：
```
test-driven-development
```

文件名映射：

```
commands/my-command.md
```
→
```
/my-command
```

commands/project/build.md

→

/plugin-name:project:build

```
agents/code-reviewer.md
```
→ 代理名称
```
code-reviewer
```
```
skills/my-skill/SKILL.md
```
→ 技能名称
```
my-skill
```

Testing Locally

本地测试

Development workflow:

Create plugin structure:

bash

mkdir -p my-plugin/.claude-plugin
echo '{"name":"my-plugin"}' > my-plugin/.claude-plugin/plugin.json

Add components (commands, agents, skills)

Install locally:

bash

/plugin install file:///absolute/path/to/my-plugin

Test functionality:

bash

/my-command arg1 arg2
# Use Task tool with your agent
# Use Skill tool with your skill

Iterate:
- Edit plugin files
- Run
```
/plugin reload
```
- Test again

Using dev marketplace:

Create marketplace structure

Add marketplace:

bash

/plugin marketplace add file:///absolute/path/to/dev-marketplace

Browse and install:

bash

/plugin browse
/plugin install my-plugin@my-dev-marketplace

开发工作流：

创建插件结构：

bash

mkdir -p my-plugin/.claude-plugin
echo '{"name":"my-plugin"}' > my-plugin/.claude-plugin/plugin.json

添加组件（commands、agents、skills）

本地安装：

bash

/plugin install file:///absolute/path/to/my-plugin

测试功能：

bash

/my-command arg1 arg2
# 使用Task工具调用你的代理
# 使用Skill工具调用你的技能

迭代：
- 编辑插件文件
- 运行
```
/plugin reload
```
- 再次测试

使用开发市场：

创建市场结构

添加市场：

bash

/plugin marketplace add file:///absolute/path/to/dev-marketplace

浏览并安装：

bash

/plugin browse
/plugin install my-plugin@my-dev-marketplace

Common Mistakes

常见错误

Issue	Symptom	Fix
Missing `.claude-plugin/`	Plugin not recognized	Create `.claude-plugin/plugin.json` at root
Invalid plugin.json	Parse error on load	Validate JSON syntax, ensure `name` field exists
Wrong tool name	Tool not available in command/agent	Check spelling: `Read` , `Grep` , `Glob` , `Bash` , `Edit` , `Write`
Description too long	Warning or truncation	Keep under 1024 characters total
Not using third person	Description sounds wrong	Use "Use when..." not "I will..."
Absolute paths in plugin.json	Breaks on other machines	Use relative paths or `${CLAUDE_PLUGIN_ROOT}`
Forgetting `/plugin reload`	Changes not visible	Run `/plugin reload` after edits
Command not found	Slash command doesn't work	Check filename matches expected command, reload plugin
Agent not auto-delegated	Agent never gets used	Improve `description` with specific triggers and symptoms

问题	症状	修复方案
缺少 `.claude-plugin/`	插件不被识别	在根目录创建 `.claude-plugin/plugin.json`
无效的plugin.json	加载时解析错误	验证JSON语法，确保 `name` 字段存在
错误的工具名称	命令/代理中工具不可用	检查拼写： `Read` , `Grep` , `Glob` , `Bash` , `Edit` , `Write`
描述过长	警告或截断	总长度保持在1024字符以内
未使用第三人称	描述语气错误	使用"Use when..."而非"I will..."
plugin.json中使用绝对路径	在其他机器上无法运行	使用相对路径或 `${CLAUDE_PLUGIN_ROOT}`
忘记运行 `/plugin reload`	修改不生效	编辑后运行 `/plugin reload`
命令未找到	斜杠命令无法工作	检查文件名是否与预期命令匹配，重新加载插件
代理未自动委托	代理从未被使用	优化 `description` ，添加特定触发条件和场景

Distribution

分发

For production/team use:

Push plugin to Git repository (GitHub, GitLab, etc.)
Create or update team's marketplace repository
Add plugin entry to marketplace.json

Team members install:

bash

/plugin marketplace add user-or-org/marketplace-repo
/plugin install plugin-name@marketplace-name

For public distribution:

Refer to official Claude Code documentation for publishing to public marketplaces.

生产/团队使用：

将插件推送到Git仓库（GitHub、GitLab等）
创建或更新团队的市场仓库
将插件条目添加到marketplace.json

团队成员安装：

bash

/plugin marketplace add user-or-org/marketplace-repo
/plugin install plugin-name@marketplace-name

公开发布：

请参考官方Claude Code文档了解如何发布到公共市场。

Reference Links

参考链接

Official plugin docs: https://docs.claude.com/en/docs/claude-code/plugins
Plugin reference: https://docs.claude.com/en/docs/claude-code/plugins-reference
MCP servers: https://docs.claude.com/en/docs/claude-code/mcp-servers

官方插件文档：https://docs.claude.com/en/docs/claude-code/plugins
插件参考：https://docs.claude.com/en/docs/claude-code/plugins-reference
MCP服务器：https://docs.claude.com/en/docs/claude-code/mcp-servers