plugin-master

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Development Guide

插件开发指南

Quick Reference

快速参考

Component	Location	Required
Plugin manifest	`.claude-plugin/plugin.json`	Yes
Commands	`commands/*.md`	No (auto-discovered)
Agents	`agents/*.md`	No (auto-discovered)
Skills	`skills/*/SKILL.md`	No (auto-discovered)
Hooks	`hooks/hooks.json`	No
MCP Servers	`.mcp.json`	No

Task	Action
Create plugin	Ask: "Create a plugin for X"
Validate plugin	Run: `/validate-plugin`
Install from marketplace	`/plugin marketplace add user/repo` then `/plugin install name@user`

组件	路径	是否必填
插件清单	`.claude-plugin/plugin.json`	是
命令	`commands/*.md`	否（自动发现）
Agents	`agents/*.md`	否（自动发现）
Skills	`skills/*/SKILL.md`	否（自动发现）
钩子	`hooks/hooks.json`	否
MCP服务器	`.mcp.json`	否

任务	操作
创建插件	询问："为X创建一个插件"
验证插件	运行： `/validate-plugin`
从市场安装	执行 `/plugin marketplace add user/repo` 然后执行 `/plugin install name@user`

Critical Rules

核心规则

Directory Structure

目录结构

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # MUST be inside .claude-plugin/
├── agents/
│   └── domain-expert.md
├── commands/
├── skills/
│   └── skill-name/
│       ├── SKILL.md
│       ├── references/
│       └── examples/
└── README.md

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # 必须位于.claude-plugin/目录下
├── agents/
│   └── domain-expert.md
├── commands/
├── skills/
│   └── skill-name/
│       ├── SKILL.md
│       ├── references/
│       └── examples/
└── README.md

Plugin.json Schema

Plugin.json 格式规范

