我给 AI 打辅助：怎么写一个好的 Skill？

你让 AI 帮你做一次代码审查。第一次你说"帮我看看这段代码"，AI 给了个泛泛的回答。第二次你写了 500 字的提示词，告诉它要从稳定性、性能、可读性三个维度分析——效果好多了，但你每次都要重复写这 500 字。

Skill 要解决的，就是这个痛点。

---

一、Skill 是什么？

1.1 一句话定义

Skill = 结构化的工作流指令包。

Skill 是一套面向 AI 的结构化工作流指令包，用来把一次性的优质提示词沉淀为可复用、可维护的标准化能力模块。

Skill 的本质，可以理解为：给 AI 使用的专业领域 SOP 手册。
它不仅描述“要做什么”，还明确“按什么步骤做”“在什么边界内做”“输出应满足什么标准”。

从更高层看，Skill 的出现，代表着 AI 的使用方式正在从临场交互走向工程化复用。
它可以看作是 AI 走向工程化过程中的一种关键解决方案：通过把零散经验组织成稳定模块，使 AI 能以更一致、更可靠的方式承载业务逻辑。

进一步说，Skill 往往不只是“写给模型的一段话”，它还可以包含一定的流程控制特征，例如条件分支、循环、状态衔接和异常处理。
这意味着，Skill 正在从简单的提示表达，演化为一种更高层的能力组织方式。

这里我有一个猜想：

如果说从汇编语言到高级语言，是一次从“贴近机器”到“贴近人类意图”的抽象升级，那么 Skill 所代表的这种结构化自然语言，是否可能成为下一阶段更贴近人类意图的逻辑表达方式？

如果这个方向成立，那么未来人们也许不再需要写代码，而是写 Skill，或者类 Skill 的，通过结构化资源语言表达的能力模块。
人负责描述目标、规则、流程、边界和例外情况，系统再把这些结构化表达转译为具体的执行过程。

所以，什么是 skill ？

1.2 Skill 的模样

Skill 是一个目录，包含一个必需的 SKILL.md 文件和可选的辅助文件。本质上是一份给 AI 用的 SOP 说明书：

skill-name/
├── SKILL.md          ← 必需：元数据 + 指令正文
├── scripts/          ← 可选：可执行脚本
├── references/       ← 可选：按需加载的参考文档
├── assets/           ← 可选：模板、静态资源
└── ...               ← 任意其他文件

它告诉 AI 四件事：

问题	对应位置
你擅长做什么？	description
什么时候该被触发？	description 中的触发条件描述
具体怎么做？	SKILL.md 正文指令
需要哪些辅助材料？	scripts/、references/、assets/

1.3 什么时候用 Skill？

• 流程复杂
• 流程稳定
• 长期频繁使用

反例:

• ❌ 简单低频操作：“帮我翻译这句话”——杀鸡用牛刀
• ❌ 探索性聊天：没有固定流程的头脑风暴

1.4 如何评判一个 Skill 好不好？

skil的质量 = 触发准确率 + 流程完整度 + 知识充分度 + 输出稳定性 + 可维护性

维度	含义
触发准确率	该用的时候能触发，不该用的时候不误触
流程完整度	步骤是否覆盖关键节点，有无遗漏
知识充分度	references/assets 是否够用
输出稳定性	多次执行结果的一致性
可维护性	结构清晰、易于更新

---

二、Skill 结构详解

💡 本文只写重点，完整规范参考 Agent Skills Specification

2.1 SKILL.md 双层结构

┌─────────────────────────────────────┐
│ 第 1 层：YAML Frontmatter（元数据）    │  ← ~100 tokens，启动时加载
│ name / description / license ...    │
├─────────────────────────────────────┤
│ 第 2 层：Markdown 正文（指令）         │  ← <5000 tokens，触发时加载
│ Overview → Steps → Rules → ...      │
└─────────────────────────────────────┘

① Frontmatter 示例

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

② 最关键字段：name & description

• name：唯一标识，必须与目录名一致
• description：决定 Skill 能否被正确触发 —— 这是最重要的字段

