沉梦手记
  • 开发日常
  • 开发工具篇
  • AI工具
沉梦听雨
2026-10-13
目录

Skill开发指南：如何编写AI技能

# Skill 开发指南：如何编写 AI 技能

Skill（技能）是 AI 编程助手的"可复用能力包"。把一套完整的工作流、领域知识、代码模板封装成 Skill 后，AI 在遇到匹配的场景时会自动加载并按规范执行。本文以 Claude Code / CodeFree-O 的 Skill 体系为例，讲清楚 Skill 的目录结构、编写方法、触发匹配机制和最佳实践。

# 一、什么是 Skill

Skill 本质上是一个文件夹，里面至少包含一个 SKILL.md 文件。当用户的请求匹配到某个 Skill 的描述时，AI 会自动读取该文件并按其中的指令行事。

你可以把 Skill 理解为给 AI 的"操作手册"：

  • 没有 Skill：AI 靠通用能力应对所有任务，每次都要从头理解你的意图。
  • 有 Skill：AI 遇到特定场景时，自动加载对应手册，按预定义的流程、规范、模板执行，输出质量和一致性大幅提升。

典型应用场景：后端代码开发、HTML 原型生成、接口文档输出、代码安全审计、旅行攻略规划等。

# 二、Skill 的目录结构

Skill 的结构可简可繁，按需组织。下面从最简到最复杂，展示三种典型结构。

# 2.1 最简结构（单文件）

只有一个 SKILL.md，所有指令都写在这一个文件里。适合逻辑简单、不需要外部资源的技能。

my-skill/
└── SKILL.md
1
2

示例：backend-dev 技能就只有一个 SKILL.md，把后端开发的完整流程（需求分析 → 架构设计 → 代码生成 → 单测 → 审查 → Git 提交）全部写在一个文件中。

# 2.2 标准结构（含捆绑资源）

当技能需要脚本、参考文档或模板时，按职责分目录存放。

my-skill/
├── SKILL.md          # 必需，技能入口
├── scripts/          # 可执行代码，用于确定性/重复性任务
│   └── build.py
├── references/       # 参考文档，按需加载到上下文
│   ├── schemas.md
│   └── guide.md
└── assets/           # 输出中使用的文件（模板、图标、字体等）
    └── template.html
1
2
3
4
5
6
7
8
9

三个子目录的职责：

目录 作用 加载时机
scripts/ 存放可执行脚本（Python、Shell 等），AI 可以直接运行而不需要把代码读入上下文 需要执行时调用
references/ 存放参考文档，AI 在需要时按需读取，避免一次性塞满上下文 SKILL.md 中指明何时读取
assets/ 存放模板、图标、字体等静态资源文件 生成产物时使用

示例：skill-creator 技能使用了完整的标准结构——scripts/ 放了评估脚本、打包脚本，references/ 放了 JSON Schema 定义，assets/ 放了 HTML 模板。

# 2.3 复杂结构（含子技能）

当一个技能需要支持多种变体（如多种页面类型、多种部署平台）时，用 sub-skills/ 组织子技能。

my-skill/
├── SKILL.md              # 主技能：工作流 + 调度逻辑
├── sub-skills/           # 子技能目录
│   ├── login-page/
│   │   └── SKILL.md      # 子技能：登录页
│   ├── dashboard/
│   │   └── SKILL.md      # 子技能：仪表盘
│   └── faq-page/
│       └── SKILL.md      # 子技能：FAQ 页
├── references/           # 共享参考文档
│   ├── inference.md
│   └── checklist.md
├── assets/               # 共享模板
│   └── base-template.html
└── components/           # 共享组件库
    └── ui-components/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

示例：design-proto 技能是典型的复杂结构——主 SKILL.md 负责推断和调度，sub-skills/ 下有 13 种页面类型（登录页、仪表盘、FAQ 等），references/ 放推断规则和工艺检查清单，design-systems/ 放 9 套视觉风格，craft/ 放工艺规范。

