hanzhcn laohan Skill 创建·审计·修复·优化器
创建是生产能力，审计是只读诊断，修复是小范围纠错，优化才是实验性演进。先判断模式，再使用与风险相称的验证；不得把一次明确的小修复升级成完整优化项目。
参考来源
当前借鉴 6 组上游来源。具体文件与最近核验 commit 记录在 references/upstream-sources.json。修改本 Skill 自身或用户要求更新方法时，先运行 scripts/check-upstreams.sh；发现上游变化后阅读相关 diff，只吸收能改善本地真实行为的变化，不自动覆盖本地方法。
anthropics/skills · skill-creator（https://github.com/anthropics/skills）
- 借鉴：渐进式披露（metadata→body→bundled 三层）、同条件 baseline 对比、盲比较、description 优化器、从 transcript 找重复工作、更新保持原名
- 核心理念：好的 skill 分三层渐进披露，不是一坨
Agent Skills specification / best practices（https://github.com/agentskills/agentskills）
- 借鉴：frontmatter 公共规范、渐进式披露、真实经验优先、控制强度与任务脆弱性匹配、从执行轨迹删除无效步骤
- 核心理念：Skill 应补充 agent 缺少的领域经验，不重复常识；过度全面同样会降低效果
mattpocock/skills · writing-great-skills（https://github.com/mattpocock/skills）
- 借鉴：触发分支、信息层级、完成条件、单一真源、去除 duplication/sediment/no-op
- 核心理念：Skill 追求过程可预测，不追求所有输出相同；不同分支只加载各自需要的信息
thananon/9arm-skills · debug-mantra/post-mortem/scrutinize（https://github.com/thananon/9arm-skills）
- 借鉴：verbatim recitation（首次一次+逐字+silent apply）、硬门控措辞、refuse to draft、跨 skill offer 非自动、先质疑意图、cite or it didn't happen
- 核心理念：不确定就停下来，每个 claim 要有引用
alchaincyf/darwin-skill + SkillLens / SkillOpt（https://github.com/alchaincyf/darwin-skill）
- 借鉴：9 维评分体系、反例黑名单 8 条、棘轮机制（git ratchet）、独立子 agent 复评、人在回路 5 阶段
- 核心理念：SkillLens 显示无 rubric 的 LLM 成对判断只有 46.4% 准确率，验证过的 meta-skill rubric 提升到 73.8%，仍不足以代替真实任务验证
obra/superpowers · writing-skills（https://github.com/obra/superpowers）
- 借鉴：只有深度创建/优化才做无 Skill baseline 与压力场景；可机械执行的约束优先交给脚本或 verifier
- 核心理念：测试应证明 Skill 改变了实际行为，但不能把 TDD 仪式强加给明确的小修复
核心理念
四原则：
- 路由决定成本 — name + description 负责让 agent 找到 Skill，正文第一步负责选择正确分支；触发准确不等于每次都走重流程
- 结构引导行为 — 好骨架比好指令有效
- 精简优于完整 — 每个章节都要证明存在的价值
- 效果先于格式分 — 静态 rubric 用于发现问题；触发、执行、held-out 样本与用户验收决定是否保留改动
先选模式
每次只选一个主模式：
| 模式 | 何时用 | 默认验证强度 |
|---|---|---|
CREATE |
新建一个可复用 Skill | 真实样本、触发/反触发、执行测试；复杂或高影响 Skill 再加 held-out |
AUDIT |
体检、评分、检查合理性 | 只读，引用具体行和行为证据；不修改文件 |
SURGICAL_FIX |
恢复原版、修正明确错误、更新固定合同或路径 | 比对真源、最小修改、直接覆盖该错误的针对性回归；不做静态评分、blind judge 或无关 held-out |
OPTIMIZE |
用户明确要求提升效果、比较新旧方案或全面演进 | 冻结 baseline/指标，运行 held-out；主观结果才用 blind judge |
UPSTREAM_REFRESH |
更新本 Skill 借鉴的方法或核验引用是否变化 | 运行上游检查，阅读变化，只合并相关增益并更新记录 commit |
用户说“改 Skill”但给出了明确错误或原版真源，默认 SURGICAL_FIX；只有用户要求“优化效果、全面审核、比较方案”才进入 OPTIMIZE。AUDIT 不隐含修复授权，CREATE 不隐含安装或发布授权。
上游更新
UPSTREAM_REFRESH 和修改 laohan-skillcreator 自身时：
- 运行
bash scripts/check-upstreams.sh。 CURRENT：继续当前任务。UPDATED：读取记录 commit 到最新 commit 的相关文件 diff，判断是否改变本地借鉴的方法。- 只有确有增益才修改本 Skill；无相关增益只更新核验说明，不照搬上游全文。
- 验证本地模式分流没有退化后，更新
references/upstream-sources.json的 commit 和verified_at。 UNVERIFIED：报告无法核验，不声称已经跟上上游；不阻断与上游无关的SURGICAL_FIX。
CREATE 流程
Step 0 · 先质疑意图（硬门控，scrutinize 模式）
新建前强制检查三个问题；先用 catalog/项目证据自主回答，只有用户意图无法从对话确定时才询问：
- 能不能扩展现有 skill？（从当前 runtime 的 available-skills catalog 和项目本地 skill 目录查重叠；不猜安装路径）
- 能不能不建？（做 nothing 行不行？手动一次性操作够不够？）
- 确认必须新建 → 进入 Step 1
如果 1 或 2 答 yes → 告诉用户替代方案（扩展哪个 skill / 为什么不必建），不新建。
Step 1 · 捕获意图
从对话提取（或问用户）：
- 这个 skill 让 agent 能做什么？
- 什么时候触发？（用户会说什么关键词/什么场景？）
- 期望输出格式？
- 是否需要 scripts/ 或 references/ 子目录？
用户说不清 → 停下来，列出不明确的部分，等补充。不要猜。
Step 2 · 调研
确认 Step 0 的"不能扩展已有"结论（重查 catalog 和当前项目）。如发现可扩展 → 回 Step 0。
- 完成条件： 确认新建并说明理由
Step 3 · 写 SKILL.md
按下方骨架模板和写法规则。先判断极简还是完整骨架，再填。
- 完成条件： frontmatter 符合目标 runtime 允许的 schema（Agent Skills 通用最小集是 name + description；laohan-local profile 另要求 version），正文与资源引用完整
Step 4 · 测试迭代
- 先在可写工作副本中测试；只在目标 runtime 要求安装才按其官方路径/打包方式安装，不自动建 symlink
- 触发测试：自动路由 Skill 至少覆盖一个 should-trigger 和一个近似 should-not-trigger；分支多或 description 改动大时扩到每个分支，纯手动调用记
NOT_APPLICABLE - 执行测试：确定性 skill 用可机械验证的输入/输出夹具；主观性 skill 用盲比和具体质量标准
- held-out 验证：复杂、高影响或用户要求比较效果时至少保留 1 个未用于改稿的样本；简单 Skill 用一个真实执行样本即可
- 重复工作检查：读执行 transcript，若每次生成相同辅助代码 → 提取到 scripts/
- 不通过 → 回 Step 3 改 → 重新测试
- 3 轮未过 → 停，可能是结构问题不是小补，重审核心理念
Step 5 · 本地验收
- 用真实执行结果决定是否完成；6维评分只在结构不清或用户要求评分时作为诊断
- 复杂/高影响 Skill 需 held-out 不退化；简单 Skill 的目标样本和触发测试通过即可接受
- 🔴 PUBLISH CHECKPOINT：只有用户明确要求 push/publish/package/install 时才执行相应外部动作；创建或优化本身不隐含发布授权
SKILL.md 骨架模板
不是每个 Skill 都需完整骨架。逻辑简单到几行能说清时直接写指令，别为“专业”加多余章节。
判断标准：单步、无复杂条件分支（简单回退除外）、无角色区分 → 极简。多步/有条件分支/多角色 → 完整骨架。
极简示例（5 行）
---
name: caveman
description: 极简回应模式，只输出关键信息。Use when 用户说"caveman mode""极简""少说废话""简短"。
---
所有回应控制在 3 句话以内。只给结论和关键依据，不解释过程。如果用户要求详细解释，恢复正常模式。
完整骨架模板（v2 升级）
---
name: skill-name
description: 一句话说清做什么。Use when 用户说"触发词1""触发词2""触发词3"或提到[相关场景]。 # ≤1024字符，3-8触发词，第三人称
# version: 1.0 # 只在目标 runtime/profile 允许时加
---
# Skill 标题
一句话定位。
## 核心理念（复杂 skill 必加，简单可省）
为什么存在、遵循什么原则。先讲 why 再讲 how——比直接列步骤更有效。
## 工作流
### 1. [步骤名]
- 做什么
- **完成条件：** [怎么判断这步做完了]
- **🔴 CHECKPOINT：** [仅当该步有外部副作用、高风险或用户保留决策时填；否则删除]
- **🛑 STOP：** [强制停止条件]
### 2. [步骤名]
- 做什么
- **失败处理（只有存在复杂降级链时用三段式；单一安全 STOP 直接写 if-then）：**
| 触发条件 | 一线修复 | 仍失败兜底 |
|---------|---------|-----------|
| [X 失败] | [Y] | [Z] |
### 3. [步骤名]
- 做什么
- **涉及外部动作 → 🔴 等用户确认再执行**
## 操作规则
跨步骤常驻约束：
- [规则1]
- [规则2]
- 遇到 [异常] → [怎么处理]（不静默跳过）
## 不适用场景（refuse to draft 硬拒绝，v2 升级）
- 场景 A → 改用 [其他 skill]
- **缺 [必要输入 X] → 列出缺什么并停，不硬编、不猜**（9arm post-mortem 模式）
## 反模式（复杂 skill 必加，v2 从可选升级）
❌ 差：
"[反例]"
✅ 好：
"[正例]"
## 输出格式（可选）
# [标题模板]
## [章节1]
评分体系（6 维快速评分卡）
精简自 darwin 9 维（完整 9 维见 references/scoring-rubric.md）。给任何 skill 打分：
| # | 维度 | 权重 | 评分标准 |
|---|---|---|---|
| 1 | frontmatter 质量 | 10 | name/description 符合目标 runtime 的允许字段；description 同时说做什么与何时用。触发词数是启发式，不为凑 3-8 个堆词 |
| 2 | 工作流清晰度 | 20 | 编号步骤+明确完成条件+输入输出清晰 |
| 3 | 失败模式编码 ⭐ | 20 | 覆盖真实可发生且会影响结果的失败面；一个安全 STOP 已足够时不强行写三段表，复杂降级链才要求三段式 |
| 4 | 检查点设计 ⭐ | 15 | 外部副作用、高风险或用户保留决策前有显性 gate；自治/确定性 skill 说明无人工 gate 的理由也可满分，不为格式加假 checkpoint |
| 5 | 可执行具体性 ⭐ | 25 | 有具体参数/格式/示例可直接执行；只在软化词替代必要决策规则时扣分，引用、用户输出和不确定事实不机械命中 |
| 6 | 反例与风险边界 ⭐ | 10 | 阻止本 skill 实际可能触发的误用和危险动作；不涉及 git/删除/发布的 skill 不因没列这些动作扣分 |
算分：每维 1-10 分，总分 = Σ(维度分/10 × 权重)，满分 100。
cite or it didn't happen（9arm）：每个扣分必须引用 SKILL.md 具体行号或段落原文。不允许泛泛"这里不够好"。
评分档位：
- 85-100：静态结构可进入执行/held-out 验证，不等于可发布
- 70-84：需优化（找最低维改）
- <70：结构有问题，重审核心理念
AUDIT 流程
- 冻结被审计文件和用户关心的问题，读取原版、当前版与实际调用边界。
- 先找会改变触发、执行、效果或维护成本的问题，再看格式；每个发现引用具体行、diff 或执行证据。
- 区分
BLOCKING、BEHAVIOR_RISK、MAINTENANCE和NO_ISSUE，不把静态分数当问题数量。 - 输出结论与最小建议，不修改文件、不安装、不提交；用户随后要求修复时再路由到
SURGICAL_FIX或OPTIMIZE。
SURGICAL_FIX 流程
- 明确错误、原版真源和应保持不变的行为。
- 只修改能追溯到该错误的行；保留现有模板、方法库和已验证效果，清理本次产生的重复或矛盾规则。
- 运行一个能在修复前失败、修复后通过的针对性检查；若影响已有机械合同，再运行对应合同回归。
- 不为本次小修复增加评分表、blind judge、全量 trigger 矩阵、通用框架或新 Skill。
- 报告改了什么、验证了什么、哪些真实效果仍待实际使用证明。
OPTIMIZE 流程
优化已有 skill（只改自研 laohan 系列；npx 第三方 fork 后改）：
1. 建立可比基线
- 主 agent 按 6 维找结构问题，扣分引行号
- 冻结基线 skill、目标 runtime、测试样本、评分器和成功指标；没有这些就不声称“优化”
2. 一轮一个因果假设
- 每轮只修复一个可检验的行为缺陷；同一根因涉及多个 rubric 维度时一次改完，不为“一轮一维”留下自相矛盾
- 在未提交工作副本中应用 bounded add/delete/replace，记录假设与改动预算
3. 独立验证与 held-out gate
- 确定性 skill 用冻结的机械 verifier 比较基线/候选；主观输出由不知道版本标签的 judge盲比。只做静态审计时可用独立 judge 抓自相矛盾，但不把 73.8% 当绝对真值
- 候选只在预注册指标严格改善，或主指标持平且修复已证实高风险缺陷时接受；否则丢弃未提交改动
4. 棘轮轻量版
- 验证通过后才 commit；如用户已授权且候选已被单独 commit，退步时用
git revert，不用破坏性 reset - 连续 2 轮 held-out 无实质改善或一轮只提高格式分时停手
5. 深度优化路由（不在这做）
需要大样本多轮优化时，读 references/scoring-rubric.md 跑完整 9 维；如当前 catalog 已安装 darwin-skill，也可按它的 held-out 循环执行。不在当前任务中自动安装。
操作规则
所有模式的共同约束：
- 保持精简：写完逐条审查，删不影响输出的指令
- Lazy creation：有内容才建文件/目录，不先建空结构占位
- 通用化非过拟合：不为单个用例做小众调整
- 解释 why："因为 A 所以 B" 优于 "MUST 做 B"——LLM 聪明，给理由比硬规则有效（anthropics）
- 匹配目标用户语言：laohan 系列默认中文，技术术语保留英文
- 更新保持原名：installed 是
research-helper就输出同名，不是 v2（anthropics）
dim5 软化措辞审查（只在 AUDIT/OPTIMIZE 评分时使用）
只审查可执行指令段：以下措辞若代替了具体条件/动作，出现 ≥3 处时 dim5 扣 ≥3 分；引用、反例、用户输出或客观不确定性不计：
- "建议" / "可以考虑" / "根据情况" / "灵活把握" / "视情况而定" / "酌情" / "适当"
改用具体指令："做 X"（祈使句 + 具体参数/示例）。完整禁用词表见 references/blacklist-phrases.md。
反例黑名单（v2 新，darwin 8 条精简）
创建/优化时禁止：
- 不把自评当验收 — 同一 session 可做静态诊断；确定性候选接受需独立机械 verifier + held-out，主观候选需 blind judge + held-out（OPTIMIZE/复杂候选接受时）
- 不先 commit 再评 — 先在工作副本比较；只在候选已单独 commit 且获授权时用
git revert - 不为凑分堆冗余 — 触顶（连续 2 轮 Δ<2 分）就停
- 不把静态分冒充验收分 —
AUDIT可标STRUCTURE_ONLY；只有OPTIMIZE的效果改善结论必须有 baseline/with-skill/held-out 行为证据 - 一轮只验一个行为假设 — 不用 rubric 分类强行切断同一根因
- 不静默跳过异常 — fallback 失败必须先告知用户
不适用场景（refuse to draft，v2 升级为硬拒绝）
- 创建 agent（agent ≠ skill）→ 使用目标 runtime 的 agent 配置机制
- 非 SKILL.md/Agent Skills 兼容的平台插件 → 使用该平台的原生插件规格
- 修改 npx 第三方 skill → fork 后新建（
npx skills update覆盖原地改动） - 缺必要输入（用户说不清要做什么）→ 列出缺什么并停，不硬编、不猜（9arm refuse to draft）
写法规则
Frontmatter
---
name: skill-name # kebab-case，与目录名一致
description: 功能描述。Use when 触发场景列举。 # ≤1024字符，第三人称
# version: 1.0 # 只在目标 runtime/项目 schema 允许时使用；laohan-local 要求
---
name + description 是 agent 路由 skill 的常驻元数据。description 必须含：
- 功能描述（一句话做什么）
- "Use when" + 足以区分近似 skill 的自然语言触发场景；3-8 个是 laohan-local 启发式，不是通用 schema 硬约束
- 第三人称（mattpocock）
- 如有竞争 skill，明确区分
正文写法
| 规则 | 说明 |
|---|---|
| 篇幅控制 | 以完整加载且没有冗余为准；尽量 <500 行，接近/超过时把长参考和详细 eval 流程拆到 references/ |
| 核心理念先行 | 3 步以上 skill 在工作流前加核心理念章节（先 why 后 how） |
| 工作流+操作规则分离 | 工作流=步骤序列；操作规则=跨步骤约束，独立章节 |
| 阶段门控 | 只在外部副作用、高风险或用户保留决策前设硬 gate；确定性内部步骤不加假 CHECKPOINT |
| 反模式 WRONG/RIGHT | 核心规则用对比块（❌差/✅好） |
| 口诀植入（verbatim） | 只在任务真的需要可背诵纪律时使用；不把 debug-mantra 形式套到所有 skill |
| 输出格式 | 用模板定义，不给模糊指令 |
| 降级级联 | 多方案用严格优先级（依次尝试），非菜单 |
| 跨 skill 调用 | 完成后 offer 衔接另一个 skill（不自动 handoff，9arm post-mortem） |
| 写作原则 | 祈使句 + 具体例子 + 不用 ALL CAPS ALWAYS/NEVER + 内容创作类定义语气 |
| scripts/ 判断 | 确定性操作/重复生成的相同代码/需显式错误处理 → scripts（mattpocock） |
| references/ 判断 | 平台专属方法/长模板/不需每次加载的背景知识 → references（仅一层深） |
渐进式披露（anthropics）：metadata（常驻）→ SKILL.md body（触发加载）→ bundled resources（按需）。SKILL.md 别一坨塞完，重的拆 references/scripts。
6 项极简自检清单（CREATE 后快速过）
- description 含 Use when + 触发词
- SKILL.md 尽量 <500 行；超过时必须拆 references，100-500 行按加载价值判断
- 无时效信息（具体日期/版本号除非必要）
- 术语一致
- 有具体例子
- references 仅一层深
验收与发布清单
创建/优化完成后：
- SKILL.md 写好，frontmatter 符合目标 runtime schema（通用最小集 name + description；laohan-local 另有 version）
- 目标 runtime/profile 已明确，安装路径或打包方式来自当前宿主规格
- 已记录本次模式；
AUDIT保持只读，SURGICAL_FIX没有升级成完整优化 - CREATE/OPTIMIZE 的触发、反触发与执行测试通过；SURGICAL_FIX 的针对性回归通过
- 重复工作检查（无每次生成的相同辅助代码）
- 只有 OPTIMIZE 或复杂/高影响 CREATE 才要求 held-out；主观对比才要求 blind judge
- runtime 扫描按 profile 运行；fatal 必须修复，portable 专属路径警告由人工判断是否已有 capability branch
- 修改本 Skill 自身时已运行
scripts/check-upstreams.sh，并按实际核验结果更新上游记录 - 安全检查通过（无 API key/个人绝对路径，发布动作有明确授权）
- 本地 commit、安装、package、push 和 publish 分开登记；本地 commit 遵循当前任务/仓库授权，安装、package、push 和 publish 仅在用户明确授权时执行