zzz-od-dev-skill-guide

name	zzz-od-dev-skill-guide
description	当要创建 skill、编辑/修改 skill、写 SKILL.md、或问 skill 该放哪、带哪些文件、内容怎么写时用。英文:create/author/edit a skill、write SKILL.md、skill structure。仅创建/修改 skill 时用;使用已有 skill 不触发。

创建/修改项目 skill

本项目开发类 skill 用 zzz-od-dev- 前缀(使用类 zzz-od-)、放根 skills/、junction 到 .claude/skills/。创建或改 skill 时,下面 4 条硬规范必须满足。

硬规范

1. 必须有 design.md

每个 skill 目录下要有 design.md,记这个 skill 的设计与决策:为什么做、定位与边界、每条关键决策的理由、落点选择。

• 目的:后续修改时(人或智能体)知道当初为什么这么定,避免盲目改动破坏原意。
• 写「为什么这么决策」,不只是「是什么」。
• 边界:design.md 是给后续维护者的存档,不进智能体执行上下文 —— SKILL.md 不应写「见 design.md」让智能体去读它获取使用信息(命令 / 参数 / 接口);使用信息要么内联 SKILL.md,要么放 skill 目录内其他辅助文件(如 api_reference.md / 脚本)。design.md 只记「为什么这么设计」(决策 / 踩坑论据)。

2. 内容给智能体看(指令式)

SKILL.md 是智能体要执行的指令与判据,不是给人读的说明文档。

• 祈使句 + 判据(「先 X 再 Y」「若 Z 则 W」),不要叙述文档腔。
• frontmatter 的 description 只写何时用(触发条件),不写「做什么/怎么做」 —— 否则智能体照 description 行事、不读正文。

3. 自包含:分场景(独立发布 vs 项目内)

• 可引用其它 skill(写完整标识符含命名空间,如「按 superpowers:receiving-code-review 的方法」):用完整标识符,避免裸名解析不到。
• 引用 skill 目录外的文件,分场景:
  • 独立发布 skill(跨项目用):禁止外引(发布不含,目标环境可能不存在)。知识内联进 SKILL.md 或 skill 目录内辅助文件。
  • 项目内 dev skill(放项目 skills/,跟项目走、不独立发布)可引:runtime 资产路径(skill 要去读/写的操作对象:screen_info / application 源码 / docs/game 等,本项目必有、稳定)+ skill 目录内自带工具 / 辅助文件(自包含,随 skill 走,如归档脚本 convert_to_webp.py)。不可引:具体代码文件 / 实现行 / 易变文档(如某 devtools 模块 L640、「详见某 README」)—— 抽象化,不点具体位置。
  • 判据(分场景,非「所有路径都不写」):「skill 要读写的稳定操作对象 / 自带工具」可引;「只为佐证某约定的具体代码/文档位置(易变)」抽象化。
  • 有一类具体名可以写:框架地基级、几乎不改名的接口名。有些 skill(debug / 排查 bug / 迁移)的指令本身就是「在本项目代码里搜某个名 / 调某个接口」,比如要搜 @operation_node 装饰器看节点流转、要调 save_screenshot 截图、要提醒 analyze_screen 工具的结论会骗你 —— 这些名是指令的一部分(不是顺带举例),删了智能体就不会做了;且是框架地基级接口(整个节点系统就靠 @operation_node,改它等于重写框架,几乎不会发生)。这类名属上面「skill 要读写的稳定操作对象」,可以写进 SKILL.md。判一个名能不能写,问两点:
    1. 删掉它,智能体还能照做吗? —— 删了照样能做(名只是举例住在哪)→ 挪 design.md;删了就不会做了(名 = 指令本身)→ 看第 2 点。
    2. 它会不会经常变? —— 框架地基级、几乎不改名 → 可以写;容易变的(某测试 API、具体行号)→ 挪 design.md。
  • 能写就写全名,别改成模糊说法。可写进 SKILL.md 的接口名直接写完整名字(如「本项目用 @operation_node 装饰器声明节点流转」)—— 万一以后代码改名,全局一搜这名就发现 SKILL.md 这行也得跟着改,改没改一目了然。别反过来模糊成「节点声明装饰器」:代码改名后这种说法不报错、却已指错地方,谁都不会发现 —— 看着抽象好像更稳,其实更危险。