# 2.4 子技能的 frontmatter

子技能的 SKILL.md 需要额外声明 type 和 parent 字段，表明它从属于哪个主技能：

---
name: login-page
description: 移动端优先的登录认证页面。支持手机号+SMS验证码、密码登录、社交SSO。
type: page           # 子技能类型
parent: design-proto # 父技能名称
---
1
2
3
4
5
6

# 三、SKILL.md 的写法

SKILL.md 由两部分组成：YAML Frontmatter（元数据）和 Markdown 正文（指令）。

# 3.1 YAML Frontmatter

Frontmatter 是文件顶部的 YAML 块，用 --- 包裹。它是技能的"身份证"，AI 始终能看到所有技能的元数据。

---
name: my-skill
description: |
  一句话说明这个技能做什么、什么时候触发。
  这是技能的核心触发机制，必须同时包含"做什么"和"何时用"。
triggers:
  - "关键词1"
  - "关键词2"
  - "关键词3"
---
1
2
3
4
5
6
7
8
9
10

# 必填字段

字段 说明 示例
name 技能标识符，用小写字母+连字符 backend-dev
description 技能描述，触发匹配的核心依据 见下方详解

# 可选字段

字段 说明 示例
triggers 触发关键词列表，辅助匹配 ["原型", "Demo", "html"]
type 子技能类型 page
parent 父技能名称（子技能用） design-proto
compatibility 依赖的工具或环境 requires: [webfetch]

# 3.2 description 怎么写

description 是最重要的字段——AI 判断是否使用某个技能，主要就看这段文字。

三个要点：

  1. 说清"做什么"：技能的核心能力是什么。
  2. 说清"何时用"：列出触发场景和用户可能的说法。
  3. 适当"推一把"：AI 倾向于"欠触发"（该用的时候没用），所以描述要主动一些。

对比示例：

# ❌ 太弱，容易不触发
description: 如何构建仪表盘。

# ✅ 清晰且主动
description: >
  管理后台 / 分析仪表盘生成技能。当用户提到"仪表盘""dashboard""数据可视化"
  "后台管理""KPI 看板"时自动触发。即使用户没有明确说"仪表盘"，只要涉及
  数据展示、指标监控、后台界面，也应使用本技能。
1
2
3
4
5
6
7
8
# ❌ 只说了做什么，没说何时用
description: 后端全栈开发技能。

# ✅ 做什么 + 何时用 + 触发说法
description: >
  本技能专为后端全栈开发设计。当用户输入"完成这个需求""帮我实现登录接口"
  或提供工作项 ID 时自动触发。支持 Java/Python/Go/Node.js/C# 多语言自动适配，
  覆盖从架构设计到 Git 提交的完整开发闭环。
1
2
3
4
5
6
7
8

# 3.3 Markdown 正文

正文是技能的"操作手册"，AI 在触发后会完整读取。正文没有固定模板，但通常包含以下部分：

# 技能名称

简要说明技能做什么。

## 参数 / 输入

列出技能接受的输入参数及其含义。

## 输出格式

定义产物的结构和格式，用模板或表格说明。

## 执行流程

按步骤列出执行逻辑，这是正文的核心。

### 1. 第一步
- 具体动作...

### 2. 第二步
- 具体动作...

## 规则与约束

列出必须遵守的规则、禁止行为等。

## 示例

给出一个完整的端到端使用示例。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 写作风格建议

  • 用祈使句：写"读取文件""生成代码"，而不是"你应该读取文件"。
  • 解释"为什么"：与其堆砌 MUST / ALWAYS，不如解释背后的原因。AI 理解了原因，执行更灵活。
  • 定义输出格式：用模板明确产物长什么样，减少歧义。
## 报告结构
必须使用以下模板：

# [标题]
## 摘要
## 关键发现
## 改进建议
1
2
3
4
5
6
7
  • 给出示例：用"输入 → 输出"的格式展示期望行为。