json

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Complete [domain] expertise. PROACTIVELY activate for: (1) ...",
  "author": {
    "name": "Author Name",
    "email": "email@example.com"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Validation Rules:

```
author
```
MUST be an object
```
{ "name": "..." }
```
- NOT a string
```
version
```
MUST be a string
```
"1.0.0"
```
- NOT a number
```
keywords
```
MUST be an array
```
["word1", "word2"]
```
- NOT a string
Do NOT include
```
agents
```
,
```
skills
```
,
```
slashCommands
```
- these are auto-discovered

json

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Complete [domain] expertise. PROACTIVELY activate for: (1) ...",
  "author": {
    "name": "Author Name",
    "email": "email@example.com"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

验证规则：

```
author
```
必须是对象
```
{ "name": "..." }
```
，不能是字符串
```
version
```
必须是字符串
```
"1.0.0"
```
，不能是数字
```
keywords
```
必须是数组
```
["word1", "word2"]
```
，不能是字符串
请勿包含
```
agents
```
、
```
skills
```
、
```
slashCommands
```
，这些会被自动发现

YAML Frontmatter (REQUIRED)

YAML前置元数据（必填）

ALL markdown files in agents/, commands/, skills/ MUST begin with frontmatter:

markdown

---
description: Brief description of what this component does
---

agents/、commands/、skills/中的所有Markdown文件必须以前置元数据开头：

markdown

---
description: 该组件的简要说明
---

Content...

内容...


**Without frontmatter, components will NOT load.**


**若无前置元数据，组件将无法加载。**

Plugin Design Philosophy (2025)

插件设计理念（2025版）

Agent-First Design

以Agent为核心的设计

Primary interface: ONE expert agent named
```
{domain}-expert
```
Minimal commands: Only 0-2 for automation workflows
Why: Users want conversational interaction, not command menus

Naming Standard:

```
docker-master
```
→ agent named
```
docker-expert
```
```
terraform-master
```
→ agent named
```
terraform-expert
```

核心交互入口：一个名为
```
{domain}-expert
```
的专家Agent
极简命令：仅保留0-2个用于自动化工作流的命令
设计原因：用户期望对话式交互，而非命令菜单

命名规范：

```
docker-master
```
→ 更名为
```
docker-expert
```
```
terraform-master
```
→ 更名为
```
terraform-expert
```

Progressive Disclosure for Skills

Skills的渐进式加载机制

Skills use three-tier loading:

Frontmatter - Loaded at startup for triggering
SKILL.md body - Loaded when skill activates
references/ - Loaded only when specific detail needed

This enables unbounded capacity without context bloat.

Skills采用三级加载模式：

前置元数据 - 启动时加载，用于触发判断
SKILL.md主体内容 - Skill激活时加载
references/目录 - 仅在需要特定细节时加载

这种机制可实现无上限的能力扩展，同时避免上下文冗余。

Creating a Plugin

创建插件

Step 1: Detect Repository Context

步骤1：检测仓库上下文

Before creating files, check:

bash

undefined

创建文件前，请先检查：

bash

undefined

Check if in marketplace repo

检查是否在市场仓库中

if [[ -f .claude-plugin/marketplace.json ]]; then PLUGIN_DIR="plugins/PLUGIN_NAME" else PLUGIN_DIR="PLUGIN_NAME" fi

Get author from git config

从Git配置中获取作者信息

AUTHOR_NAME=$(git config user.name) AUTHOR_EMAIL=$(git config user.email)

undefined

AUTHOR_NAME=$(git config user.name) AUTHOR_EMAIL=$(git config user.email)

undefined

Step 2: Create Structure

步骤2：创建目录结构

bash

mkdir -p $PLUGIN_DIR/.claude-plugin
mkdir -p $PLUGIN_DIR/agents
mkdir -p $PLUGIN_DIR/skills/domain-knowledge

bash

mkdir -p $PLUGIN_DIR/.claude-plugin
mkdir -p $PLUGIN_DIR/agents
mkdir -p $PLUGIN_DIR/skills/domain-knowledge

Step 3: Create Files

步骤3：创建文件

plugin.json - Manifest with metadata
agents/domain-expert.md - Primary expert agent
skills/domain-knowledge/SKILL.md - Core knowledge
README.md - Documentation

plugin.json - 包含元数据的插件清单
agents/domain-expert.md - 核心专家Agent
skills/domain-knowledge/SKILL.md - 核心知识库
README.md - 插件文档

Step 4: Register in Marketplace

步骤4：在市场中注册

CRITICAL: If

.claude-plugin/marketplace.json

exists at repo root, you MUST add the plugin:

json

{
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Same as plugin.json description",
      "version": "1.0.0",
      "author": { "name": "Author" },
      "keywords": ["same", "as", "plugin.json"]
    }
  ]
}

重要提示：如果仓库根目录存在

.claude-plugin/marketplace.json

，必须将插件添加至其中：

json

{
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "与plugin.json中的描述一致",
      "version": "1.0.0",
      "author": { "name": "Author" },
      "keywords": ["与plugin.json中的关键词一致"]
    }
  ]
}

Component Types

组件类型

Commands

命令

User-initiated slash commands in

