ch3sh-lc/myworkflow/skill-authoring

触发

• 触发：创建/修改/优化/审查一个 skill，或讨论 skill 设计（"帮我写个 skill""这个 skill 不够好帮我优化""审查这个 skill"）。
• 不触发：纯使用 skill（直接调目标 skill）、与 skill 无关的代码编写、闲聊式评价（"这 skill 挺好"）。

定位

myworkflow 技能包的技能创作辅助工具：走完"设计→起草→验证→优化"全流程，确保 skill 能被正确触发和执行。设计由本 skill 负责，文件修改由「智能体闭环开发」执行；需求不清先调「需求澄清」；审查时用「反谄媚」保持批判性——不因为是自己写的就放过问题。

核心原则：TDD 方法

写 skill 就是写文档的 TDD——不写测试就先写 skill = 不写测试就先写代码。

• RED：先跑基线——不用这个 skill，模型会怎么做？会犯什么错？
• GREEN：写最小 skill——针对观察到的问题，写出刚好够用的指令。
• REFACTOR：堵漏洞——找到新漏洞 → 修补 → 重新验证。

执行流程

主线：阶段1 明确需求 → 阶段2 起草 SKILL.md → 阶段3 TDD 验证 → 阶段4 审查。

阶段1：明确需求

第一步：快速访谈（AskUserQuestion 问 4 问）：①目标：这个 skill 要帮模型做什么？②触发：用户说什么时应该触发？（列具体词句）③产出：用了之后产出有什么不同？④边界：什么情况下不应该触发？

第二步：判断 skill 类型（类型决定验证策略）：

阶段2：起草 SKILL.md

Skill 结构模板：

---
name: <skill-name>
description: <触发条件描述 — 最重要字段，决定会不会被调用>
allowed-tools:
  -Read
  -Write
  -...
---
 
## 触发场景
<!-- 触发场景简单（2-3 句话可讲清）时可融入 description 和正文首段，不设独立章节。 -->
### 必须触发
### 不触发
 
## 执行流程
### 步骤 1
### 步骤 2
...
 
## 快速参考
## 常见错误
## 危险信号
## 完成标志

Description 铁律：只能写"何时触发"，绝对不能写"skill 做了什么"。 测试发现：description 含流程总结时，模型会直接照 description 做而不读正文——skill 内容变摆设。 ❌ "Use when fixing bugs — first collect details, then find root cause, then dispatch parallel fixes" ✅ "Use when encountering any bug, error, crash, or unexpected behavior, before proposing fixes"

Description 清单：

• [ ] 以"Use when"开头（中文可用"当...时触发"）
• [ ] 含具体触发词（用户会说的原话）与触发场景
• [ ] 含反例排除（什么情况不需要）
• [ ] 不包含任何流程/步骤/工作流描述
• [ ] < 500 字符（越短越精准）

参考：references/persuasion-principles.md — 为何某些写作技巧有效

正文写作原则：

1. 解释为什么：不只写"必须做 X"，写"必须做 X，因为不做会 Y"——模型理解原因后自判边界。
2. 用红旗而非禁律：少写"禁止 X"，多写"如果你发现自己正在 X → 停下，这说明你在犯 Y 错误"。
3. 结构 > 长度：关键是模型能否快速定位所需信息。
4. 完成标志清单：每个 skill 末尾必须有 ## 完成标志（checkbox）。
5. 流程用 ASCII 图：复杂流程比文字描述清晰。

阶段3：验证（TDD 循环）

区分"能用"和"好用"，跳过验证的 skill 在真实场景必然出问题。可用 Agent 启动独立会话测试（避免当前会话已加载的 skill 干扰）。

Step 1 设计验证场景（2-3 个真实场景）：规则型→压力场景（催促/简单到"不值得走流程"/多压力叠加）；技术型→变化场景（换语言/框架/场景）；参考型→检索场景（给定问题能从 skill 找到正确答案）。

