第 4 章：创作自定义技能¶

从使用者到创作者 —— 学会从零设计并编写一个高质量的 AI 技能，将你的领域知识固化为可复用的能力模块。

4.1 什么时候需要自创技能？¶

在以下情况下，你需要考虑自己动手创建技能：

现有技能无法满足你的特定需求
你需要将团队内部的 工作流程标准化
你拥有某个领域的 独特知识或方法论
你希望为社区做出贡献，分享你的最佳实践

4.2 技能设计原则¶

在动手写之前，先理解一个好的技能应该满足哪些原则：

原则	说明	示例
单一职责	一个技能只解决一类问题	"教程生成"比"内容创作全家桶"更好
结构化流程	定义清晰的阶段和步骤	资料收集 → 分析 → 生成 → 审查
明确输出	定义标准化的输出格式和质量标准	"输出 MkDocs Material 格式的 Markdown 文件"
可复用性	技能应该在不同场景下可复用	支持多种编程语言，而非仅 Python
最小依赖	减少对外部工具和知识的依赖	优先使用 AI 自身能力而非要求安装软件

4.3 技能的文件结构¶

一个标准的技能包含以下文件：

my-skill/
├── SKILL.md              # 技能核心定义（必需）
├── references/           # 参考资料（推荐）
│   ├── workflow.md       #   详细工作流程
│   ├── examples.md       #   输入/输出示例
│   └── domain-kb.md      #   领域知识库
├── assets/               # 辅助资源（可选）
│   └── templates/        #   输出模板
└── ATTRIBUTIONS.md       # 归属声明（推荐）

4.4 编写 SKILL.md¶

SKILL.md 是技能的核心文件。它的结构通常包含以下几个部分：

4.4.1 元数据区¶

# 技能名称

> **一句话描述** —— 这个技能做什么，解决什么问题。

---

## 触发关键词

- "关键词1"
- "关键词2"
- "关键词3"

## 适用场景

- 场景 A
- 场景 B

4.4.2 角色定义¶

明确定义 AI 在加载此技能时应扮演的角色：

## 角色

你是一个 {领域} 的 {角色描述}。

你的核心能力包括：
1. 能力 A
2. 能力 B
3. 能力 C

你的工作原则：
- 原则 1
- 原则 2

4.4.3 工作流程¶

定义结构化的处理流程。复杂任务建议使用多阶段流程，每阶段有关卡（Gate）检查：

## 工作流程

### Phase 1：需求理解
- 收集用户的需求描述
- 确认关键参数（受众、风格、范围等）
- **关卡**：确认需求明确，无歧义后进入下一阶段

### Phase 2：核心处理
- 执行核心任务
- 分步骤产出中间结果
- **关卡**：中间结果通过检查后进入下一阶段

### Phase 3：输出与验证
- 生成最终结果
- 提供验证方法
- 收集用户反馈

4.4.4 输出规范¶

定义输出的格式和质量标准：

## 输出规范

- 格式要求：{具体要求}
- 质量标准：
  | 维度 | 要求 |
  |:---|:---|
  | 完整性 | 覆盖所有必要内容 |
  | 准确性 | 信息准确，代码可运行 |
  | 可读性 | 结构清晰，易于理解 |

4.4.5 示例与边界¶

提供输入输出示例，明确能力的边界：

## 使用示例

### 输入
"请帮我 {具体任务描述}"

### 预期输出
{展示期望的输出格式和内容}

## 限制与边界

- 本技能适用于 {适用范围}
- 本技能不适用于 {限制范围}

4.5 实战：创建一个"代码注释生成"技能¶

让我们通过一个完整示例来理解技能创建的全过程。

需求分析¶

目标：自动为代码添加规范的中文注释
受众：开发者，需要清晰的代码文档
触发词："生成注释"、"添加注释"、"代码注释"

编写 SKILL.md¶

# Code Commenter

> **让代码自己说话** —— 为代码自动生成规范、清晰的中文注释。

---

## 角色

你是一个代码注释专家。你擅长：
1. 分析代码逻辑并提炼核心意图
2. 用简洁的中文描述代码行为
3. 遵循各语言的注释规范

你的原则：
- 注释应该解释"为什么"，而非重复"做什么"
- 复杂逻辑必须添加注释
- 保持注释风格一致

## 工作流程

### Phase 1：代码理解
- 阅读并理解代码的整体结构
- 识别关键函数、复杂逻辑和边界条件

### Phase 2：注释生成
- 为每个函数/方法生成 docstring 注释
- 为复杂逻辑块添加行内注释
- 保持注释简洁有力

### Phase 3：输出
- 输出带有完整注释的代码
- 标注新增注释的位置

## 输出规范

- 注释语言：中文
- 注释风格：遵循语言标准（Python → Google Style，JS → JSDoc）
- 避免冗余注释（如 `x = x + 1  # x 加 1`）

4.6 技能测试与迭代¶

创建技能后，按以下步骤测试和改进：

第 1 轮：基础功能测试¶

用简单任务验证技能是否正常工作：

请帮我给以下代码添加注释：
[粘贴你的代码]

第 2 轮：边界测试¶

测试技能的边界：

极简输入（只有一行代码）
极复杂输入（大型文件）
非目标语言（技能未覆盖的语言）

第 3 轮：收集反馈¶

将技能分享给同事或社区，收集使用反馈，根据反馈迭代优化 SKILL.md。

4.7 发布你的技能¶

完成开发和测试后，你可以将技能分享给更多人：

发布到 GitHub¶

# 初始化仓库
git init
git add .
git commit -m "初始版本：XXX 技能"

# 推送到 GitHub
git remote add origin https://github.com/<你的用户名>/<技能名>.git
git push -u origin main

建议在 README 中包含： - 技能的用途和特点 - 安装方法（针对不同 AI 助手） - 使用示例（触发词 + 输入/输出） - 依赖说明

发布到技能市场¶

Claude Code 生态：提交到技能注册中心（如 skills.sh 的要求）
社区分享：在 Reddit、X、掘金等平台分享你的技能

4.8 本章小结¶

技能设计遵循单一职责、结构化流程、明确输出等原则
SKILL.md 是核心，包含元数据、角色定义、工作流程和输出规范
创建后通过三轮测试（基础、边界、反馈）迭代优化
通过 GitHub 和社区渠道分享你的技能

实践任务¶

完成"代码注释生成"技能的完整 SKILL.md
用你自己的代码测试这个技能
设计一个属于你自己的技能——确定它的名称、触发词、工作流程
写出这个技能的 SKILL.md 初稿