commands/*.md

markdown

---
description: What this command does
---

用户触发的斜杠命令，位于

commands/*.md

中：

markdown

---
description: 该命令的功能说明
---

Command Name

命令名称

Instructions for Claude to execute...

undefined

Claude执行该命令的说明...

undefined

Agents

Autonomous subagents in

agents/*.md

markdown

---
name: agent-name
description: |
  Use this agent when... Examples:
  <example>
  Context: ...
  user: "..."
  assistant: "..."
  <commentary>Why trigger</commentary>
  </example>
model: inherit
color: blue
---

System prompt for agent...

自主子Agent，位于

agents/*.md

中：

markdown

---
name: agent名称
description: |
  何时使用该Agent... 示例：
  <example>
  上下文：...
  用户："..."
  助手："..."
  <commentary>触发原因</commentary>
  </example>
model: 继承
color: blue
---

Agent的系统提示词...

Skills

Dynamic knowledge in

skills/skill-name/SKILL.md

markdown

---
name: skill-name
description: When to use this skill...
---

动态知识库，位于

skills/skill-name/SKILL.md

中：

markdown

---
name: skill名称
description: 何时使用该Skill...
---

Skill的渐进式加载内容...

Skill content with progressive disclosure...

钩子

undefined

事件自动化配置，位于

hooks/hooks.json

中：

json

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

支持的事件：PreToolUse、PostToolUse、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification、Stop、SubagentStop

Hooks

最佳实践

—

命名规范

Event automation in

hooks/hooks.json

json

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

Events: PreToolUse, PostToolUse, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, Stop, SubagentStop

插件：
```
kebab-case
```
格式（例如：
```
code-review-helper
```
）
命令：动词开头（例如：
```
review-pr
```
、
```
run-tests
```
）
Agents：基于角色命名（例如：
```
code-reviewer
```
、
```
test-generator
```
）
Skills：基于主题命名（例如：
```
api-design
```
、
```
error-handling
```
）

Best Practices

可移植性

Naming Conventions

—

Plugins:
```
kebab-case
```
(e.g.,
```
code-review-helper
```
)
Commands: verb-based (e.g.,
```
review-pr
```
,
```
run-tests
```
)
Agents: role-based (e.g.,
```
code-reviewer
```
,
```
test-generator
```
)
Skills: topic-based (e.g.,
```
api-design
```
,
```
error-handling
```
)

所有内部路径请使用

${CLAUDE_PLUGIN_ROOT}

：

json

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"

请勿使用硬编码的绝对路径。

Portability

平台注意事项

Use

${CLAUDE_PLUGIN_ROOT}

for all internal paths:

json

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"

Never use hardcoded absolute paths.

Windows：使用GitHub市场安装方式（本地路径可能失效）
Git Bash/MinGW：通过
```
$MSYSTEM
```
检测环境，使用GitHub安装方式
Mac/Linux：所有安装方式均适用

Platform Notes

故障排查

Windows: Use GitHub marketplace installation (local paths may fail)
Git Bash/MinGW: Detect with
```
$MSYSTEM
```
, use GitHub method
Mac/Linux: All installation methods work

问题	解决方案
插件无法加载	检查plugin.json是否位于 `.claude-plugin/` 目录下
命令不显示	验证前置元数据是否包含 `description` 字段
Agent未触发	在描述中添加 `<example>` 示例块
市场未找到	确保仓库是公开的，检查marketplace.json中的路径是否正确

Troubleshooting

Issue	Solution
Plugin not loading	Check plugin.json is in `.claude-plugin/`
Commands missing	Verify frontmatter has `description` field
Agent not triggering	Add `<example>` blocks to description
Marketplace not found	Ensure repo is public, check path in marketplace.json

Additional Resources

—

For detailed information, see:

references/manifest-reference.md
- Complete plugin.json fields
references/component-patterns.md
- Advanced component patterns
references/publishing-guide.md
- Marketplace publishing details
examples/minimal-plugin.md
- Simplest working plugin
examples/full-plugin.md
- Complete plugin with all features

—

plugin-master

Original

Translation

Plugin Development Guide

插件开发指南

Quick Reference

快速参考

Critical Rules

核心规则

Directory Structure

目录结构

Plugin.json Schema

Plugin.json 格式规范

YAML Frontmatter (REQUIRED)

YAML前置元数据（必填）

Content...

内容...

Plugin Design Philosophy (2025)

插件设计理念（2025版）

Agent-First Design

以Agent为核心的设计

Progressive Disclosure for Skills

Skills的渐进式加载机制

Creating a Plugin

创建插件

Step 1: Detect Repository Context

步骤1：检测仓库上下文

Check if in marketplace repo

检查是否在市场仓库中

Get author from git config

从Git配置中获取作者信息

Step 2: Create Structure

步骤2：创建目录结构

Step 3: Create Files

步骤3：创建文件

Step 4: Register in Marketplace

步骤4：在市场中注册

Component Types

组件类型

Commands

命令

Command Name

命令名称

Agents

Agents

Skills

Skills

Skill content with progressive disclosure...

钩子

Hooks

最佳实践

命名规范

Best Practices

可移植性

Naming Conventions

Portability

平台注意事项

Platform Notes

故障排查

Troubleshooting

更多资源

Additional Resources