**示例 1：**
输入：添加了 JWT 用户认证
输出：feat(auth): 实现 JWT 认证
1
2
3

# 四、触发与匹配机制

理解触发机制，才能写出"该触发时一定触发、不该触发时绝不误触"的技能。

# 4.1 三级加载体系

Skill 采用**渐进式披露（Progressive Disclosure）**设计，分三级加载，按需消耗上下文：

┌──────────────────────────────────────────────────────┐
│  Level 1：元数据（name + description）                │
│  始终在上下文中，约 100 词/技能                        │
│  → AI 据此判断"要不要用这个技能"                       │
├──────────────────────────────────────────────────────┤
│  Level 2：SKILL.md 正文                               │
│  技能触发时加载，建议 < 500 行                         │
│  → AI 据此执行具体任务                                 │
├──────────────────────────────────────────────────────┤
│  Level 3：捆绑资源（scripts / references / assets）   │
│  按需加载，无大小限制                                  │
│  → AI 在执行过程中按需读取，脚本可直接运行不占上下文    │
└──────────────────────────────────────────────────────┘
1
2
3
4
5
6
7
8
9
10
11
12
13

关键原则：

  • Level 1 的 description 决定一切——写不好，技能永远不会被触发。
  • Level 2 的 SKILL.md 要精简——超过 500 行就该拆分到 references/。
  • Level 3 的资源要"指路"——在 SKILL.md 中明确说明"何时读取哪个文件"。

# 4.2 匹配是怎么发生的

  1. AI 启动时，加载所有技能的 name + description（Level 1）到上下文。
  2. 用户发来一条消息。
  3. AI 扫描所有技能的 description，判断哪个技能与当前任务匹配。
  4. 匹配成功 → 加载该技能的 SKILL.md 正文（Level 2）。
  5. 执行过程中，按正文中的指引读取 references/ 或执行 scripts/（Level 3）。

注意：AI 只在"自己处理不了"的复杂任务上才会触发技能。简单的单步任务（如"读一下这个文件"）即使描述完美匹配，AI 也可能直接用基础工具完成，不触发技能。因此，测试触发效果时要用足够复杂的真实场景。

# 4.3 description 优化技巧

写好 description 后，可以用以下策略优化触发率：

应该触发的场景（should-trigger）：

覆盖不同说法——正式的、口语的、不直接点名技能但明显需要的：

description: >
  ...当用户说"帮我做旅行攻略""规划行程""成都怎么玩""周末去哪"
  "安排一下三亚的旅行"时触发。即使用户没说"攻略"二字，只要涉及
  出行规划、景点安排、酒店预订，也应使用本技能。
1
2
3
4

不应该触发的场景（should-not-trigger）：

在描述中适当排除近似但不同的场景，减少误触：

description: >
  生成可交互的 HTML 原型页面。注意：本技能生成的是 HTML 文件，
  不是 Vue/React 工程代码。如果用户要求生成框架组件代码，不要使用本技能。
1
2
3

# 4.4 triggers 字段

triggers 是可选的辅助触发关键词列表，作为 description 的补充：

triggers:
  - "原型"
  - "Demo"
  - "html"
  - "快速生成"
1
2
3
4
5

triggers 只是辅助手段，核心匹配仍然依赖 description。不要把所有触发逻辑都寄托在 triggers 上。

# 五、捆绑资源的组织

当技能逻辑较复杂时，把内容拆分到子目录，在 SKILL.md 中按需引用。

# 5.1 references/ — 参考文档

把详细的规范、规则、速查表放在这里，SKILL.md 中指明何时读取：

## 执行流程

1. 读取 `references/inference.md` 获取推断规则与关键词速查表
2. 按规则评估用户请求的三个维度
3. 读取 `references/execution.md` 获取步骤 4-7 的完整指令
1
2
3
4
5

