简介
很多人写 Skill 时会把提示词写长、写细，但常见情况不是“信息不够”，而是不好复用：同一类任务今天能跑通，换个说法就不触发；流程走到一半跑偏；输出格式每次不一样。
这篇主要讲一件事：怎么把对话里试出来的做法，整理成一份自己和别人都能接着用的 Skill。写法上把它当成工作说明：触发条件、步骤、校验、失败时怎么办写清楚，尽量少靠临场发挥。
文中的例子都按软件开发里常见的一段流程来举：PRD（产品需求文档）已经具备，要把需求收成一版可评审的技术方案 / 概要设计（讲清楚范围、改动点、接口与数据、风险与待产品确认项），而不是直接替工程师写业务代码。
后面按「基础 → 设计 → 测试 → 发布 → 资源」顺着写，会涉及三个问题：
- 为什么有的 Skill 触发不准、执行不稳
- 设计阶段怎么少返工
- 多人、多场景下怎么还能改得动
第一章 基础知识
1. Skill 和「加长版提示词」不是一回事
一个好 Skill 的关键，不在“写得多”，而在“可执行、可验证、可维护”。
它通常由 SKILL.md 作为核心文件，再配合可选的 scripts/、references/、assets/。
其中最核心的是前置信息（YAML）和正文指令（Markdown）之间的分工：
- 前置信息负责“让模型知道何时应该启用你”
- 正文负责“启用后应该如何执行”
常见问题是两者没分开：前置写得太泛，容易乱触发；正文太虚，执行容易飘。
这样写（分工清楚）
---
name: prd-to-tech-design
description: 根据 PRD 输出技术方案草稿。当用户提到「技术方案」「从 PRD 出设计」「设计评审材料」时启用。
---
# PRD → 技术方案
## 执行流程
1. 核对 PRD 范围与验收口径，缺项先追问
2. 对照现有系统写改动点（模块、接口、数据）
3. 输出可评审稿：设计要点、风险、待产品确认的问题
别这样写（分工混乱）
---
name: planner
description: 一个很强大的技能，什么都能做。
---
# Planner
你需要先判断很多情况，反正尽量做得完整点。
问题在于：前置信息没有触发边界，正文没有操作步骤，模型只能“猜”。
2. 三条习惯：少而准、可组合、可迁移
少而准（渐进式披露）
不要把所有知识一次性塞进主文件。核心规则放 SKILL.md，细节放 references/，让模型按需读取。这样既省上下文，也更稳定。
可组合
Skill 很少单独存在。真实场景里经常是多个 Skill 同时启用，所以你写指令时要避免“全局接管式”语气，例如“必须忽略其他技能”。这会引发冲突。
可迁移
尽量让 Skill 与运行环境解耦。把依赖写清楚，但不要把环境细节硬编码在每一步里。这样同一 Skill 才能在不同产品形态下复用。
这样写（渐进式披露）
## 调用规则
写方案前先看 `references/architecture-overview.md`，避免和现有系统假设冲突。
若 PRD 没写验收标准或边界，先列「待澄清」，不要自己补需求。
别这样写（信息堆砌）
## 调用规则
（这里粘贴 400 行 API 说明、错误码、示例、历史变更）
主文件过重会拖慢响应，也会降低遵循率。
3. Skill 与工具层的关系
如果把工具（如各种连接器、接口）比作“手”，Skill 更像“方法”。
工具决定“能做什么”，Skill 决定“应该怎么做”。
只有工具没有 Skill 时，常见情况是接口能调，但步骤靠现想；Skill 把顺序、校验和出错怎么办先写死，用起来会顺很多。
一个简单的自检：
把说明里的大段解释删掉，只留「步骤 + 每步输入输出 + 错误处理」，流程还能不能跑通。能，一般就过关了。
4. 基础规范速查（常见问题）
SKILL.md必须大小写精确name使用 kebab-case，不要空格和大写description必须写触发语境- 不要把关键规则埋在很长段落中
- 主文件只放“执行骨架”，细节放引用文档
这样写（容易触发）
description: 根据 PRD 写技术方案草稿（范围、设计要点、接口/数据、风险、待澄清）。当用户提到「技术方案」「PRD 评审设计」「概要设计」时启用。
别这样写（很难触发）
description: 写方案。
第二章 规划与设计
1. 从场景出发，而不是从功能出发
先写 2-3 个经常遇到、能反复复现的任务场景，再动文件。每个场景最好固定四件事：
- 触发语句（用户会怎么说）
- 执行步骤（按什么顺序做）
- 依赖工具（需要哪些能力）
- 完成标准（什么结果算成功）
为什么要先做这个？因为 Skill 的本质是“把流程固化”，不是“把能力罗列”。
如果只列功能点，最后容易变成一大段散点，没有流程。
可以直接用这张场景卡片：
场景名：从 PRD 到技术方案
触发：用户说「根据这份 PRD 出个技术方案」或「把需求拆成可实现的设计」
输入：PRD（或摘要）、约束（排期/人力/合规）、现有系统边界（可简述或附文档）
步骤：
1) 从 PRD 抽出功能点、边界条件、非功能要求（性能、可用性、安全等）
2) 对照现有架构，标出要新增或改动的模块、接口、数据与依赖
3) 有关键选型时写清备选与取舍理由，避免只给结论
4) 输出可评审稿：范围说明、设计要点、接口/数据变更、风险与待产品确认的问题
完成标准：能和 PRD 逐条对上号；待澄清单列；不偷偷假设产品没写的需求
别这样写（只有功能）
支持：读 PRD、画架构图、写接口文档、拆任务、估工时……
这种写法看起来全，但没有步骤。
2. 用“成功标准”反推指令写法
最好在动手前就定义两组指标：
- 触发指标：相关问题里，Skill 是否能稳定被选中
- 执行指标：步骤是否完整、错误是否可恢复、结果是否一致
测试如果全堆在最后，返工会多。可以先想清楚什么叫「算成功」，再反推 description 和正文要写多细。
这样写（能验收）
- 触发成功率：20 个相关问题里至少触发 18 次
- 执行稳定性：连续 10 次任务创建，失败 0 次
- 结果一致性：核心字段（负责人、截止时间、优先级）齐全率 100%
别这样写（没法验收）
- “看起来差不多就行”
- “大部分时候能跑”
3. 文件与命名规范不要忽视
命名、文件名看起来小事，却是上传失败、解析失败里常见原因。最好统一：
- 目录名使用 kebab-case
- 主文件必须是精确拼写
SKILL.md - 不在技能目录里放无关说明文件
一旦这些基础规则不稳，上传失败、解析失败、触发异常会频繁出现，而且很难第一时间定位。
这样写（目录）
prd-to-tech-design/
├── SKILL.md
├── references/
│ ├── architecture-overview.md
│ └── prd-review-checklist.md
└── scripts/
└── validate_design_doc.py
别这样写（目录）
Release Notes Skill/
├── skill.md
└── README.md
4. description 写得好不好，直接影响会不会被用上
description 至少要同时写清两件事：做什么、什么情况下用。
可以按下面这种句式填：
这个 Skill 帮你完成[任务目标]。当用户提到[关键词A/B/C]或出现[场景条件]时启用。
常见错误有三种：
- 过于抽象：只写“帮忙写技术文档”
- 只有能力没有触发词：模型不知道何时该调用
- 技术术语过重：用户真实表达与描述不匹配
用词尽量贴近用户平时怎么说，少堆术语。
这样写（触发词贴近用户）
description: 根据 PRD 输出技术方案，标出改动点和待澄清问题。当用户说「出个技术方案」「PRD 怎么落地」「准备设计评审」时启用。
别这样写（术语过重）
description: 提供跨限界上下文的领域事件溯源与聚合根一致性建模能力输出。
5. 正文指令要可执行，不要靠猜
Skill 主体至少包含：
- 目标与边界
- 分步流程
- 每步输入输出
- 失败处理
- 示例任务
失败处理尤其重要。不写分支的话，线上很容易卡在一半。
可以给常见错误写清楚：出现什么现象、可能原因、下一步怎么处理。
这样写（正文能照着做）
## 步骤 1：收集输入
- 必填：PRD 正文或链接、已知约束（排期/合规/性能等，没有则标注「未提供」）
- 若缺少 PRD 依据：先追问，不凭空调方案
## 步骤 2：生成初稿
- 使用模板 `assets/tech-design-outline.md`
- 固定章节：范围与目标、现状与假设、方案说明、接口与数据变更、风险、待澄清
## 步骤 3：校验
- 运行 `python scripts/validate_design_doc.py`
- 若报错 `MISSING_OPEN_QUESTIONS`：待澄清列表非空后再重试
别这样写（正文没法执行）
先随便出一版设计，不合适再改。
第三章 测试与迭代
1. 三层测试法
第一层：触发测试
准备一组“应该触发”和“不该触发”的问题，检查边界是否清晰。
第二层：功能测试
验证流程完整性：是否按顺序执行、是否遗漏校验、是否产出符合预期。
第三层：对比测试
同一任务比较“有 Skill”和“无 Skill”的差异，关注交互轮次、失败率、结果一致性、上下文消耗。
只测功能、不测触发和对比，容易出现「单测都对、用起来别扭」的情况。
可直接使用的测试样例
应该能触发：
1) “这份 PRD 帮我出个技术方案，明天评审用”
2) “从需求里拆一版可实现的设计，标一下要改哪些接口”
不该触发：
1) “今天上海天气”
2) “直接帮我写这段需求的单元测试代码”
功能用例：
给定输入：一份 PRD 摘要（含 2 个功能点 + 1 条非功能约束）
期望输出：方案稿含范围、改动点、待澄清；待澄清不与 PRD 已写内容重复
2. 先打透一个复杂场景
可以先选一个最难、最容易翻车的任务，改到稳了再扩别的场景。
难任务会把流程缺口、异常和描述歧义都暴露出来，后面加场景会省时间。
迭代可以分三轮
- 第 1 轮：只追求“跑通”
- 第 2 轮：补齐失败处理和追问策略
- 第 3 轮：压缩上下文、提高触发准确率
3. 迭代要看三种信号
触发不足：该启用时不启用
处理方式：补充更贴近用户语言的触发词与场景描述。
触发过度：不相关任务也被启用
处理方式：增加边界条件和“不要用于”的负向描述。
执行不稳：结果漂移、报错多、需要用户纠错
处理方式：细化步骤、强化检查点、增加失败分支和重试策略。
Skill 一般不会一次定稿，要当活文档维护。
这样写（有变更记录）
v1.0.1
- 新增触发词：“技术方案”“概要设计”“PRD 落地设计”
- 新增负向边界：不接「无 PRD、一句话需求」直接出详设
- 修复：PRD 未贴全时会先追问缺哪一节
别这样写（没记录）
改了一点描述，应该更好了。
第四章 发布与分享
1. 发出去之后，要看有没有人接着用
不少人写完上传就完事，其实后面要看同事愿不愿意长期用。
发布时至少有三块内容：
- 安装方式（尽量一步一步可复制）
- 典型场景（让用户立刻知道能解决什么）
- 结果价值（比手工流程快多少、稳多少）
读者更关心省时间、少踩坑，而不是你用了什么技术名词。
这样写（发布说明）
这个 Skill 适合在评审前把 PRD 收成一版技术方案草稿：范围对齐、改动点清楚、待澄清单列，
负责落地的后端/全栈同学可以少来回扯皮。
别这样写（发布说明）
该技能采用 frontmatter + markdown + script 的多层架构。
2. 对外说明尽量说结果
可以说清楚：大概多久能做完什么事、能少犯哪类错。
少说「这是一个带 frontmatter 的文件夹」这类实现细节，别人不好判断要不要用。
介绍时可以这样写
[Skill名] 可以帮 [角色/团队] 在 [时间] 内完成 [任务]，减少 [常见错误]。
3. 记版本、收反馈
只要有人在真实业务中使用，Skill 就必须版本化管理。可以按下面做：
- 每次更新记录触发词变更、流程变更、兼容性变更
- 收集失败样本并按类型归档
- 用固定节奏回顾误触发与失败率
不记版本、不记改了什么，过几个月往往就没人敢动。
最小版本策略
PATCH：只改文案和触发词MINOR：增加步骤或新增子场景MAJOR：调整主流程或兼容性
下面用 prd-to-tech-design 举三个能对照文件 diff 想的例子（版本号按你团队习惯标在 metadata.version 或 CHANGELOG 里即可）。
PATCH（1.0.0 → 1.0.1）——只动字，不动流程
用户反馈：同事常说「帮我写个概要设计」，但 Skill 不触发。你只改 SKILL.md 前置里的 description，正文步骤一行不动。
# 改前
description: 根据 PRD 输出技术方案草稿。当用户提到「技术方案」「PRD 设计」「设计评审」时启用。
# 改后（补上团队口头常用说法）
description: 根据 PRD 输出技术方案草稿。当用户提到「技术方案」「概要设计」「PRD 设计」「设计评审」时启用。
CHANGELOG 写一句就够：fix: description 增加「概要设计」触发词，无流程变更。
MINOR（1.0.0 → 1.1.0）——多一步、多一节，老用法还能用
产品要求方案里必须写「灰度与回滚」。你在 assets/tech-design-outline.md 里加了一级标题 ## 灰度与回滚，在 SKILL.md 的执行步骤里加第 4 步「按新章节填空」，并在 validate_design_doc.py 里多检查一个锚点（例如正文里必须出现「灰度」二字）。
用户以前只要四段，现在会多一段；但还是一次对话、一份 Markdown，没有改成两阶段交付，所以算 MINOR。
CHANGELOG 示例：feat: 方案模板增加灰度与回滚，校验脚本同步。
MAJOR（1.5.0 → 2.0.0）——主路径变了，旧习惯会踩空
你把 Skill 从「单次输出一整篇方案」改成硬性两步：第一步只输出「概要 + 待澄清」，第二步用户确认后再输出「含接口字段表」的详设。老用户如果只发一条消息、等一整篇，现在拿不到完整结果，必须改交互习惯。
或者：输出从 Markdown 改成固定 JSON，下游工具按旧版去解析 Markdown 会全挂。这类都算 MAJOR，要在说明里写清「升级后怎么用」。
CHANGELOG 示例：BREAKING: 方案改为两阶段输出；单轮对话仅得概要稿。
怎么记：改几个字、补触发 → PATCH；多章节/多分支/多检查，但「还是同一种交付物」→ MINOR；交付形态或必经步骤变了，旧脚本/旧口令不适用 → MAJOR。
第五章 资源与实操
入门可以按下面顺序来：
- 先阅读一份高质量 Skill 示例，理解结构而非照抄内容
- 用自己的真实场景写出第一版 Skill 初稿
- 用三层测试法验证触发、功能、对比
- 记录失败样本并做一轮针对性迭代
- 再推广到团队并建立版本更新机制
一个粗标准：用户不用反复教「下一步该干嘛」，Skill 也能把事做完，就算写得差不多了。
可以配的辅助文件
references/prd-review-checklist.md：对照 PRD 写方案时的检查项references/error-cases.md：常见错误与处理assets/tech-design-outline.md：技术方案章节骨架scripts/validate_design_doc.py（或同类脚本）：校验必含章节与待澄清项
落地流程（初稿到发布）
- 选一个常做、又容易出错或费时间的任务
- 写出最小
description和三步执行流程 - 补上至少两个失败分支
- 跑 10 条触发测试 + 5 条功能测试
- 根据失败样本迭代 1-2 次再发布
写法示例一：description 怎么写稳一点
可以按这个句式写：
[任务目标]。当用户提到[关键词1/2/3]或提出[场景动作]时启用。不适用于[排除场景]。
这样写（边界清楚）
description: 根据 PRD 输出技术方案草稿。当用户提到「技术方案」「PRD 设计」「设计评审」时启用。
不适用于无需求依据的纯架构讨论，或直接要求写生产代码、逐文件改码。
别这样写（没边界）
description: 写技术文档。
写法示例二：SKILL.md 基础结构
---
name: prd-to-tech-design
description: 根据 PRD 输出技术方案草稿。当用户提到「技术方案」「PRD 设计」「设计评审」时启用。
---
# PRD → 技术方案
## 输入要求
- 必填：PRD 正文或链接；可选：架构约束、排期、合规要求
- 缺 PRD 或关键章节（范围/验收）时，先追问补齐
## 执行步骤
1. 按 `assets/tech-design-outline.md` 生成方案：范围、现状、方案、接口/数据、风险、待澄清
2. 用 `scripts/validate_design_doc.py` 检查必含章节与非空待澄清（无则报错）
3. 若校验失败，按错误码补全后重新生成
## 错误处理
- `MISSING_OPEN_QUESTIONS`：列出须产品确认的问题后重跑校验
- `PRD_SCOPE_UNCLEAR`：请用户补充 PRD 相关段落或缩小讨论范围后继续
这个结构的重点是：步骤明确、失败可恢复、输出可检查。
排障：四类常见问题怎么处理
问题 1：Skill 不触发
- 先看
description是否包含用户真实会说的词 - 再看是否写了过多抽象术语
- 最后补一条“不适用场景”收紧边界
问题 2：Skill 触发过多
- 给
description增加负向条件 - 删除泛化词（如「写文档」「做设计」却不写触发场景）
- 明确输入前提（如「必须有 PRD 或等价需求说明」）
问题 3：执行不稳定
- 把长段落改成编号步骤
- 给每步补“输入/输出”
- 把关键检查改成脚本化校验
问题 4：输出质量忽高忽低
- 固定输出模板（章节、顺序、字段）
- 在生成后增加质量检查环节
- 对失败项执行“定点重写”，不要整篇重生
这几类理顺以后，一般用起来会顺不少。
结语
好用的 Skill，一般不靠堆辞藻；边界清楚、步骤能照着做、出错知道怎么办、改动有记录，这些更实在。
可以把它当成团队里会过期的文档：业务一变就要跟着改，不维护就会慢慢没人用。
动手的话，三件事就够开头：挑一个常做的任务，写一版初稿，改个两三轮再看效果。
一次写完美不现实，能持续改下去比较现实。
