laohan-skillcreator · diff
v2 to v2.1
60 added, 61 removed. Audit A to A.
---
name: laohan-skillcreator
- version: 2.0
- description: 创建、优化、评分 Claude Code agent skills 的元 skill（三位一体）。创建从构思到发布全流程；6 维量化评分（frontmatter/工作流/失败模式/检查点/具体性/反例）；迭代优化只保留涨分改动。Use when 用户说"创建skill""写一个skill""新建skill""改skill""优化skill""给skill打分""评分""评估skill质量""skill体检""review skill"或提到 skill 创建/优化/评分相关任何意图。
+ version: 2.1
+ description: 创建、审计和优化 Agent Skills；按宿主能力选择 frontmatter/安装方式，用风险比例的静态评分、触发/执行测试与 held-out 验证只保留有效改动。Use when 用户说"创建skill""写一个skill""改skill""优化skill""给skill打分""skill体检""review skill"或要求验证 Skill 质量。
---
# laohan Skill 创建·优化·评分器
- v2.0 三位一体：**创建** skill → **评分** skill → **优化** skill。融合 4 个来源最佳实践。
+ v2.1 三位一体：**创建** skill → **评分** skill → **优化** skill。结构分只是诊断信号，最终接受条件是目标 runtime 下的真实任务表现不退化。
## 参考来源
融合 4 个来源（定期检查有无新 commit 可借鉴）：
1. **anthropics/skills · skill-creator**（https://github.com/anthropics/skills）
- 借鉴：渐进式披露（metadata→body→bundled 三层）、并行 spawn with/baseline 对比、盲比较、description 优化器、从 transcript 找重复工作、更新保持原名
- 核心理念：好的 skill 分三层渐进披露，不是一坨
2. **mattpocock/skills · write-a-skill**（https://github.com/mattpocock/skills）
- 借鉴：Use when 触发精准、阶段门控、WRONG/RIGHT 反模式块、6 项极简检查清单、第三人称描述、scripts 判断标准
- 核心理念：description 是 agent 看到的唯一东西，在与所有 installed skill 竞争
3. **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 要有引用
4. **alchaincyf/darwin-skill**（https://github.com/alchaincyf/darwin-skill）
- 借鉴：9 维评分体系、反例黑名单 8 条、棘轮机制（git ratchet）、独立子 agent 复评、人在回路 5 阶段
- - 核心理念：skill 质量可量化，只保留有改进的改动（SkillLens 实证 LLM 自评仅 46.4% 准确率）
+ - 核心理念：SkillLens 显示无 rubric 的 LLM 成对判断只有 46.4% 准确率，验证过的 meta-skill rubric 提升到 73.8%，仍不足以代替真实任务验证
---
## 核心理念
四原则：
1. **description 决定生死** — 触发精准度是一切前提。Claude 倾向欠触发，description 要主动推销
2. **结构引导行为** — 好骨架比好指令有效
3. **精简优于完整** — 每个章节都要证明存在的价值
- 4. **质量可量化**（v2 新）— skill 不是写完即可，要能评分 + 迭代改进
+ 4. **效果先于格式分** — 静态 rubric 用于发现问题；触发、执行、held-out 样本与用户验收决定是否保留改动
---
## 创建流程
### Step 0 · 先质疑意图（硬门控，scrutinize 模式）
- **新建前强制问三个问题，任何一问答 yes 就停下来不新建：**
+ **新建前强制检查三个问题；先用 catalog/项目证据自主回答，只有用户意图无法从对话确定时才询问：**
- 1. 能不能**扩展现有 skill**？（读 `~/.agents/skills/` 和 `~/.claude/skills/` 找重叠/可扩展的）
+ 1. 能不能**扩展现有 skill**？（从当前 runtime 的 available-skills catalog 和项目本地 skill 目录查重叠；不猜安装路径）
2. 能不能**不建**？（做 nothing 行不行？手动一次性操作够不够？）
3. 确认必须新建 → 进入 Step 1
**如果 1 或 2 答 yes → 告诉用户替代方案（扩展哪个 skill / 为什么不必建），不新建。**
### Step 1 · 捕获意图
从对话提取（或问用户）：
1. 这个 skill 让 agent 能做什么？
2. 什么时候触发？（用户会说什么关键词/什么场景？）
3. 期望输出格式？
4. 是否需要 scripts/ 或 references/ 子目录？
用户说不清 → 停下来，列出不明确的部分，等补充。**不要猜。**
### Step 2 · 调研
- 确认 Step 0 的"不能扩展已有"结论（再扫一遍 `~/.agents/skills/`）。如发现可扩展 → 回 Step 0。
+ 确认 Step 0 的"不能扩展已有"结论（重查 catalog 和当前项目）。如发现可扩展 → 回 Step 0。
- **完成条件：** 确认新建并说明理由
### Step 3 · 写 SKILL.md
按下方骨架模板和写法规则。先判断极简还是完整骨架，再填。
- - **完成条件：** frontmatter（name + version + description 含 "Use when"）+ 正文完整
+ - **完成条件：** frontmatter 符合目标 runtime 允许的 schema（Agent Skills 通用最小集是 name + description；laohan-local profile 另要求 version），正文与资源引用完整
### Step 4 · 测试迭代
- 1. 放入 `~/.agents/skills/<name>/`，symlink 到 `~/.claude/skills/<name>`
- 2. **触发测试**：新开对话说触发词，确认加载该 skill
- 3. **反触发测试**：说相似但无关的词，确认不误触发
- 4. **执行测试**：实际跑流程，验证输出
+ 1. 先在可写工作副本中测试；只在目标 runtime 要求安装才按其官方路径/打包方式安装，不自动建 symlink
+ 2. **触发测试**：对自动路由的 skill 跑至少 3 个 should-trigger 和 3 个近似 should-not-trigger；纯手动调用则记 `NOT_APPLICABLE`
+ 3. **执行测试**：确定性 skill 用可机械验证的输入/输出夹具；主观性 skill 用盲比和具体质量标准
+ 4. **held-out 验证**：至少保留 1 个未用于改稿的样本；新版只有在目标指标不退化时才接受
5. **重复工作检查**：读执行 transcript，若每次生成相同辅助代码 → 提取到 scripts/
6. 不通过 → 回 Step 3 改 → 重新测试
7. 3 轮未过 → 停，可能是结构问题不是小补，重审核心理念
- ### Step 5 · 6 维自评 + 发布
+ ### Step 5 · 评估 + 本地验收
- 1. 用下方 6 维评分卡自评（应 ≥80）
- 2. 🔴 **CHECKPOINT**：展示评分 + 安装清单 + 将推送的文件，**等用户说"推""确认""yes"再 push**
+ 1. 用下方 6 维评分卡做静态诊断。确定性 skill 由机械 verifier 评审 held-out；主观输出再由不知道改动方向的独立 judge 盲评
+ 2. 只在静态结构无阻断问题且 held-out 不退化时接受当前改动；接受后才允许本地 commit
+ 3. 🔴 **PUBLISH CHECKPOINT**：只有用户明确要求 push/publish/package/install 时才执行相应外部动作；创建或优化本身不隐含发布授权
---
## SKILL.md 骨架模板
不是每个 skill 都需完整骨架。Matt Pocock 证明 3-5 行指令式 skill 合法——逻辑简单到一句话说清，直接写指令，别为"专业"加多余章节。
**判断标准**：单步、无复杂条件分支（简单回退除外）、无角色区分 → 极简。多步/有条件分支/多角色 → 完整骨架。
### 极简示例（5 行）
```markdown
---
name: caveman
- version: 1.0
description: 极简回应模式，只输出关键信息。Use when 用户说"caveman mode""极简""少说废话""简短"。
---
所有回应控制在 3 句话以内。只给结论和关键依据，不解释过程。如果用户要求详细解释，恢复正常模式。
```
### 完整骨架模板（v2 升级）
```markdown
---
name: skill-name
- version: 1.0
description: 一句话说清做什么。Use when 用户说"触发词1""触发词2""触发词3"或提到[相关场景]。 # ≤1024字符，3-8触发词，第三人称
+ # version: 1.0 # 只在目标 runtime/profile 允许时加
---
# Skill 标题
一句话定位。
## 核心理念（复杂 skill 必加，简单可省）
为什么存在、遵循什么原则。先讲 why 再讲 how——比直接列步骤更有效。
## 工作流
### 1. [步骤名]
- 做什么
- **完成条件：** [怎么判断这步做完了]
- - **🔴 CHECKPOINT：** [关键决策点，停下来等用户确认]（v2：显性标记，非"建议"措辞）
+ - **🔴 CHECKPOINT：** [仅当该步有外部副作用、高风险或用户保留决策时填；否则删除]
- **🛑 STOP：** [强制停止条件]
### 2. [步骤名]
- 做什么
- - **失败处理（三段式 fallback，v2）：**
+ - **失败处理（只有存在复杂降级链时用三段式；单一安全 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](references/scoring-rubric.md)）。给任何 skill 打分：
| # | 维度 | 权重 | 评分标准 |
|---|------|------|---------|
- | 1 | **frontmatter 质量** | 10 | name 规范；description 含做什么+Use when+3-8 触发词；≤1024 字符；**无"灵活应用/根据情况判断"等空话尾巴** |
+ | 1 | **frontmatter 质量** | 10 | name/description 符合目标 runtime 的允许字段；description 同时说做什么与何时用。触发词数是启发式，不为凑 3-8 个堆词 |
| 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）显式列禁 |
+ | 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：可发布
+ - 85-100：静态结构可进入执行/held-out 验证，不等于可发布
- 70-84：需优化（找最低维改）
- <70：结构有问题，重审核心理念
---
## 优化流程
优化已有 skill（只改自研 laohan 系列；npx 第三方 fork 后改）：
- ### 1. 6 维评分（找最低维）
- - 主 agent 打分结构维度（1-6）
- - **扣分引行号**，输出评分卡 + 最弱维度
+ ### 1. 建立可比基线
+ - 主 agent 按 6 维找结构问题，**扣分引行号**
+ - 冻结基线 skill、目标 runtime、测试样本、评分器和成功指标；没有这些就不声称“优化”
- ### 2. 改最低维度（一轮一维，darwin 反例第 5 条）
- - 只改得分最低那一维，不动其他（多变量同变无法归因）
- - 改完 git commit
+ ### 2. 一轮一个因果假设
+ - 每轮只修复一个可检验的行为缺陷；同一根因涉及多个 rubric 维度时一次改完，不为“一轮一维”留下自相矛盾
+ - 在未提交工作副本中应用 bounded add/delete/replace，记录假设与改动预算
- ### 3. 独立复评（darwin 反例第 1 条：不自评）
- - **另起一个子 agent** 重新 6 维打分（避免"我刚改的肯定更好"乐观偏差，实证 46.4%）
- - 新分 > 旧分 → 保留；否则 → `git revert HEAD`（**不用 reset --hard**）
+ ### 3. 独立验证与 held-out gate
+ - 确定性 skill 用冻结的机械 verifier 比较基线/候选；主观输出由**不知道版本标签的 judge**盲比。只做静态审计时可用独立 judge 抓自相矛盾，但不把 73.8% 当绝对真值
+ - 候选只在预注册指标严格改善，或主指标持平且修复已证实高风险缺陷时接受；否则丢弃未提交改动
### 4. 棘轮轻量版
- - 改进才 commit，退步 revert，分数只升不降
- - 单轮涨幅 < 1 分 → 停手（见好就收，不凑分堆冗余，darwin 反例第 3 条）
+ - 验证通过后才 commit；如用户已授权且候选已被单独 commit，退步时用 `git revert`，不用破坏性 reset
+ - 连续 2 轮 held-out 无实质改善或一轮只提高格式分时停手
### 5. 深度优化路由（不在这做）
- 需要 dim8 实测（with_skill vs baseline 双跑）/ 棘轮多轮循环 / runtime 红灯 gate → **用 darwin-skill**（如已装 `npx skills add alchaincyf/darwin-skill`），或读 references/scoring-rubric.md 跑完整 9 维。
+ 需要大样本多轮优化时，读 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 软化措辞黑名单（v2 新，darwin）
+ ### dim5 软化措辞审查
- **禁用以下措辞**（出现 ≥3 处，dim5 扣 ≥3 分）：
+ **只审查可执行指令段**：以下措辞若代替了具体条件/动作，出现 ≥3 处时 dim5 扣 ≥3 分；引用、反例、用户输出或客观不确定性不计：
- "建议" / "可以考虑" / "根据情况" / "灵活把握" / "视情况而定" / "酌情" / "适当"
改用具体指令："做 X"（祈使句 + 具体参数/示例）。完整禁用词表见 references/blacklist-phrases.md。
### 反例黑名单（v2 新，darwin 8 条精简）
创建/优化时禁止：
- 1. **不自评自改** — 同一 session 又改又评有乐观偏差；评分必须 spawn 独立子 agent
- 2. **不用 `git reset --hard`** 回滚 — 用 `git revert HEAD`
+ 1. **不把自评当验收** — 同一 session 可做静态诊断；确定性候选接受需独立机械 verifier + held-out，主观候选需 blind judge + held-out
+ 2. **不先 commit 再评** — 先在工作副本比较；只在候选已单独 commit 且获授权时用 `git revert`
3. **不为凑分堆冗余** — 触顶（连续 2 轮 Δ<2 分）就停
- 4. **不跳过测试打分** — 没跑测试不算分
- 5. **一轮只改一维** — 多维同变无法归因
+ 4. **不把静态分冒充验收分** — 未跑测试可标 `STRUCTURE_ONLY` 做诊断；没有 baseline/with-skill/held-out 行为证据不得给 `ACCEPTED` 或发布结论
+ 5. **一轮只验一个行为假设** — 不用 rubric 分类强行切断同一根因
6. **不静默跳过异常** — fallback 失败必须先告知用户
---
## 不适用场景（refuse to draft，v2 升级为硬拒绝）
- - 创建 Claude Code **agent**（agent ≠ skill）→ 手动写 agent 配置
- - 非 Claude Code 平台插件 → 本 skill 只适用 SKILL.md 格式
+ - 创建 **agent**（agent ≠ skill）→ 使用目标 runtime 的 agent 配置机制
+ - 非 SKILL.md/Agent Skills 兼容的平台插件 → 使用该平台的原生插件规格
- 修改 **npx 第三方 skill** → fork 后新建（`npx skills update` 覆盖原地改动）
- **缺必要输入**（用户说不清要做什么）→ **列出缺什么并停**，不硬编、不猜（9arm refuse to draft）
---
## 写法规则
### Frontmatter
```yaml
---
name: skill-name # kebab-case，与目录名一致
- version: 1.0
description: 功能描述。Use when 触发场景列举。 # ≤1024字符，第三人称
+ # version: 1.0 # 只在目标 runtime/项目 schema 允许时使用；laohan-local 要求
---
```
- **description 是 agent 决定加载哪个 skill 的唯一依据**（mattpocock）。必须含：
+ **name + description 是 agent 路由 skill 的常驻元数据**。description 必须含：
1. 功能描述（一句话做什么）
- 2. "Use when" + 3-8 个触发词（用户会说的自然语言，不只技术术语）
+ 2. "Use when" + 足以区分近似 skill 的自然语言触发场景；3-8 个是 laohan-local 启发式，不是通用 schema 硬约束
3. 第三人称（mattpocock）
4. 如有竞争 skill，明确区分
### 正文写法
| 规则 | 说明 |
|------|------|
- | 篇幅控制 | <100 行单文件；100-500 考虑拆 references/；>500 必须拆（SKILL.md 只留工作流+规则）|
+ | 篇幅控制 | 以完整加载且没有冗余为准；尽量 <500 行，接近/超过时把长参考和详细 eval 流程拆到 references/ |
| 核心理念先行 | 3 步以上 skill 在工作流前加核心理念章节（先 why 后 how）|
| 工作流+操作规则分离 | 工作流=步骤序列；操作规则=跨步骤约束，独立章节 |
- | 阶段门控 | 关键步骤间硬停止："如果无法确定 X → 停下来" / 🔴 CHECKPOINT / 🛑 STOP |
+ | 阶段门控 | 只在外部副作用、高风险或用户保留决策前设硬 gate；确定性内部步骤不加假 CHECKPOINT |
| 反模式 WRONG/RIGHT | 核心规则用对比块（❌差/✅好）|
- | 口诀植入（verbatim） | 核心纪律用口诀：**首次响应输出一次、逐字不改写、用户说跳过则不输出但仍 silent apply**（9arm debug-mantra）|
+ | 口诀植入（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 项极简自检清单（创建后快速过，mattpocock）
- [ ] description 含 Use when + 触发词
- - [ ] SKILL.md < 100 行（或 >500 已拆 references）
+ - [ ] SKILL.md 尽量 <500 行；超过时必须拆 references，100-500 行按加载价值判断
- [ ] 无时效信息（具体日期/版本号除非必要）
- [ ] 术语一致
- [ ] 有具体例子
- [ ] 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）
+ - [ ] SKILL.md 写好，frontmatter 符合目标 runtime schema（通用最小集 name + description；laohan-local 另有 version）
+ - [ ] 目标 runtime/profile 已明确，安装路径或打包方式来自当前宿主规格
- [ ] 触发测试通过
- [ ] 反触发测试通过
- [ ] 执行测试通过
- [ ] 重复工作检查（无每次生成的相同辅助代码）
- - [ ] **6 维自评 ≥80**（v2 新）
- - [ ] runtime 红灯扫描通过（`bash scripts/redlight-scan.sh`，无硬编码平台绑定路径）
- - [ ] 推送安全检查（无硬编码绝对路径、无内部昵称、无 API key）
- - [ ] 复制到 laohan-skills 仓库（自研）+ git push
+ - [ ] 静态 6 维无阻断问题，且 held-out 机械 verifier/主观 blind judge 验证不退化
+ - [ ] runtime 扫描按 profile 通过（`bash <laohan-skillcreator-dir>/scripts/redlight-scan.sh --profile portable|local <skill-dir>`）
+ - [ ] 安全检查通过（无 API key/个人绝对路径，发布动作有明确授权）
+ - [ ] 本地 commit、安装、package、push 和 publish 分开登记；本地 commit 遵循当前任务/仓库授权，安装、package、push 和 publish 仅在用户明确授权时执行