组织原则：

  • 单个参考文件超过 300 行时，在文件开头加目录（Table of Contents）。
  • 按领域分文件，AI 只读取相关的那一个，不全部加载。
references/
├── aws.md       # AWS 部署参考
├── gcp.md       # GCP 部署参考
├── azure.md     # Azure 部署参考
└── common.md    # 通用部署流程
1
2
3
4
5

# 5.2 scripts/ — 可执行脚本

把重复性的确定性操作封装成脚本，AI 直接运行而不需要把代码读入上下文：

scripts/
├── generate_report.py   # 生成评估报告
├── package_skill.py     # 打包技能
└── validate.py          # 验证技能格式
1
2
3
4

在 SKILL.md 中这样引用：

## 打包技能

运行以下命令打包：

```bash
python -m scripts.package_skill <技能目录路径>
1
2
3
4
5
6

> 脚本的好处：一次写好，每次执行都不占上下文窗口，且结果确定可靠。如果多个测试用例都在重复写类似的辅助脚本，那就该把它提取到 `scripts/` 中。

### 5.3 assets/ — 静态资源

模板、图标、字体等文件放在这里，生成产物时使用：
1
2
3
4
5
6
7

assets/ ├── base-template.html # 基础 HTML 模板 ├── eval_review.html # 评估审查页面模板 └── logo.svg # 图标资源


## 六、完整示例

下面是一个完整的技能示例——一个"代码审查报告生成器"技能。

### 6.1 目录结构
1
2
3
4
5
6
7

code-review-report/ ├── SKILL.md ├── references/ │ └── review-checklist.md └── scripts/ └── generate_report.py


### 6.2 SKILL.md

```markdown
---
name: code-review-report
description: >
  代码审查报告生成技能。当用户要求"审查代码""review 这段代码""看看这个 PR
  有没有问题""检查一下代码质量"时自动触发。生成结构化的审查报告，包含问题
  清单、严重程度分级和修复建议。即使用户只说"帮我看看这段代码"，只要涉及
  代码质量检查，也应使用本技能。
---

# 代码审查报告生成器

对代码变更进行结构化审查，输出可操作的审查报告。

## 输入

- 代码变更（git diff、PR 内容或直接粘贴的代码）
- 可选：审查重点（安全 / 性能 / 规范 / 全部）

## 输出格式

必须使用以下模板：

