Skill 工程设计指南（3天口播内容 Skill 系统完整搭建复盘），新手友好，后附口播获客 GitHub 网址，开源分享
1. Claude Code Skill 工程设计指南
[!abstract] 本文要点
以一个真实 Skill 的完整构建过程为例，展示如何用工程思维从零设计一个复杂的 AI Agent 技能系统。
示例项目：ah-douyin-lead-gen（获客型抖音口播稿生产系统）。
1.1. 前言：什么是 Skill 工程
Skill 不是一段提示词。Skill 是一个有状态、有流程、有知识库、有自检机制的内容生产系统。
简单 Skill（比如“帮我翻译这段文字”）只需要一个 SKILL.md。
但复杂 Skill——涉及多阶段工作流、用户知识库管理、方法论参考库、质量审核——需要工程思维来设计。
我这个 Skill 是要做什么：用户进来时什么都不懂，离开时拥有一套能持续产出获客型口播稿的内容生产线。
AI 用用户的真实经历写稿，而不是编造。
1.2. Skill 工程的完整生命周期
1.3. 准备阶段：动手前的四件事
1.3.1. 确认方法论是否已经“工程化就绪”
不是所有知识都能做成 Skill。判断标准：
本例：获客型文案白皮书（6 万字，13 章）覆盖了定义、框架、模板、自查、选题、审核。
每个环节都有可操作的步骤，不是泛泛的“要建立高位框架”
1.3.2. 整理并分类所有参考素材
把散落的文档按功能分类，这一步决定了 Skill 的文件结构：
原则：不是把所有东西塞进去。
每份参考素材要回答一个问题——“这份材料补了核心方法论的哪个缺口？”
本例中，获客型白皮书是骨架，其余文件补了四个缺口：选题筛选标准、情绪量化审核、反常识公式、需求验证工具。
1.3.3. 研究现有 Skill 的工程模式
在动手之前，先搞清楚项目中已有的 Skill 是怎么组织的。需要了解：
- SKILL.md 的 frontmatter 格式（name + description + 触发词）
- 多文件 Skill 的命名约定（StepN- 还是 00-编号？）
- 参考数据放哪里（data/ 子目录还是扁平？）
- 状态管理怎么做（项目级 JSON 还是 vault 内 Markdown？）
- 工作流描述用什么结构（Phase 0-6 还是别的？）
本例发现：
- 复杂 Skill 用 StepN- 前缀编号（尤其在有标准 SOP 的创作过程中很好用）
- 参考数据用 data/ 子目录
- 工作流统一用 Phase 0-6 结构
- 状态不存 Skill 目录内，存项目级文件或用户 vault
1.3.4. 定义 Skill 的边界
一个 Skill 不能解决所有问题。在动手前明确：
1.4. 设计阶段：四个架构决策
决策 1：单 Skill 还是多 Skill 组合
判断标准：各阶段之间是否有强数据依赖？
如果 Phase 1 的输出是 Phase 2 的输入、Phase 2 的输出是 Phase 3 的输入 → 单 Skill 更合适。
拆成多个 Skill 反而增加用户来回切换的摩擦。
本例选择：单 Skill 五阶段流水线。
知识库 → 选题 → 成稿 → 审核 → 回流，每个阶段强依赖上一个阶段的输出。
决策 2：知识库存哪里
三个选项：
本例选择：Vault 内 Markdown 文件（✍️ 写作系统/抖音/03-获客知识库/）。
拆成 7 个独立文件（定位/产品/客户/公敌/经历/购买理由/词根），每个文件一个模块，方便单独更新。
决策 3：方法论参考内容放哪里
方法论是给 AI 执行时参考的“知识库”，不是给用户看的。
放在 data/ 子目录，从 SKILL.md 的文件索引表中按需读取。
本例：data/ 目录 10 个文件，从 6 万字的白皮书提炼到约 2 万字的精简参考。
每个文件聚焦一个模块，AI 执行到对应 Phase 时只读需要的 2-3 个文件，不塞满上下文。
决策 4：文件命名和结构
命名约定：
- StepN-描述.md 用于执行指令文件（N = 执行顺序）
- data/NN-描述.md 用于参考数据（NN = 无严格顺序要求）
- SKILL.md 是唯一入口
每个 Step 文件的内部结构：
- “你的任务”段：一句话说清楚这个阶段要产出什么
- “执行前必读”段：列出需要读取的 data 文件
- “执行流程”段：Step 3.1 → 3.2 → 3.3，每一步有明确的操作指令和自检标准
- “输出格式”段：规定输出内容的结构
1.5. 工作流设计：五阶段流水线
设计原则
- 每个 Phase 有明确的输入和输出：Phase 1 输入用户口述，输出 7 个 Markdown 文件
- Phase 之间自动流转：Phase 2 选定选题后自动进入 Phase 3，不需要用户手动调用
- 支持断点续跑：用户可以在任何 Phase 停下来，下次直接跳到那个 Phase
- 首次使用和日常使用分流：知识库不存在 → 自动进入 Phase 1；已存在 → 询问用户意图
本 Skill 的五阶段
Phase 1：定位与知识库初始化
输入：用户口述
输出：7个知识库文件
↓
Phase 2：选题生成与筛选
输入：知识库
输出：3-5条通过双重筛选的选题
↓
Phase 3：口播稿生成
输入：选定选题 + 知识库素材
输出：1000-1400字获客型口播稿
↓
Phase 4：内容审核
输入：口播稿
输出：5维35分制审核报告
↓
Phase 5：知识库维护与回流
输入：口播稿 + 审核报告
输出：更新后的知识库 + 变更摘要
Phase 之间的流转逻辑
- Phase 4 评分 ≥ 30 → Phase 5（拍摄级）
- Phase 4 评分 25-29 → 针对性修改 → 重新审核
- Phase 4 评分 20-24 → 回 Phase 3 重写
- Phase 4 评分 < 20 → 回 Phase 1 检查定位
1.6. 实现阶段：从数据层到执行层
实现顺序
不要从 SKILL.md 开始写。从最底层的数据文件开始，逐层往上。
- data/ 参考库（AI 执行时的“知识底座”）
↓ - Step 执行指令（AI 执行时的“操作手册”）
↓ - SKILL.md（用户看到的“入口界面”）
第一层：data/ 参考库
每个 data 文件是一个独立的知识模块。提炼原则：
- 从原始文档中提取可操作的内容，删掉解释性文字
- 用表格和清单代替段落
- 每个文件控制在 2000 字以内
- 文件开头标注来源
本例：10 个 data 文件覆盖了从定位公式（data/09）到审核标准（data/04）到内容结构扩展库（data/08）的完整方法论链。
第二层：Step 执行指令
每个 Step 文件是 AI 在对应 Phase 的“操作手册”。写法原则：
- 先说自己要干什么，再说怎么干
- 每一步有明确的自检标准，不是“你应该注意 XX”而是“检查：XX 是否满足？”
- 规定输出格式，AI 才知道生成什么结构的内容
- 写清楚常见错误和禁止事项
本例的关键设计：Step3 中把“展示可能性，隐藏操作细节”写成了硬约束 + 自检问题——“用户看完能不能自己复制？能 → 不合格，需要删掉操作细节”。
这是整个获客型内容最核心的规则，不能只提一句，要写成可执行的检查步骤。
第三层：SKILL.md 入口文件
SKILL.md 的作用是：
- 让系统识别（frontmatter 中的 name + description + 触发词）
- 让 AI 知道什么时候读什么文件（文件索引表）
- 让 AI 知道整体工作流（五个 Phase 的概述）
- 让 AI 知道核心约束（硬约束章节）
SKILL.md 不要写太细
执行细节在 Step 文件里，SKILL.md 只是路由和总览。
1.7. 关键设计模式（可复用）
模式 1：知识库与 Skill 分离
Skill 本身不存用户数据。用户的知识库存在 vault 中，Skill 只负责读写。
好处：
- Skill 可以跨用户复用
- 用户可以直接在 Obsidian 中编辑知识库
- 知识库是纯 Markdown，不受 Skill 升级影响
模式 2：MVP 优先
复杂 Skill 不需要一次实现全部功能。先跑通核心闭环。
本例的 MVP：Phase 1（建库）+ Phase 3（写稿）+ Phase 4（审核）。
用户至少能跑通“有自己风格的获客稿”。
Phase 2（选题自动生成）和 Phase 5（自动回流）是锦上添花。
模式 3：评分驱动的流转
用明确的分数阈值控制 Phase 之间的流转，避免 AI 在“差不多”的质量上继续。
- 30-35 分：通过
- 25-29 分：修改
- 20-24 分：重写
- <20 分：回溯定位问题
模式 4：每个 Phase 规定“必须读取的文件”
不让 AI 自己判断读什么。在 SKILL.md 的文件索引表里明确规定每个文件“何时读取”。
反例：“AI 你根据情况自行读取相关文件” → AI 会全部读或一个不读
正例：“Phase 3 执行前必读：Step3 + data/00 + data/01 + data/05 + data/06”
模式 5：硬约束独立成章
把绝对不能违反的规则集中放在 SKILL.md 的“硬约束”章节，和具体的执行流程分开。
这样 AI 在每次执行时都能看到这些约束，不容易在执行复杂流程时遗忘。
1.8. 来自 GStack 的设计哲学：Thin Harness, Fat Skills
在完成初始设计后，我对照 YC CEO Garry Tan 的 GStack 项目做了一轮架构审查。
GStack 把整个创业公司工程团队“序列化”为 12 个独立 Skill，每个 Skill 扮演一个专业角色。
它的核心哲学补充和升级了我原有设计中的几个关键维度。
哲学 1：基于角色设计，而非基于流程
GStack 的核心洞见：Skill 不是流程节点，是专业角色。
/office-hours 扮演 YC 合伙人，/plan-eng-review 扮演工程经理，/cso 扮演首席安全官。
对照本 Skill 的优化：
哲学 2：多种显式工作模式
GStack 的一个 Skill 支持多种模式（如 CEO 视角分了 4 种扩围模式）。
用户不需要理解流程，只需要说“我现在需要什么”。
本 Skill 优化后定义了 4 种显式模式：
哲学 3：验证证据，不接受 AI“自称完成了”
GStack 的铁律：每个 Skill 执行后必须有可验证的证据（截图、测试通过、Diff），不接受 AI 声称“搞定了”。
本 Skill 优化后增加的验证要求：
- Phase 3 成稿后：必须标注知识库素材引用位置 + “展示可能性”自检 + 结尾 CTA 逐句检查
- Phase 4 审核后：每个扣分项必须引用原文 + 说明扣分理由 + 给出具体修改建议
- Phase 5 回流后：输出知识库变更 Diff 表——哪个文件、什么操作、新增了什么
哲学 4：人机协作，AI 是团队成员而非替代者
GStack 的每个流程节点都保留人的最终决策权。本 Skill 的对齐：
- 每个 Phase 结尾都是用户确认而非自动通过
- Phase 1 知识库内容全部来自用户口述，AI 不编造
- Phase 4 审核给出修改建议但由用户决定是否改、怎么改
GStack 参考框架（你写自己 Skill 时复用）
# Skill 名称：[角色名]
## 身份定义
你扮演的是 [角色]，你的核心视角是 [什么]
## 触发条件
当用户请求 [什么类型任务] 时，激活本 Skill
## 工作模式
- 模式A：[适用场景]
- 模式B：[适用场景]
## 执行流程
1. 步骤一：[具体操作]
2. 步骤二：[具体操作]
3. 验证：[需要输出什么作为完成证明]
## 禁止行为
- 不允许 [X]
- 不在没有验证的情况下声称完成
## 输出格式
[明确规定输出结构]
1.9. Skill 设计的常见错误（仅个人观点）
1.10. 完整的准备清单
在开始写第一行 SKILL.md 之前，确认以下全部就绪：
方法论就绪
- 核心方法论有完整的操作步骤（不是只有理念）
- 有可复用的模板或公式
- 有明确的检查/审核标准
- 有至少 3 个真实案例验证过
素材就绪
- 所有参考文档已分类（核心/补充/可舍弃）
- 每份素材标注了它补什么缺口
- 已确定哪些素材不纳入 Skill
架构决策就绪
- 单 Skill 还是多 Skill
- 知识库存哪里
- 文件结构和命名约定
- 工作流分几个 Phase
- 每个 Phase 的输入输出
边界明确
- Skill 做什么、不做什么
- 和现有 Skill 的关系
- 用户需要什么前置条件
1.11. 本案例的文件清单
ah-douyin-lead-gen/
SKILL.md ← 入口：工作流总览 + 硬约束 + 文件索引
Step1-定位与知识库初始化.md ← Phase 1：带用户建7个知识库文件
Step2-选题生成与筛选.md ← Phase 2：倒推选题 + 双重筛选
Step3-口播稿生成.md ← Phase 3：四步结构 + 4种模板 + 硬约束
Step4-内容审核.md ← Phase 4：5维35分制 + 情绪曲线 + 流转判定
Step5-知识库维护与回流.md ← Phase 5：自动提取 + 回写 + 数据复盘
data/
00-获客型文案核心框架.md ← 定义 + 四步结构 + 操作铁律
01-四种文案模板库.md ← 模板A/B/C/D + 选择决策表
02-选题公式与筛选标准.md ← 倒推公式 + 5种题型 + DELIVERR
03-论述逻辑自查框架.md ← 6项检查 + 推力结构 + 客单价配比
04-情绪注入与审核标准.md ← L1-L3分级 + 逐段标注 + 量化参考
05-无用之用与购买理由.md ← 15个认知错误 + 信号三件套
06-反常识与认知颠覆公式.md ← 3公式 + 四部分结构
07-需求验证方法与工具.md ← 平台工具 + 评论信号 + 词根分类
08-内容结构扩展库.md ← 9种结构 + 5步拆解法 + 钩子拆解
09-定位与人设公式.md ← 定位公式 + 赛道选择 + 行业公敌
本指南使用 ah-douyin-lead-gen v1.0.0 作为完整案例，Skill 源码位于 https://github.com/ahang008/ah-douyin-lead-gen
方法论来源：获客型文案白皮书 + 12 份自媒体认知补充文档
-END-
我是谁：
我是阿杭，全网 3w 粉的 AI+商业博主，00 后连续创业者，做过电商，干过工地，做过 AI 产品经理，做过 MCN，我在做一些轻创业项目，和 AI+流量打法。
抖音、小红书：阿杭在赚钱；公众号：叫我阿杭
朋友圈会分享我的日常深度思考，欢迎链接。还有一些我发现的小项目的技巧，可以直接找我要哦
使用交流欢迎添加 VX，备注来意，否则不通过哦～：