⚠️ 最大陷阱：description 应该只描述"什么时候用"，绝对不要总结工作流程！否则 AI 会只看 description 就执行，跳过正文。

❌ 错误写法（总结了流程）	✅ 正确写法（只写触发条件）
执行计划时为每个任务分配子代理，并在任务间做代码审查	在当前会话中执行含独立任务的实现计划时使用
TDD——先写测试，看它失败，写最少代码，重构	在编写实现代码之前，用于任何功能开发或 bug 修复

③ 正文常用指令

章节	作用
Overview / Purpose	一句话说明目的 + 核心原则
When to Use / Not Use	明确使用边界
Prerequisites	执行前需满足的条件
Steps / Phases	核心执行流程
Rules / Iron Law	必须遵守的规则
Examples (Good/Bad)	正反对照示例
Output Format	规定输出格式
Troubleshooting / Escalation	异常处理和升级机制
Rationalizations Table	预判并堵死 AI 的自我合理化
Quick Reference	快速查阅的速查表

💡 Token 效率提示：Agent 一旦决定使用某个 Skill，就会加载整个文件。超过 100 行的参考资料请放到 references/ 目录，正文中用相对路径引用：See [reference](references/REFERENCE.md)

2.2 可选目录说明

目录	用途	特点
scripts/	可执行代码	Agent 可直接运行
references/	附加参考文档	按需加载，越省 token 越好
assets/	静态资源	模板、图片、数据文件等

---

三、四种黄金框架

3.1 总览

框架	核心特征	典型场景	代表仓库
工作流型	有先后顺序，逐步执行	知道怎么做，但步骤多怕漏掉	vercel-deploy、prd-development
检查清单型	逐项核对，强调覆盖率	确保重要事项不遗漏	fp-check、audit-context-building
生成器型	从输入到产出，重质量与格式	少量输入产出标准化内容	design-md、enhance-prompt
分析决策型	多角度分析，防 AI 偷懒	AI 辅助思考，不是单纯执行	test-driven-development、systematic-debugging

3.2 各框架要点

工作流型 (Workflow)

## Prerequisites
- Check whether the Vercel CLI is installed

## Quick Start
1. command -v vercel
2. If installed: vercel deploy [path] -y
3. If not: bash "$skill_dir/scripts/deploy.sh"

## Troubleshooting
- Network failure → rerun with escalated permissions

关键要素： 阶段编号 + 每阶段目标/产出 + 条件分支 + 异常处理

---

检查清单型 (Checklist)

Quality thresholds:
- 至少记录 5 个假设条件
- 外部交互至少考虑 3 项风险
- 至少应用 1 次第一性原理分析
- 至少组合使用 3 次"5 Whys + 5 Hows"

关键要素： 完整检查项 + 判断标准(Pass/Fail/Warning) + 优先级标记(P0/P1/P2) + 数量阈值

---

生成器型 (Generator)

## Output Format (DESIGN.md Structure)

# Design System: [Project Title]
**Project ID:** [Insert Project ID Here]

## 1. Visual Theme & Atmosphere
## 2. Color Palette & Roles
## 3. Typography Rules
## 4. Component Stylings
## 5. Layout Principles

关键要素： 输入规范 + 输出模板 + 风格约束 + 校验规则 + 常见陷阱

---

分析决策型 (Analytical)

## The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
如果你还没完成第 1 阶段，就不能提出修复建议。

## Common Rationalizations
| 借口 | 真相 |
|------|------|
| "太简单了不需要测试" | 简单逻辑也会出错，补个测试只要 30 秒 |
| "我先手动测一下" | 手动≠系统化，无法复用和追溯 |

关键要素： 分析维度 + 评估方法论 + 借口反驳表 + Iron Law + 结论格式

---

四、SKILL.md 编写技巧（内功心法）

