plugin-master

插件开发指南

快速参考

组件	位置	必需
插件清单	.claude-plugin/plugin.json	是
命令	commands/*.md	否（自动发现）
Agent	agents/*.md	否（自动发现）
技能	skills/*/SKILL.md	否（自动发现）
Hooks	hooks/hooks.json	否
MCP 服务	.mcp.json	否

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

关键规则

目录结构

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.json 架构

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

验证规则：

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

YAML Frontmatter（必需）

agents/、commands/、skills/ 中的所有 Markdown 文件都必须以 frontmatter 开头：

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

# Content...

如果没有 frontmatter，组件将无法加载。

插件设计理念（2025）

Agent 优先设计

• 主要接口：一个名为 {domain}-expert 的专家 Agent
• 尽量精简命令：自动化工作流仅需 0-2 个命令
• 原因：用户希望通过对话交互，而不是使用命令菜单

命名规范：

• docker-master → 名为 docker-expert 的 Agent
• terraform-master → 名为 terraform-expert 的 Agent

技能的渐进式披露

技能采用三层加载：

1. Frontmatter - 启动时加载，用于触发
2. SKILL.md 正文 - 技能激活时加载
3. references/ - 仅在需要特定细节时加载

这样无需增加上下文负担即可支持无限扩展。

创建插件

步骤 1：检测仓库上下文

创建文件前，请检查：

# 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
AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)

步骤 2：创建结构

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

步骤 3：创建文件

1. plugin.json - 包含元数据的清单
2. agents/domain-expert.md - 主要专家 Agent
3. skills/domain-knowledge/SKILL.md - 核心知识
4. README.md - 文档

步骤 4（有条件）：归属声明清单

如果插件包含任何随附的第三方内容、衍生内容或经许可使用的第三方内容，请在市场注册前，于插件根目录创建 NOTICES.md。应将其视为与 plugin.json 和 README.md 同等重要的正式发布文件，而非文档润色工作。有关结构完整性、许可证文本保留及交叉引用要求，请参阅 references/publishing-guide.md（“Licensed / Vendored / Derived Content”检查清单）。

如果插件不包含第三方内容，则跳过此步骤。

步骤 5：在市场中注册

重要：如果仓库根目录存在 .claude-plugin/marketplace.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"]
    }
  ]
}

组件类型

命令

位于 commands/*.md 中，由用户发起的斜杠命令：

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

# Command Name

Instructions for Claude to execute...

Agent

位于 agents/*.md 中的自主子 Agent：

---
name: agent-name
description: |
  Brief role summary. PROACTIVELY activate for: (1) trigger, (2) trigger, ..., (N) trigger. Provides: capability list.

  # Optional. Include 3-5 <example> blocks ONLY when the agent body
  # exceeds 2,500 words. Lean orchestrators omit them by design.
  # See agent-development "Example-block requirement by agent body size".
model: inherit
color: blue
---

System prompt for agent...

技能

位于 skills/skill-name/SKILL.md 中的动态知识：

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

# Skill content with progressive disclosure...

Hooks

位于 hooks/hooks.json 中的事件自动化：

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

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

最佳实践

命名约定

• 插件：kebab-case（例如，code-review-helper）
• 命令：使用动词（例如，review-pr、run-tests）
• Agent：基于角色命名（例如，code-reviewer、test-generator）
• 技能：基于主题命名（例如，api-design、error-handling）

可移植性

所有内部路径都使用 ${CLAUDE_PLUGIN_ROOT}：

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

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

平台说明

• Windows：使用 GitHub 市场安装（本地路径可能无法正常工作）
• Git Bash/MinGW：通过 $MSYSTEM 检测，并使用 GitHub 方式
• Mac/Linux：所有安装方式均可使用

故障排查

问题	解决方案
插件未加载	检查 .claude-plugin/ 中是否有 plugin.json
缺少命令	确认 frontmatter 中有 description 字段
Agent 未触发	检查 description 是否包含 PROACTIVELY activate for: 枚举。仅当 Agent 正文超过 2,500 个单词时，才添加 3–5 个 <example> 块——参见 agent-development SKILL.md“按 Agent 正文长度确定示例块要求”。精简的编排器不受此要求限制。
找不到 Marketplace	确保仓库是公开的，并检查 marketplace.json 中的路径

更多资源

如需详细信息，请参阅：

• references/manifest-reference.md - 完整的 plugin.json 字段说明
• references/component-patterns.md - 高级组件模式
• references/publishing-guide.md - Marketplace 发布详情
• examples/minimal-plugin.md - 最简单的可用插件
• examples/full-plugin.md - 包含所有功能的完整插件