4. 写方法论,不写具体例子(限 SKILL.md 与智能体读的辅助文件)

写方法、原则、判据(怎么判断、怎么选),不要写「某个具体场景/项目的做法」。具体游戏事实(键位/坐标/具体流程/机制)归 doc 不归 skill;skill 只记方法论(分工见 doc_organization)。(注:框架接口名不归本条管 —— 那是规范 3「skill 要读写的稳定操作对象」,看规范 3 判据;本条只管具体游戏事实 / 项目例子。)

• 适用范围:SKILL.md 正文 + skill 目录内会被智能体读取的辅助文件(这些注入智能体执行上下文)。
• design.md 不在此列:它是给后续维护者的设计记录,可以有具体例子/踩坑作为决策论据。
• 理由:具体例子会以偏概全 —— 智能体把例子的偶然细节当成必然规则,套到不匹配的新场景。
• 抽象成判据:「在 X 条件下选 A,在 Y 条件下选 B」,而非「项目 P 里我们用了 A」。
• 不得不具体的,仅限纯语法/字段名(如 frontmatter 的 name+description、命令必填参数),给最小可用形式;「为什么选 A」「项目里遇过 X」这类划到 design.md。

落点(项目约定)

• 目录:根 skills/<dev-name>/(跨工具源,提交共享)。
• 前缀:开发类 zzz-od-dev-(项目开发流程类);使用类 zzz-od-。zzz-od- 兼项目命名空间,防和插件/个人 skill 撞名。
• Claude Code 发现:junction .claude/skills/<dev-name> → 根 skills/<dev-name>,形如 cmd /c mklink /J .claude\skills\<dev-name> skills\<dev-name>(Windows junction 免管理员;symlink 需特权)。junction 不提交(.claude/ 已 gitignore),每人本地建。
• 结构:SKILL.md(入口)+ design.md(设计决策)+ 按需辅助文件(必须在 skill 目录内)。

创建/修改流程

1. 定位:这个 skill 管什么、不管什么。和已有 skill(superpowers:*、本项目 zzz-od-dev-*)重叠的,引用而非重复。
2. 写 SKILL.md:frontmatter(name + description,description 只写触发)+ 指令式正文(方法论)。
3. 写 design.md:为什么做、定位边界、关键决策理由、落点。
4. 自检 4 条硬规范(逐条对照)+ 通读正文确认每条指令可执行。
5. junction 到 .claude/skills/,验证 skill 可被触发(按工具要求重载/重启)。
6. 提交 skills/<dev-name>/(junction 不提交)。

与 superpowers:writing-skills 的关系

通用 skill 结构、frontmatter 字段、description 触发优化(SDO)、token 效率、cross-reference 写法 —— 参考 superpowers:writing-skills(它讲得全,引用即可,本 skill 不重复)。 本 skill 只叠加项目特定部分:上面 4 条硬规范 + 落点。

两类 skill:RED 必要性不同,GREEN 始终必做

writing-skills 把 skill 创建当严格 TDD(必须先 baseline pressure-test 再写)。本项目按 skill 的内容依据分两类:

• 纠正型:改变智能体默认会做错的行为,内容依据是"baseline 暴露的 failure" → RED(baseline)必做,再写最小纠正。
• 方法论覆盖型:整合业界已验证的方法论成系统流程,内容依据是方法论本身 → RED 可省(团队工具/模型异构,单一 baseline 外部效度不足);但写完必须 GREEN 验证(跑 application 场景,确认用了 skill 的智能体决策/产出更系统)。

无论哪类,GREEN 验证不可省(writing-skills 的"写完要验证"对两类都成立);差异只在 RED 是否必须。 判断属于哪类:问"这条规范的依据,是'智能体默认会做错所以纠正',还是'业界方法论本来就该这么做'?"。前者纠正型,后者方法论型。zzz-od-dev-deciding-a-fix 是方法论型(锚定 RCA / Impact Analysis 等)。