extension-authoring

本技能是编写 Claude Code 扩展的权威指南，涵盖四种扩展类型：

1. 技能 - 以 SKILL.md 文件形式提供领域专业知识的模块化能力
2. 钩子 - 在工具使用和会话事件中执行的事件驱动自动化
3. 斜杠命令 - 使用 /command-name 语法触发的可复用提示词
4. 子 Agent - 用于委派任务的专用 Claude 实例

这四种扩展类型都遵循核心原则：纯 XML 结构、YAML frontmatter 和明确的成功标准。本技能将指导你按照最佳实践创建有效扩展。

你想创建或了解什么？

1. 技能 - 用于提供领域专业知识的 SKILL.md 文件
2. 钩子 - 事件驱动自动化（PreToolUse、PostToolUse、Stop 等）
3. 斜杠命令 - 使用 /command-name 的可复用提示词
4. 子 Agent - 用于委派任务的专用 Agent
5. 指导 - 帮助决定使用哪种扩展类型

请回复数字，或描述你想构建的内容。

| 回复 | 操作 | |----------|--------| | 1、"skill"、"SKILL.md" | 阅读 [reference/skills.md](reference/skills.md) | | 2、"hook"、"hooks" | 阅读 [reference/hooks.md](reference/hooks.md) | | 3、"command"、"slash" | 阅读 [reference/commands.md](reference/commands.md) | | 4、"subagent"、"agent" | 阅读 [reference/subagents.md](reference/subagents.md) | | 5、"guidance"、"help" | 使用下方的决策树 |

阅读参考文档后，严格遵循其中的工作流。

<decision_tree> 我应该使用哪种扩展类型？

Is it triggered by specific Claude Code events?
  (tool use, session start/end, user prompt submit)
    YES --> Hook

Is it a reusable prompt the user invokes with /command-name?
    YES --> Slash Command

Is it an isolated task that runs autonomously without user interaction?
    YES --> Subagent

Is it domain knowledge or workflow guidance Claude loads on demand?
    YES --> Skill

快速决策表：

需求	扩展类型
执行前验证命令	钩子（PreToolUse）
编辑后自动格式化代码	钩子（PostToolUse）
需要输入时发送桌面通知	钩子（Notification）
可复用的 git 提交工作流	斜杠命令
代码审查清单	斜杠命令
委派研究任务	子 Agent
自主编写测试	子 Agent
API 集成知识	技能
多步骤工作流指导	技能
</decision_tree>

<shared_principles> 以下原则适用于所有 Claude Code 扩展类型：

<xml_structure> 使用纯 XML 结构。移除正文中的所有 Markdown 标题。

<objective>What it does</objective>
<workflow>How to do it</workflow>
<success_criteria>How to know it worked</success_criteria>

在内容中保留 Markdown 格式（粗体、列表、代码块）。

为什么使用 XML？

• 对 Claude 来说具有语义含义（而不只是视觉格式）
• 章节边界明确
• 节省 token（约 15 个 token，而 Markdown 标题约 20 个）
• 便于可靠解析和渐进式披露 </xml_structure>

<yaml_frontmatter> 所有扩展都需要 YAML frontmatter：

---
name: extension-name       # lowercase-with-hyphens
description: What it does and when to use it (third person)
---

命名约定： create-*、manage-*、setup-*、generate-*

描述规则：

• 使用第三人称（绝不使用“I”或“you”）
• 说明它能做什么以及何时使用
• 最多 1024 个字符 </yaml_frontmatter>

上下文窗口由多个部分共享。只添加 Claude 尚不了解的内容。

• 假设 Claude 很聪明
• 质疑每一处内容：“它值得占用这些 token 吗？”
• 提供默认方案和退出路径，而不是列出多个选项
• 主文件控制在 500 行以内，并将内容拆分到参考文件中

<success_criteria> 每个扩展都应定义明确的完成标准：

<success_criteria>
- Specific measurable outcome 1
- Specific measurable outcome 2
- How to verify it worked
</success_criteria>

</success_criteria> </shared_principles>

<quick_reference> 文件位置：

扩展	项目位置	用户位置
技能	.claude/skills/	~/.claude/skills/
钩子	.claude/hooks.json	~/.claude/hooks.json
斜杠命令	.claude/commands/	~/.claude/commands/
子 Agent	.claude/agents/	~/.claude/agents/

最简示例：

<skill_example>

---
name: process-pdfs
description: Extract text from PDF files. Use when working with PDFs.
---

<objective>Extract text from PDF files using pdfplumber.</objective>

<quick_start>
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

</quick_start>

<success_criteria>提取的文本没有错误。</success_criteria>

</skill_example>

<hook_example>
```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

</hook_example>

<command_example>

---
description: Create a git commit
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

<objective>Create a git commit for current changes.</objective>

<context>
Current status: ! `git status`
Changes: ! `git diff HEAD`
</context>

<process>
1. Review changes
2. Stage relevant files
3. Create commit following repository conventions
</process>

<success_criteria>Commit created successfully.</success_criteria>

</command_example>

```markdown --- name: code-reviewer description: Reviews code for quality and security. Use after code changes. tools: Read, Grep, Glob, Bash model: sonnet --- You are a senior code reviewer focused on quality and security. 1. Read modified files 2. Identify issues 3. Provide specific feedback with file:line references - NEVER modify code, only review - ALWAYS provide actionable feedback ```

<reference_index> 详细指南：

参考资料	内容
reference/skills.md	SKILL.md 结构、路由模式、渐进式披露
reference/hooks.md	Hook 类型、匹配器、输入/输出架构、示例
reference/commands.md	Slash 命令 YAML、参数、动态上下文
reference/subagents.md	Agent 配置、执行模型、编排
</reference_index>

<anti_patterns> 所有扩展类型中常见的错误：

```markdown ## Bad - Using markdown headings ```

<good>Using XML tags instead</good>

```yaml description: Helps with stuff # Bad description: Extract text from PDF files. Use when processing documents. # Good ``` ```yaml description: I help you process files # Bad - first person description: Processes files for analysis # Good - third person ``` 提供一种默认方案并留有备用途径，而不是罗列多种替代方案。

<success_criteria> 编写完善的 Claude Code 扩展应具备：

• 有效的 YAML frontmatter，包含描述性名称和描述
• 纯 XML 结构（正文中不使用 Markdown 标题）
• 明确的目标/用途说明
• 定义的成功标准或完成验证方式
• 适当的详细程度（不过度设计）
• 真实场景测试与迭代
• 使用第三人称编写文档 </success_criteria>

写入结果旁路文件

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-extension-authoring.json：

{"ts":"[UTC ISO8601]","skill":"extension-authoring","version":"1.1.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"extensions_created":[n],"extension_type":"[skill|hook|command|subagent]"},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果部分阶段失败但仍生成了结果，请使用状态 "partial"。只有在未生成任何输出时，才使用 "error"。