Back to Details

plugin-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code Plugin Development

Claude Code 插件开发

Guide for creating effective Claude Code plugins with skills, commands, and agents.
本指南介绍如何创建包含技能、命令和Agent的高效Claude Code插件。

Plugin Structure

插件结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Plugin metadata
├── skills/
│   └── skill-name/
│       ├── SKILL.md        # Required
│       ├── references/     # Detailed docs
│       ├── examples/       # Working code
│       └── scripts/        # Utilities
├── commands/
│   └── command-name.md
├── agents/
│   └── agent-name.md
└── hooks/
    └── hooks.json
my-plugin/
├── .claude-plugin/
│   └── plugin.json         # 插件元数据
├── skills/
│   └── skill-name/
│       ├── SKILL.md        # 必填文件
│       ├── references/     # 详细文档
│       ├── examples/       # 可运行代码
│       └── scripts/        # 实用工具
├── commands/
│   └── command-name.md
├── agents/
│   └── agent-name.md
└── hooks/
    └── hooks.json

Skill Development

技能开发

SKILL.md Structure

SKILL.md 结构

yaml
---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", or mentions "keyword". Be specific about triggers.
version: 1.0.0
---
yaml
---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", or mentions "keyword". Be specific about triggers.
version: 1.0.0
---

Skill Title

技能标题

Core content here (1,500-2,000 words ideal).
核心内容（建议1500-2000字）。

Additional Resources

额外资源

  • references/detailed.md
     - Detailed patterns
  • examples/working.sh
     - Working example
undefined
  • references/detailed.md
     - 详细模式说明
  • examples/working.sh
     - 可运行示例
undefined

Progressive Disclosure

渐进式披露

LevelContentWhen Loaded
Metadataname + descriptionAlways (~100 words)
SKILL.mdCore contentWhen triggered (<5k words)
ReferencesDetailed docsAs needed (unlimited)
层级内容加载时机
元数据名称 + 描述始终加载（约100字）
SKILL.md核心内容触发时加载（少于5000字）
参考文档详细文档按需加载（无字数限制）

Description Best Practices

描述撰写最佳实践

Good:
yaml
description: This skill should be used when the user asks to "create a hook", "add PreToolUse hook", "validate tool use", or mentions hook events.
Bad:
yaml
description: Provides hook guidance.  # Too vague
description: Use this skill for hooks.  # Not third person
优秀示例：
yaml
description: This skill should be used when the user asks to "create a hook", "add PreToolUse hook", "validate tool use", or mentions hook events.
反面示例：
yaml
description: Provides hook guidance.  # 过于模糊
description: Use this skill for hooks.  # 未使用第三人称表述

Writing Style

写作风格

Use imperative form, not second person:
markdown
undefined
使用祈使语气，避免第二人称：
markdown
undefined

Good

正确示例

Start by reading the configuration. Validate the input before processing.
首先读取配置信息。 处理前先验证输入内容。

Bad

错误示例

You should start by reading... You need to validate the input...
undefined
你应该先读取... 你需要验证输入内容...
undefined

Command Development

命令开发

Command Structure

命令结构

yaml
---
name: command-name
description: What the command does
argument-hint: "[optional args]"
---
yaml
---
name: command-name
description: 命令功能说明
argument-hint: "[可选参数]"
---

Command Title

命令标题

Instructions for executing the command.
undefined
命令执行说明。
undefined

Example Command

命令示例

yaml
---
name: review-pr
description: Review a GitHub PR with detailed code analysis
argument-hint: "[PR number or URL]"
---
yaml
---
name: review-pr
description: 对GitHub PR进行详细代码分析评审
argument-hint: "[PR编号或URL]"
---

Review PR Command

PR评审命令

  1. Fetch PR details using 
    gh pr view
  2. Get changed files with 
    gh pr diff
  3. Analyze each file for issues
  4. Provide summary with recommendations
undefined
  1. 使用 
    gh pr view
    获取PR详情
  2. 使用 
    gh pr diff
    获取变更文件
  3. 逐一分析文件中的问题
  4. 提供包含改进建议的总结
undefined

Agent Development

Agent开发

Agent Structure

Agent结构

yaml
---
agent: agent-name
description: |
  When to use this agent with examples:
  <example>
  Context: User situation
  user: "User request"
  assistant: "How assistant responds"
  <commentary>Why this agent is appropriate</commentary>
  </example>
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
color: cyan
---
yaml
---
agent: agent-name
description: |
  本Agent的适用场景及示例：
  <example>
  场景：用户所处情境
  user: "用户请求"
  assistant: "助手回复内容"
  <commentary>为何该Agent适用于此场景</commentary>
  </example>
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
color: cyan
---

Agent Instructions

Agent行为指令

Detailed instructions for the agent's behavior.
undefined
关于Agent行为的详细说明。
undefined

Agent Colors

Agent 颜色选项

Valid colors: 
red
, 
green
, 
yellow
, 
blue
, 
magenta
, 
cyan
, 
white
可用颜色：
red
, 
green
, 
yellow
, 
blue
, 
magenta
, 
cyan
, 
white

Hooks Development

Hooks开发

hooks.json Structure

hooks.json 结构

json
{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Write|Edit",
      "type": "prompt",
      "prompt": "Validate code before writing...",
      "timeout": 10000
    }
  ]
}
json
{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Write|Edit",
      "type": "prompt",
      "prompt": "Validate code before writing...",
      "timeout": 10000
    }
  ]
}

Hook Events

Hook 事件

EventWhen Fired
SessionStart
Session begins
PreToolUse
Before tool execution
PostToolUse
After tool execution
Stop
Session ends
Notification
Background task complete
事件触发时机
SessionStart
会话开始时
PreToolUse
工具执行前
PostToolUse
工具执行后
Stop
会话结束时
Notification
后台任务完成时

Validation Checklist

验证检查清单

Skills:
  • SKILL.md has valid YAML frontmatter
  • Description uses third person with trigger phrases
  • Body is 1,500-2,000 words (detailed content in references/)
  • Uses imperative writing style
  • Referenced files exist
Commands:
  • Has name and description in frontmatter
  • Clear instructions for execution
  • argument-hint if accepts parameters
Agents:
  • Has description with examples
  • Specifies model and tools
  • Valid color specified
  • Detailed behavioral instructions
技能：
  • SKILL.md 包含有效的YAML前置元数据
  • 描述使用第三人称并明确触发短语
  • 主体内容为1500-2000字（详细内容放在references/目录下）
  • 使用祈使语气写作
  • 引用的文件实际存在
命令：
  • 前置元数据包含名称和描述
  • 执行说明清晰明确
  • 若接受参数则包含argument-hint
Agent：
  • 描述中包含使用示例
  • 指定了模型和工具
  • 颜色设置有效
  • 包含详细的行为指令

Common Mistakes

常见错误

  1. Weak skill descriptions - Be specific with trigger phrases
  2. Too much in SKILL.md - Use progressive disclosure
  3. Second person writing - Use imperative form
  4. Missing resource references - Point to references/examples
  5. Vague agent examples - Include concrete user/assistant pairs
  1. 技能描述模糊 - 需明确触发短语
  2. SKILL.md内容过载 - 采用渐进式披露方式
  3. 使用第二人称写作 - 改用祈使语气
  4. 缺少资源引用 - 指向references/examples目录下的资源
  5. Agent示例模糊 - 包含具体的用户/助手对话示例