模块	核心原则	具体做法	示例
强硬语气	用强约束表达替代商量语气和模糊借口	多用“必须 / 逐项检查 / 按顺序执行 / 不得跳过”；提前堵住常见偷懒说法	❌“如果可以，请检查一下代码质量” ✅“必须完成以下检查：圈复杂度、边界条件、异常处理，任何一项不得跳过。”
借口反驳表	提前堵住模型的偷懒和自我合理化	把常见借口写成“借口 / 反驳”对照，要求模型遇到这些情况时仍继续执行或明确升级	参考上文，太难画了…
正面指令	优先告诉模型“要做什么”	多写清晰动作和期望结果，少写抽象否定；负面约束作为补充	❌“不要写得太空泛，不要漏重点。” ✅“请按‘结论 → 原因 → 建议’输出，每部分不超过 3 点，每点附 1 个例子。”
量化阈值	要求必须可检查	把“高质量”“一些测试”改成数字标准；设置最低门槛	❌“写一些测试” ✅“每个公共方法至少 3 个测试：正常、边界、异常。”
负面指令	明确禁止高风险或高频错误动作	用 Don’t 约束误改、跑偏、越权行为	要做：先读现有代码，再给建议。 不要做：不要重写整个文件，不要新增依赖。
使用分隔符	用结构边界隔离指令、数据和示例	使用 <>、```、''' 包裹内容，防止把数据误当指令
示例提示	给出示例，模型更容易模仿	在指令中提供 1~10 个高质量示例，明确输入和输出	输入：“找不到导出按钮。” → 输出：“可用性问题”
重要事项反复强化	关键要求在结尾再强调一次	开头说一次，结尾重复一次，减少中段遗忘	开头：“输出必须使用中文，且结论先行。” 结尾：“再次提醒：最终答案必须使用中文，并先写结论。”
人工兜底	高风险情况交给人	预设升级条件，触发后停止自动处理	遇到高危漏洞、生产配置变更、用户数据删除时，立即停止并请示人工。
角色设定	先定义身份，再执行任务	指定角色、经验和擅长方向	你是一位擅长 SOP 设计和 AI 工作流的资深运营专家。
金字塔结构	先结论，后展开	先写目标和交付物，再展开细节	❌“介绍一下 Skill。” ✅“产出一份《如何使用 Skill 的方法论》。”
视觉锚点	用格式增加可读性	使用标题、编号、表格等增强可读性
思维引导	明确要求采用特定方法思考	指定分析框架或推理路径	先用第一性原理解释本质，再用 5W2H 展开。
输出约束	明确交付形式	规定语言、风格、篇幅和详略	请使用中文；风格通俗；控制在 1500 字内。
自检验证	输出前先自查	要求先评分，再给优化建议	输出前请检查：是否包含适用场景、模板和示例。
内联流程图	用可视化方式表达分支逻辑	用 ASCII 树代替大段的判断说明	信息是否充足？├─ 是：直接输出 └─ 否：列出缺失项并请示人工

---

五、最佳实践

5.1 原则

原则	一句话表达
单一职责	一个 Skill 只做一件事
组合优于嵌套	多个小 Skill 组合完成复杂任务
渐进式披露	核心指令放主文件，参考资料按需加载
主文件 < 500 行	短的才是好的
持续迭代	Skill 是活的，不是写完就扔
先跑通再优化	烂的 Skill 比没有 Skill 强

5.2 Skill特性：渐进式披露——控制 Token 消耗

第 1 层：元数据 (~100 tokens)     → 启动时加载，意图匹配
         ↓
第 2 层：指令正文 (<5000 tokens)   → 触发时加载
         ↓
第 3 层：资源文件 (按需加载)        → references/assets/scripts

实战：

• 超 100 行的资料 → references/REFERENCE.md
• 模板文件 → assets/template.md
• 可执行脚本 → scripts/extract.py
• 正文中引用 → See [reference](references/REFERENCE.md)

---

六、Skill 质量评估

维度	建议权重	标准
触发准确性	25%	description 精准，无误判
流程完整性	25%	步骤完整，含异常处理和分支
知识充分度	20%	参考文档全面且按需加载
输出稳定性	15%	多次执行高度一致
可维护性	15%	模块化，主文件 < 500 行
安全性	5%	完善的权限控制和人工兜底

---

七、实战示例：

以"产出一份《如何使用 Skill 的方法论》"为目标，展示完整构建过程：

---
name: 方法论写作技能
description: >
  将复杂方法论转化为通俗易懂、结构清晰、可直接执行的文档。
  适用于知识沉淀、SOP 编写、培训材料制作、最佳实践总结。
  当用户要求产出方法论文档、操作手册、结构化指南时使用。
metadata:
  author: your-name
  version: "1.0"
---

# Methodology Writer

## Overview
将复杂知识转化为通俗、可执行的结构化文档。
**Core principle:** 先让读者理解"为什么"，再告诉读者"怎么做"。

## When to Use
- 用户要求产出方法论文档、SOP、操作手册
- 需要把专家经验转化为团队可复用的文档

## When NOT to Use
- 简单问答 / 实时查询 / 已有现成模板只需填空

## Execution Steps

### Step 1: 理解与拆解
- 识别核心概念（不超过 3 个）
- 确定知识层级：战略层 → 战术层 → 执行层

### Step 2: 结构设计
1. **是什么** — 一句话定义 + 类比解释
2. **为什么** — 解决什么问题 + 不用会怎样
3. **怎么用** — 分步骤操作指南
4. **注意事项** — 常见坑 + 避坑指南
5. **示例** — 至少一个完整案例

### Step 3: 内容填充
- 每段不超过 5 行
- 专业术语首次出现必须解释
- 优先表格和列表，避免大段文字

### Step 4: 自检
- [ ] 初学者能否独立理解核心概念？
- [ ] 是否有具体操作步骤？
- [ ] 是否包含"什么时候不用"？
- [ ] 排版是否层次分明？

## Rules

### Do
- 用类比降低理解门槛
- 先结论后展开（金字塔原理）
- 不确定时标注"待确认"而非编造

### Don't
- 不要用学术腔调写作
- 不要堆砌术语而不解释
- 不要输出超过 3000 字

## Escalation
遇到以下情况时停止并请示：
- 涉及公司机密
- 主题超出知识范围
- 预估输出超过 5000 字

## Output Format
### 风格: 文风要求通俗易懂，避免故作高深。文章整体简明扼要，但在重点处必须有示例说明。
### 语气: 无要求

---

八、结语

本文的 Skill速查卡.md

┌──────────────────────────────────────────────────────────────┐
│                    🧰 Skill 速查卡 v1.0                       │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  📖 官方规范                                                  │
│     https://agentskills.io/specification                     │
│                                                              │
│  📦 目录结构                                                   │
│     skill-name/SKILL.md + scripts/ + references/ + assets/   │
│                                                              │
│  🏗️ SKILL.md 双层结构                                          │
│     YAML 元数据(~100 tokens) + Markdown 指令(<5000 tokens)     │
│                                                              │
│  ⚠️ 最大陷阱                                                   │
│     ❌ description 总结工作流程 → AI 跳过正文！                  │
│     ✅ description 只写"什么时候用" ≠ "怎么用"                   │
│                                                              │
│  🎯 四种黄金框架                                                │
│     🔧 工作流型 → 一步步执行                                     │
│     ✅ 检查清单型 → 逐项核对                                     │
│     🎨 生成器型 → 从输入到产出                                   │
│     🧠 分析决策型 → 多角度分析 + 堵死借口                          │
│                                                               │
│  ✍️ 核心五招                                                    │
│     强硬语气 + 量化阈值 + 负面指令                                │
│     + 借口反驳表 + 人工兜底                                      │
│                                                               │
│  ⚡ 原则                                                       │
│     • 单一职责                                                 │
│     • 组合优于嵌套                                              │
│     • 渐进式披露                                               │
│     • 主文件 < 500 行                                          │
│     • 持续迭代                                                 │
│     • 先跑通再优化                                             │
│                                                              │
│  📊 质量评分 = 触发准确×25% + 流程完整×25%                       │
│              + 知识充分×20% + 输出稳定×15% + 可维护×15%          │
│     ≥4.5 ★★★★★ 生产就绪  |  <2.5 ★★☆☆☆ 需要重写                 │
│                                                              │
└──────────────────────────────────────────────────────────────┘

感谢您的时间与思考！如果本文对您有启发：
✅ 点赞让更多同行看到
⭐ 收藏作为实践手册
💬 评论分享您的经验