tomevault-io laohan Skill 创建·优化·评分器
v2.0 三位一体：创建 skill → 评分 skill → 优化 skill。融合 4 个来源最佳实践。
参考来源
融合 4 个来源（定期检查有无新 commit 可借鉴）：
anthropics/skills · skill-creator（https://github.com/anthropics/skills）
- 借鉴：渐进式披露（metadata→body→bundled 三层）、并行 spawn with/baseline 对比、盲比较、description 优化器、从 transcript 找重复工作、更新保持原名
- 核心理念：好的 skill 分三层渐进披露，不是一坨
mattpocock/skills · write-a-skill（https://github.com/mattpocock/skills）
- 借鉴：Use when 触发精准、阶段门控、WRONG/RIGHT 反模式块、6 项极简检查清单、第三人称描述、scripts 判断标准
- 核心理念：description 是 agent 看到的唯一东西，在与所有 installed 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（https://github.com/alchaincyf/darwin-skill）
- 借鉴：9 维评分体系、反例黑名单 8 条、棘轮机制（git ratchet）、独立子 agent 复评、人在回路 5 阶段
- 核心理念：skill 质量可量化，只保留有改进的改动（SkillLens 实证 LLM 自评仅 46.4% 准确率）
核心理念
四原则：
- description 决定生死 — 触发精准度是一切前提。Claude 倾向欠触发，description 要主动推销
- 结构引导行为 — 好骨架比好指令有效
- 精简优于完整 — 每个章节都要证明存在的价值
- 质量可量化（v2 新）— skill 不是写完即可，要能评分 + 迭代改进
创建流程
Step 0 · 先质疑意图（硬门控，scrutinize 模式）
新建前强制问三个问题，任何一问答 yes 就停下来不新建：
- 能不能扩展现有 skill？（读
~/.agents/skills/和~/.claude/skills/找重叠/可扩展的） - 能不能不建？（做 nothing 行不行？手动一次性操作够不够？）
- 确认必须新建 → 进入 Step 1
如果 1 或 2 答 yes → 告诉用户替代方案（扩展哪个 skill / 为什么不必建），不新建。
Step 1 · 捕获意图
从对话提取（或问用户）：
- 这个 skill 让 agent 能做什么？
- 什么时候触发？（用户会说什么关键词/什么场景？）
- 期望输出格式？
- 是否需要 scripts/ 或 references/ 子目录？
用户说不清 → 停下来，列出不明确的部分，等补充。不要猜。
Step 2 · 调研
确认 Step 0 的"不能扩展已有"结论（再扫一遍 ~/.agents/skills/）。如发现可扩展 → 回 Step 0。
- 完成条件： 确认新建并说明理由
Step 3 · 写 SKILL.md
按下方骨架模板和写法规则。先判断极简还是完整骨架，再填。
- 完成条件： frontmatter（name + version + description 含 "Use when"）+ 正文完整
Step 4 · 测试迭代
- 放入
~/.agents/skills/<name>/，symlink 到~/.claude/skills/<name> - 触发测试：新开对话说触发词，确认加载该 skill
- 反触发测试：说相似但无关的词，确认不误触发
- 执行测试：实际跑流程，验证输出
- 重复工作检查：读执行 transcript，若每次生成相同辅助代码 → 提取到 scripts/
- 不通过 → 回 Step 3 改 → 重新测试
- 3 轮未过 → 停，可能是结构问题不是小补，重审核心理念
Step 5 · 6 维自评 + 发布
- 用下方 6 维评分卡自评（应 ≥80）
- 🔴 CHECKPOINT：展示评分 + 安装清单 + 将推送的文件，等用户说"推""确认""yes"再 push
SKILL.md 骨架模板
不是每个 skill 都需完整骨架。Matt Pocock 证明 3-5 行指令式 skill 合法——逻辑简单到一句话说清，直接写指令，别为"专业"加多余章节。
判断标准：单步、无复杂条件分支（简单回退除外）、无角色区分 → 极简。多步/有条件分支/多角色 → 完整骨架。
极简示例（5 行）
---
name: caveman
version: 1.0
description: 极简回应模式，只输出关键信息。Use when 用户说"caveman mode""极简""少说废话""简短"。
---
所有回应控制在 3 句话以内。只给结论和关键依据，不解释过程。如果用户要求详细解释，恢复正常模式。
完整骨架模板（v2 升级）
---
name: skill-name
version: 1.0
description: 一句话说清做什么。Use when 用户说"触发词1""触发词2""触发词3"或提到[相关场景]。 # ≤1024字符，3-8触发词，第三人称
---
# Skill 标题
一句话定位。
## 核心理念（复杂 skill 必加，简单可省）
为什么存在、遵循什么原则。先讲 why 再讲 how——比直接列步骤更有效。
## 工作流
### 1. [步骤名]
- 做什么
- **完成条件：** [怎么判断这步做完了]
- **🔴 CHECKPOINT：** [关键决策点，停下来等用户确认]（v2：显性标记，非"建议"措辞）
- **🛑 STOP：** [强制停止条件]
### 2. [步骤名]
- 做什么
- **失败处理（三段式 fallback，v2）：**
| 触发条件 | 一线修复 | 仍失败兜底 |
|---------|---------|-----------|
| [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 含做什么+Use when+3-8 触发词；≤1024 字符；无"灵活应用/根据情况判断"等空话尾巴 |
| 2 | 工作流清晰度 | 20 | 编号步骤+明确完成条件+输入输出清晰 |
| 3 | 失败模式编码 ⭐ | 20 | 显式 if-then fallback（三段式表）；只写正向不写失败分支扣 ≥3 分 |
| 4 | 检查点设计 ⭐ | 15 | 关键决策有 🔴/🛑 显性标记；仅"建议/如果...可以考虑"措辞不算 |
| 5 | 可执行具体性 ⭐ | 25 | 有具体参数/格式/示例可直接执行；禁用"建议/可以考虑/根据情况/灵活把握/视情况而定"软化措辞（完整黑名单见 references/blacklist-phrases.md，出现 ≥3 处扣 ≥3 分） |
| 6 | 反例黑名单 ⭐ | 10 | 有"不要做什么"章节；危险动作（rm/reset --hard/force push）显式列禁 |
算分：每维 1-10 分，总分 = Σ(维度分/10 × 权重)，满分 100。
cite or it didn't happen（9arm）：每个扣分必须引用 SKILL.md 具体行号或段落原文。不允许泛泛"这里不够好"。
评分档位：
- 85-100：可发布
- 70-84：需优化（找最低维改）
- <70：结构有问题，重审核心理念
优化流程
优化已有 skill（只改自研 laohan 系列；npx 第三方 fork 后改）：
1. 6 维评分（找最低维）
- 主 agent 打分结构维度（1-6）
- 扣分引行号，输出评分卡 + 最弱维度
2. 改最低维度（一轮一维，darwin 反例第 5 条）
- 只改得分最低那一维，不动其他（多变量同变无法归因）
- 改完 git commit
3. 独立复评（darwin 反例第 1 条：不自评）
- 另起一个子 agent 重新 6 维打分（避免"我刚改的肯定更好"乐观偏差，实证 46.4%）
- 新分 > 旧分 → 保留；否则 →
git revert HEAD（不用 reset --hard）
4. 棘轮轻量版
- 改进才 commit，退步 revert，分数只升不降
- 单轮涨幅 < 1 分 → 停手（见好就收，不凑分堆冗余，darwin 反例第 3 条）
5. 深度优化路由（不在这做）
需要 dim8 实测（with_skill vs baseline 双跑）/ 棘轮多轮循环 / runtime 红灯 gate → 用 darwin-skill（如已装 npx skills add alchaincyf/darwin-skill），或读 references/scoring-rubric.md 跑完整 9 维。
操作规则
创建/优化/评分全程约束：
- 保持精简：写完逐条审查，删不影响输出的指令
- Lazy creation：有内容才建文件/目录，不先建空结构占位
- 通用化非过拟合：不为单个用例做小众调整
- 解释 why："因为 A 所以 B" 优于 "MUST 做 B"——LLM 聪明，给理由比硬规则有效（anthropics）
- 匹配目标用户语言：laohan 系列默认中文，技术术语保留英文
- 更新保持原名：installed 是
research-helper就输出同名，不是 v2（anthropics）
dim5 软化措辞黑名单（v2 新，darwin）
禁用以下措辞（出现 ≥3 处，dim5 扣 ≥3 分）：
- "建议" / "可以考虑" / "根据情况" / "灵活把握" / "视情况而定" / "酌情" / "适当"
改用具体指令："做 X"（祈使句 + 具体参数/示例）。完整禁用词表见 references/blacklist-phrases.md。
反例黑名单（v2 新，darwin 8 条精简）
创建/优化时禁止：
- 不自评自改 — 同一 session 又改又评有乐观偏差；评分必须 spawn 独立子 agent
- 不用
git reset --hard回滚 — 用git revert HEAD - 不为凑分堆冗余 — 触顶（连续 2 轮 Δ<2 分）就停
- 不跳过测试打分 — 没跑测试不算分
- 一轮只改一维 — 多维同变无法归因
- 不静默跳过异常 — fallback 失败必须先告知用户
不适用场景（refuse to draft，v2 升级为硬拒绝）
- 创建 Claude Code agent（agent ≠ skill）→ 手动写 agent 配置
- 非 Claude Code 平台插件 → 本 skill 只适用 SKILL.md 格式
- 修改 npx 第三方 skill → fork 后新建（
npx skills update覆盖原地改动） - 缺必要输入（用户说不清要做什么）→ 列出缺什么并停，不硬编、不猜（9arm refuse to draft）
写法规则
Frontmatter
---
name: skill-name # kebab-case，与目录名一致
version: 1.0
description: 功能描述。Use when 触发场景列举。 # ≤1024字符，第三人称
---
description 是 agent 决定加载哪个 skill 的唯一依据（mattpocock）。必须含：
- 功能描述（一句话做什么）
- "Use when" + 3-8 个触发词（用户会说的自然语言，不只技术术语）
- 第三人称（mattpocock）
- 如有竞争 skill，明确区分
正文写法
| 规则 | 说明 |
|---|---|
| 篇幅控制 | <100 行单文件；100-500 考虑拆 references/；>500 必须拆（SKILL.md 只留工作流+规则） |
| 核心理念先行 | 3 步以上 skill 在工作流前加核心理念章节（先 why 后 how） |
| 工作流+操作规则分离 | 工作流=步骤序列；操作规则=跨步骤约束，独立章节 |
| 阶段门控 | 关键步骤间硬停止："如果无法确定 X → 停下来" / 🔴 CHECKPOINT / 🛑 STOP |
| 反模式 WRONG/RIGHT | 核心规则用对比块（❌差/✅好） |
| 口诀植入（verbatim） | 核心纪律用口诀：首次响应输出一次、逐字不改写、用户说跳过则不输出但仍 silent apply（9arm debug-mantra） |
| 输出格式 | 用模板定义，不给模糊指令 |
| 降级级联 | 多方案用严格优先级（依次尝试），非菜单 |
| 跨 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 项极简自检清单（创建后快速过，mattpocock）
- description 含 Use when + 触发词
- SKILL.md < 100 行（或 >500 已拆 references）
- 无时效信息（具体日期/版本号除非必要）
- 术语一致
- 有具体例子
- references 仅一层深
安装清单
创建/优化完成后：
- SKILL.md 写好，frontmatter 含 name + version + description（含 Use when）
- 目录在
~/.agents/skills/<name>/ - symlink:
ln -s ~/.agents/skills/<name> ~/.claude/skills/<name>（自研 skill 用 symlink→git仓库，见 rules/skills.md v1.3） - 触发测试通过
- 反触发测试通过
- 执行测试通过
- 重复工作检查（无每次生成的相同辅助代码）
- 6 维自评 ≥80（v2 新）
- runtime 红灯扫描通过（
bash scripts/redlight-scan.sh，无硬编码平台绑定路径） - 推送安全检查（无硬编码绝对路径、无内部昵称、无 API key）
- 复制到 laohan-skills 仓库（自研）+ git push
Source: hanzhcn/laohan-skills — distributed by TomeVault.