\`\`\`markdown
# 代码审查报告

## 审查概要
- 审查范围：[文件列表]
- 问题总数：X 个（高危 Y / 中危 Z / 低危 W）

## 问题清单

| 序号 | 文件 | 行号 | 严重程度 | 问题描述 | 修复建议 |
|:----:|:----:|:----:|:--------:|:--------:|:--------:|
| 1    | ...  | ...  | 高危     | ...      | ...      |

## 总体评价
[一段话总结代码质量和改进方向]
\`\`\`

## 执行流程

### 1. 获取代码变更
- 如果用户提供了 git diff 或 PR，直接使用。
- 如果用户指定了 commit 范围，执行 `git diff` 获取变更。

### 2. 加载审查清单
- 读取 `references/review-checklist.md` 获取审查维度和检查项。

### 3. 逐文件审查
- 对每个变更文件，按审查清单逐项检查。
- 记录发现的问题、行号、严重程度。

### 4. 生成报告
- 按输出格式模板生成 Markdown 报告。
- 运行 `python -m scripts.generate_report` 将报告格式化输出。

## 审查维度

| 维度 | 检查内容 |
|------|---------|
| 安全 | 硬编码密钥、SQL 注入、XSS、不安全反序列化 |
| 性能 | N+1 查询、不必要的循环、资源泄漏 |
| 规范 | 命名规范、代码风格、注释完整性 |
| 逻辑 | 空指针、边界条件、异常处理 |

## 严重程度定义

| 级别 | 定义 |
|------|------|
| 高危 | 安全漏洞、数据丢失风险、导致崩溃的 Bug |
| 中危 | 性能问题、不规范但可运行的代码、潜在 Bug |
| 低危 | 代码风格、命名建议、可选的优化 |

## 示例

**用户输入：**
> 帮我审查一下这个 PR，主要看看有没有安全问题

**输出：**

\`\`\`markdown
# 代码审查报告

## 审查概要
- 审查范围：AuthController.java, AuthService.java
- 问题总数：2 个（高危 1 / 中危 1 / 低危 0）

## 问题清单

| 序号 | 文件 | 行号 | 严重程度 | 问题描述 | 修复建议 |
|:----:|:----:|:----:|:--------:|:--------:|:--------:|
| 1 | AuthController.java | 25 | 高危 | JWT 密钥硬编码 | 从配置文件读取密钥 |
| 2 | AuthService.java | 48 | 中危 | 密码比较未使用常量时间比较 | 使用 equalsConstantTime |

## 总体评价
代码整体结构清晰，但存在一个高危安全问题（JWT 密钥硬编码），必须修复后才能合并。
\`\`\`
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# 七、最佳实践速查

# 7.1 写 description

  • [ ] 同时包含"做什么"和"何时用"
  • [ ] 列出用户可能的多种说法（正式的、口语的）
  • [ ] 适当"推一把"——"即使用户没明确说 X，只要涉及 Y 也应使用"
  • [ ] 排除近似但不同的场景，减少误触

# 7.2 写正文

  • [ ] 用祈使句，不用"你应该"
  • [ ] 解释"为什么"，不堆砌 MUST / ALWAYS
  • [ ] 定义清晰的输出格式模板
  • [ ] 包含至少一个端到端示例
  • [ ] 控制在 500 行以内，超了就拆到 references/

# 7.3 组织资源

  • [ ] scripts/ 放可执行脚本（不占上下文）
  • [ ] references/ 放详细文档（按需读取）
  • [ ] assets/ 放模板和静态资源
  • [ ] 在 SKILL.md 中明确指路："何时读取哪个文件"
  • [ ] 大文件（>300 行）加目录

# 7.4 验证技能

写完技能后，用 2-3 个真实用户说法测试触发效果：

测试类型 说明 示例
应触发 技能应该被触发的场景 "帮我做个后台管理界面"
应触发（口语） 不直接点名但意图明确 "搞个数据看板呗"
不应触发 近似但不同的场景 "帮我写个 Vue 组件"

如果该触发没触发，强化 description；如果不该触发却触发了，在 description 中加排除说明。

# 八、Skill 安装位置

不同工具的 Skill 存放路径不同：

工具 路径 说明
Claude Code ~/.claude/skills/ 用户级技能
CodeFree-O ~/.codefree-o/.config/skills/ 用户级技能

安装后，工具启动时会自动扫描这些目录，加载所有技能的元数据。

技能可以全局安装（用户级，所有项目可用），也可以放在项目目录中（项目级，仅当前项目可用）。

# 九、小结

要点 一句话
Skill 是什么 一个文件夹，至少含一个 SKILL.md
触发靠什么 description 字段是核心，triggers 是辅助
加载分几级 三级：元数据（始终在）→ 正文（触发时加载）→ 资源（按需读取）
正文写多少 建议 < 500 行，超了拆到 references/
资源怎么放 scripts/ 放脚本、references/ 放文档、assets/ 放模板
怎么验证 用真实用户说法测试"应触发"和"不应触发"两种场景

写好一个 Skill 的核心心法：先想清楚 AI 在什么场景下需要这份手册，再用 AI 能理解的语言把操作步骤写清楚，最后用真实案例验证触发和执行效果。

上次更新: 2026/10/13 20:47:25
AI上下文文档与规则文档
MCP协议详解：让AI连接万物的标准接口

← MCP协议详解：让AI连接万物的标准接口→

Theme by Vdoing | Copyright © 2023-2026 沉梦听雨 | MIT License