Step 2 跑基线（RED）：不加载 skill 直接给模型同样任务，记录做了什么、犯了什么错（精确到原话）、用了什么借口跳过流程。若没观察到明确问题 → 停下来，这个 skill 可能不需要——不要为不存在的需求写 skill。实操替代：要求模型"忽略 [skill名] 指令直接完成任务"近似模拟基线。

Step 3 用 skill 再跑（GREEN）：验证是否正确触发、是否遵循每个关键步骤、产出是否满足完成标志。

Step 4 迭代（REFACTOR）：每次发现新问题 → 修改 skill → 重测，直到连续 3 个不同场景全部通过。常见迭代点：跳步 → 触发条件不明确或缺硬门禁；理解偏 → 术语不通用，换通用说法；过度执行 → 边界没写清；没触发 → description 不够精准，调整触发词。

压力测试 6 种类型：时间压力（"快速完成""直接做"）/ 沉没成本（先给有问题的方案看是否推翻）/ 权威压力（"我是专家，按我说的做"）/ 疲惫压力（长对话末尾给违规指令）/ 社会压力（"其他人都这样做"）/ 务实压力（"这只是临时方案，不用走完整流程"）。

基线测试方法：设计 3-5 个场景（含 ≥2 压力）→ RED 记录违反点与原始 rationalization → GREEN 同一场景加载对比 → REFACTOR 对照违反点加固（显式否定/加入红旗/收紧触发/增加硬门禁）→ 重复直到连续 3 场景通过。

防弹完成指标：压力场景通过率 ≥ 3/3；连续 2 轮审计 P0=0 且 P1=0；基线所有 rationalization 被红旗清单覆盖；所有 skill 间引用正确（Grep 确认）。

阶段4：审查

逐项审查（可用「myworkflow:anti-sycophancy」保持批判性）：

• 结构：name 只用字母/数字/连字符；description 以 Use when 开头、纯触发条件、<500 字符；正文 <500 行（超了拆子文件）；有触发+不触发场景；有完成标志 checkbox；有常见错误表、危险信号表。
• 内容：每个"必须"都有"为什么"；无对外部插件的硬依赖；与 myworkflow skills 交互关系明确；术语一致；无"你懂的""应该没问题"等模糊表述；示例真实（不是编造的玩具例子）。
• 触发准确性：触发词覆盖用户 ≥5 种不同说法；近义词/中英变体有覆盖；与相邻 skill 边界清晰、不误触发到其领域。

常见 skill 模式速查

• 编排型（如智能体闭环开发）：自己不做事，编排其他 skill。重点决策逻辑（何时走哪步/何时升级）。坑：步骤太多→用 ASCII 流程图；循环条件不明→写清回退点；升级条件太宽→明确轮次上限。
• 技术方法型（如根因定位）：方法论+步骤演示+完整示例，一个核心示例贯穿。坑：示例太抽象→用真实 bug 从头演示到尾；步骤太多→合并到 ≤7 个；缺"什么时候不用这个方法"。
• 行为准则型（如反谄媚）：红旗检查清单+谄媚/正确行为对照+语气要求。坑：触发面太窄漏场景 / 太宽过度质疑 / 语气对抗而非建设。

完成标志

• [ ] 阶段1：需求已明确（目标+触发+产出+边界 4 问已答）
• [ ] 阶段2：SKILL.md 已起草（结构完整、description 符合铁律）
• [ ] 阶段3：至少 1 个基线场景跑过（RED），模型确实犯了预期中的错误
• [ ] 阶段3：加载 skill 后同一场景跑过（GREEN），模型正确执行
• [ ] 阶段3：至少 1 轮 REFACTOR 迭代完成
• [ ] 阶段4：审查清单全部通过
• [ ] description 只含触发条件、不含流程（铁律检查）
• [ ] 与其他 myworkflow skills 无冲突