📦 deps(skills): sync thirdparty skills

2026-08-12 12:41:45 +08:00
parent a0131f52c6
commit 073dac13a3
101 changed files with 5290 additions and 3529 deletions
@@ -0,0 +1,68 @@
+# Runtime 适配性审查（详细对照表 + 扫描命令）
+
+> SKILL.md 在「Runtime 适配性审查」章节会引用本文件。Phase 1 基线评估时跑红灯扫描需要查这里。
+
+---
+
+## 背景
+
+花叔的 skills 基于 Anthropic 开放的 [Agent Skills](https://agentskills.io) 协议，应当能在 Claude Code、Codex、Cursor、OpenClaw、Hermes Agent、CodeBuddy、Workbuddy、Gemini CLI、OpenCode 等 50+ skills-compatible runtime 上通用。
+
+这是 skill 分发力的根本——一个被误判为「单一 runtime 绑定」的 skill，会被其他 agent 直接拒绝安装（实例：nuwa-skill 因 README 写「在 Claude Code 里使用」被 Marvis agent 拒绝）。
+
+**适用范围**：除非 skill 名字明确声明绑定单一 runtime（如 `huashu-slides-codex`、`xxx-for-claude-code`），所有 skill 必须通过本审查。
+
+---
+
+## 红灯信号（出现即扣分，必须在 P0 优化轮修复）
+
+| 红灯类型 | 典型表现 | 危害 |
+|---|---|---|
+| Badge 钉死 | `[![Claude Code Skill]]`、`[![Cursor Only]]` 之类的单一 runtime badge | 视觉上首屏定调，其他 runtime 用户直接退出 |
+| 措辞钉死 | 「在 Claude Code 里」「Cursor 用户可以」「Codex 中使用」「Claude Code skill」 | 让 agent 解析时误判为"不是给我用的" |
+| 安装命令钉死 | 只给 `~/.claude/skills/` 路径、只给 `/plugin install`、只给某 runtime 私有 CLI | 不知道这是 Claude Code 命令的 agent 会拒绝 |
+| 工具调用钉死 | 工作流里硬编码 `mcp__claude-in-chrome__*`、`PostToolUse hook` 等单 runtime 能力，且不给替代方案 | 其他 runtime 没这些工具 → 流程跑不通 |
+| 路径硬编码 | `~/.claude/skills/xxx/`、`.claude/agents/yyy` 作为唯一路径 | 其他 runtime 用 `~/.cursor/skills/` `~/.codex/skills/` |
+
+---
+
+## 绿灯措辞（推荐改写）
+
+| 红灯 | 绿灯 |
+|---|---|
+| "在 Claude Code 里" | "在你的 agent 里" / "在任何 skills-compatible runtime 中" |
+| "Claude Code skill" | "Agent Skill" |
+| "Claude Code 用户" | "skills-aware agent 用户" |
+| 单一 badge 钉死 | `Agent Skills Standard` + `skills.sh Compatible` + `Multi-Runtime` 三个中立 badge |
+| 只给 `npx skills add ...` 一行 | 三层结构：① 自动检测的一行命令 ② 折叠展开的各 runtime 手动路径 ③ 「作为参考资料 cat 进 context」fallback |
+| 工具名硬编码 | "用一个 browser automation 工具（例如 Claude 的 chrome MCP、Playwright 等）" |
+
+---
+
+## 例外清单（允许的「Claude Code 痕迹」）
+
+不是所有 Claude-Code 相关字符都要清除。下面这些是**正当出现**的，不算红灯：
+
+1. **Frontmatter `description` 里的中英文触发词**——这是 skill 入口，其他 runtime 解析 frontmatter 时同样能匹配
+2. **花叔生态内部联动的 skill 名引用**——如「调用 huashu-design」「跟 darwin-skill 配套」
+3. **明确标注的 runtime-specific 章节**——如「### 仅 Claude Code 优化（按需触发）」+ 解释清楚是 nice-to-have
+4. **commit message、changelog、内部脚本**——不属于用户读到的 skill 内容
+
+---
+
+## 审查时机
+
+- **Phase 1 基线评估时**：每个 skill 跑一次红灯扫描，命中项以 `runtime_warn=N` 形式写入 results.tsv 的 `note` 列（不新增列、保持向后兼容）
+- **Phase 2 优化循环时**：红灯命中数 ≥ 1 的 skill，强制把第一轮优化方向定为 P0「runtime drift 修复」（详见 SKILL.md 优化策略库的 P0 章节），优先于其他维度
+- **Phase 3 汇总报告时**：单独一栏「runtime 中立度」展示修复进度（命中数从 X → 0）
+
+---
+
+## 红灯扫描快速命令
+
+```bash
+# 在 skill 目录跑这个 grep，输出即红灯命中
+grep -nE "(在 Claude Code|Claude Code skill|Claude Code 用户|Cursor only|Codex 中|^\[!\[Claude Code|~/\.claude/skills/[a-z]|/plugin install\b)" SKILL.md README.md 2>/dev/null
+```
+
+输出非空 = 该 skill 未通过 gate，必须在优化循环里修复。
@@ -0,0 +1,142 @@
+# SkillLens 实证基线 + darwin-skill 本机验证数据
+
+> SKILL.md 在「评估 Rubric」章节会引用本文件。需要查论文细节、controlled study 数据、HL 实战案例的具体数字时读这里。
+
+---
+
+## SkillLens 论文实证（外部证据）
+
+**论文**：From Raw Experience to Skill Consumption: A Systematic Study of Model-Generated Agent Skills
+**作者**：Microsoft Research + 复旦大学 + 上海交大（16 作者）
+**arXiv**：2605.23899（2026-05-22，与 SkillOpt 同期发布）
+**实验规模**：5 domains（ALFWorld / SpreadsheetBench / SWE-bench-Verified / SEAL-0 / BFCL-v4）× 6 targets × 5 extractors
+
+### 关键发现
+
+1. **75% 案例 skill 有正收益，25% 出现 negative transfer**——即「加 skill 比不加还差」
+2. **强 agent 不一定是好 extractor**（Gemini-3.1-FL 在 skill 提取效率上反超 GPT-5.4）
+3. **LLM-as-judge 准确率仅 46.4%**——给 LLM judge 两份 skill，让它选哪份更好，**比扔硬币（50%）还差**
+4. **meta-skill rubric 把准确率提升到 73.8%**——加入三个维度：
+   - **Failure-mechanism encoding**（必须显式编码失败模式）
+   - **Actionable specificity**（禁止"考虑/可能"软化措辞）
+   - **Risk-action blacklist**（必须有反例清单）
+5. 所有 domain 一致 +1.55pp 提升（meta-rubric 不是某个 domain 的特例）
+
+### 对 darwin-skill 的意义
+
+旧 8 维 rubric 全部由 LLM judge 打分 → 系统性乐观偏差 → 本机 results.tsv 早期 40 次 0 revert / 67% dry_run 印证。
+
+v2 9 维 rubric 强化 dim3/dim5 + 新增 dim9 是 SkillLens 验证过的方向。**但即使 73.8%，每 4 次决策仍错 1 次——重要决策必须人审确认。**
+
+---
+
+## 本机 controlled study（2026-05-27）
+
+### 实验设计
+
+- **目标 skill**：huashu-research（170 行，独立度高）
+- **V1**：当前 GitHub 仓库最新版（被 darwin-skill 优化过 +33 分的版本）
+- **V2 (degraded)**：在 V1 基础上应用 4 类明确质量劣化：
+  - **D1 模糊化具体指令**：「必须/立即」→「建议/可以根据情况」
+  - **D2 删除关键检查点**：删掉 2 个 🔴 检查点
+  - **D3 删掉异常处理表**：整段「## 异常处理」章节删除
+  - **D4 插入 AI 腔废话**：在 Step 2、Step 3 插入花叔禁用词 9 个套话
+- **5 个独立 judge agent**（general-purpose subagent，无 context 共享）盲测打分
+- 一半 judge 先读 V1 后读 V2，另一半反序（去除位置偏差）
+
+### 结果
+
+| Judge | 顺序 | V1 总分 | V2 总分 | Δ | Verdict | Confidence |
+|---|---|---|---|---|---|---|
+| 1 | V1 → V2 | 89.5 | 41.7 | **+47.8** | V1>V2 | high |
+| 2 | V2 → V1 | 90.2 | 46.7 | **+43.5** | V1>V2 | high |
+| 3 | V1 → V2 | 89.5 | 37.6 | **+51.9** | V1>V2 | high |
+| 4 | V2 → V1 | 89.5 | 48.4 | **+41.1** | V1>V2 | high |
+| 5 | V1 → V2 | 89.5 | 41.4 | **+48.1** | V1>V2 | high |
+| **均值** | — | **89.6** | **43.2** | **+46.5** | **5/5 V1>V2** | **5/5 high** |
+
+### 维度级共识
+
+| 维度 | V1 均值 | V2 均值 | Δ | 一致性 |
+|---|---|---|---|---|
+| 1. Frontmatter | 9.0 | 5.6 | -3.4 | 全部识别 |
+| 2. 工作流清晰度 | 9.0 | 5.0 | -4.0 | 全部识别 |
+| 3. 边界条件覆盖 | 9.2 | 3.4 | -5.8 | **最明显劣化** |
+| 4. 检查点设计 | 9.0 | 2.6 | -6.4 | **最明显劣化** |
+| 5. 指令具体性 | 9.0 | 3.6 | -5.4 | 全部识别 |
+| 6. 资源整合度 | 8.0 | 6.8 | -1.2 | 弱 |
+| 7. 整体架构 | 9.0 | 4.6 | -4.4 | 全部识别 |
+| 8. 实测表现 | 9.0 | 3.6 | -5.4 | 全部识别 |
+
+### 结论
+
+**rubric 能识别 gross degradation（5/5 high confidence）**，但**这不能证明 fine-grained quality difference 也能识别**——SkillLens 的 46.4% 来自细粒度对比，darwin-skill 在细粒度判别上仍有失效风险。**重要决策仍需人审。**
+
+---
+
+## HL 实战 high-leverage 案例（来自 results.tsv 真实记录）
+
+### HL-1：显性视觉标记是 dim4 的杠杆
+
+**huashu-gpt-image Round 1**：红线 4 标题前加 🔴 CHECKPOINT + 「禁止交付」→「🛑 STOP」
+- 改动：4 行
+- dim4 变化：6.0 → 9.5（+3.5）
+- 单维度 ROI：每行改动 +0.875 分
+
+**huashu-slide-codex r4**：路径优先级章节插入 🔴🔴🔴 默认路径锁定铁律
+- dim 总分 85 → 持平但避免了「Codex 自我合理化切 Path3 失败」实测翻车
+- 视觉锚是 LLM 解析的关键信号
+
+### HL-2：if-then 三段式 fallback 表
+
+**huashu-gpt-image Round 1**：新增「🛟 失败模式与 fallback 树」章节
+- 改动：3 张表 23 条三段式（触发条件 / 一线修复 / 仍失败兜底）
+  - 单图失败 9 条
+  - 批量生成 9 条
+  - 生成执行层 5 条
+- dim3 变化：6.5 → 10（满分）
+
+**huashu-weread-advisor edit-r2**：SKILL 加 11 行全局异常表 + 4 行数据展示规范 + 4 工作流各加 5-6 行 workflow 特有异常表
+- 共 ~33 个异常场景覆盖
+- dim 总分 81.3 → 87.6（+6.3）
+
+### HL-3：维度相关性（dim2/3/4 是相关簇）
+
+**huashu-gpt-image 实测**：
+- Round 1 攻 dim3（最低 6.5）→ 改成 10
+- 同期 dim2 自动从 7.5 → 9（未单独优化）
+- Round 2 试图单独攻 dim2 → 发现已触顶 9，多此一举
+- **教训**：找最低维度时同时看相关簇短板
+
+### HL-4：触顶后边际收益递减
+
+**huashu-gpt-image Round 2**：+0.15 marginal
+- Round 1: +10.7 分（基线 80.8 → 91.5）
+- Round 2: +0.15 分（91.5 → 91.65）
+- **触顶信号**：连续 2 轮 Δ < 2 → break，避免过度优化
+
+**对比 darwin-skill 早期**：40 次记录 0 revert，部分是因为没有触顶规则，硬凑 MAX_ROUNDS=3 都 keep 了边际改动。
+
+---
+
+## 历史 results.tsv 优化记录摘要（截至 2026-05-27）
+
+完整记录见 `results.tsv`。
+
+| skill | 起分 | 终分 | Δ | 模式 |
+|---|---|---|---|---|
+| huashu-research | 40.0 | 73.2 | +33.2 | dry_run |
+| huashu-video-check | 72.1 | 80.5 | +8.4 | dry_run |
+| harness-optimizer | 78.4 | 86.0 | +7.6 | dry_run |
+| freud-skill | 72.5 | 86.0 | +13.5 | dry_run |
+| **claude-design** | **74.5** | **91.0** | **+16.5** | **full_test ✅** |
+| huashu-design | 62.3 | 86.7 | +24.4 | dry_run |
+| huashu-weread-advisor | 76.5 | 91.4 | +14.9 | full_test_informed ✅ |
+| huashu-slide-codex | 82.6 | 85+ | +2~ | mixed |
+| **huashu-gpt-image** | **80.8** | **91.65** | **+10.85** | **full_test ✅（v2 实战）** |
+| **darwin-skill (self-fix)** | **86.05** | **92.05** | **+6.0** | **full_test ✅（自指闭环）** |
+
+**统计**：
+- 平均提升：~+13.5 分
+- 全部 keep（v1 时代 0 revert 印证 rubric 偏松；v2 引入触顶 break 规则）
+- full_test 比例：从 33% 提升到 100%（最近 2 次都是 full_test）