Selaa lähdekoodia

optimize darwin-skill: add Runtime 适配性审查 gate

New gate item (independent of the 8-dim rubric) ensures skills remain
portable across Claude Code, Codex, Cursor, OpenClaw, Hermes Agent,
CodeBuddy, Workbuddy, Gemini CLI, OpenCode and other skills-compatible
runtimes — unless the skill is explicitly bound to a single runtime
(e.g. xxx-codex / huashu-slides-codex).

- Add 红灯/绿灯/例外 checklists for runtime drift
- Add quick grep command for red-flag scanning
- Add P0 priority for runtime drift fixes (must precede other dimensions)
- Add constraint #8 (Runtime 中立性) to the rules section

Motivation: nuwa-skill's previous README pinned "Claude Code Skill"
framing and was rejected by other agents (e.g. Marvis). All 15 repos
(nuwa-skill + 13 person skills + x-mentor-skill) have since been
rewritten runtime-neutral; this gate codifies the lesson into darwin
so future audits catch the same pattern.
alchain 1 kuukausi sitten
vanhempi
sitoutus
0f647a3af1
1 muutettua tiedostoa jossa 63 lisäystä ja 1 poistoa
  1. 63 1
      SKILL.md

+ 63 - 1
SKILL.md

@@ -65,6 +65,59 @@ autoresearch 的精髓:
 
 ---
 
+## Runtime 适配性审查(gate 项,独立于 8 维度评分)
+
+**背景**:花叔的 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 都必须通过本审查。
+
+### 红灯信号(出现即扣分,且必须在优化循环里修复)
+
+| 红灯类型 | 典型表现 | 危害 |
+|---|---|---|
+| 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 修复」(详见 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,必须在优化循环里修复。
+
+---
+
 ## 自主优化循环
 
 ### Phase 0: 初始化
@@ -245,6 +298,13 @@ timestamp	commit	skill	old_score	new_score	status	dimension	note	eval_mode
 
 按优先级排序,每轮只做最高优先级的一个:
 
+### P0: Runtime 适配性问题(gate 项命中 → 必须先修)
+- README/SKILL.md 出现红灯措辞(如「在 Claude Code 里」「Claude Code skill」)→ 替换为 runtime-neutral 措辞
+- Badge 钉死单一 runtime → 改为 `Agent Skills Standard` + `skills.sh` + `Multi-Runtime` 三个中立 badge
+- 安装章节只给一种 runtime 的路径 → 改为「一行命令(auto-detect)+ 手动路径表 + 作为参考资料」三层结构
+- 工作流硬编码 runtime-specific 工具且无 fallback → 给出通用替代方案或标注「仅在某 runtime 可用」
+- 例外:skill 名明确标注单 runtime(如 `xxx-codex`)的,可跳过本项
+
 ### P0: 效果问题(实测发现的)
 - 测试输出偏离用户意图 → 检查skill是否有误导性指令
 - 带skill比不带还差 → skill可能过度约束,考虑精简
@@ -297,6 +357,7 @@ timestamp	commit	skill	old_score	new_score	status	dimension	note	eval_mode
 5. **尊重花叔风格** — 中文为主、简洁为上
 6. **可回滚** — 所有改动在git分支上,用git revert而非reset --hard
 7. **评分独立性** — 效果维度必须用子agent或至少干跑验证,不能在同一上下文里「改完直接评」
+8. **Runtime 中立性** — skill 必须能在 Claude Code、Codex、Cursor、OpenClaw、Hermes 等任何 skills-compatible runtime 中正常运行。除非 skill 名明确绑定单一 runtime(如 `xxx-codex`、`huashu-slides-codex`),任何「在 Claude Code 里」「Claude Code skill」「单一 badge 钉死」「安装命令只给 `.claude/skills/` 一种路径」都视为 gate 不通过,须在 P0 优先修复(详见「Runtime 适配性审查」章节)
 
 ---
 
@@ -373,7 +434,8 @@ timestamp	commit	skill	old_score	new_score	status	dimension	note	eval_mode
    - data-field="date" → 当前日期
 3. 随机选择风格:hash 设为 swiss/terminal/newspaper 之一
 4. 用 scripts/screenshot.mjs 截图(2x 高清,只截 .card 元素,自动 open 图片):
-   node scripts/screenshot.mjs /abs/path/to/card.html /abs/path/to/output.png
+   node .claude/skills/darwin-skill/scripts/screenshot.mjs \
+     /abs/path/to/card.html /abs/path/to/output.png
    # 回退方案(脚本失败时):
    npx playwright screenshot "file:///path/to/card.html#[theme]" \
      output.png --viewport-size=960,1280 --wait-for-timeout=2000