geekx-skills: Instructions file for Codex

智能体指令

适用范围

这些指令适用于整个仓库。

仓库规则

• skills/ 下的每个技能目录都必须以 geekx- 开头。
• 每个技能目录都必须包含 SKILL.md。
• 每个 SKILL.md 的 name 字段必须与目录名一致。
• 每个技能都必须包含 skills/<skill-name>/evals/evals.json。
• 技能文件必须聚焦。只有当 references/ 或 scripts/ 能减少重复工作时才添加。
• 除非技能本身明确绑定某个运行时，否则不要加入运行时专属措辞。
• SKILL.md 的描述、正文和评测说明默认使用中文；目录名、name、命令、工具名和固定协议值保持原样。
• 不要添加 review、writer、scope-review 这类泛名。

技能创建规则

每次新增或修改技能，都必须使用 skill-creator 工作流：

1. 明确技能意图、触发条件、预期输出和成功标准。
2. 写出最小可用的 SKILL.md。
3. 在认为技能完成前，添加真实可用的评测提示。
4. 尽量让评测预期可检查。
5. 保持技能正文简洁，把厚重材料移到 references/。
6. 新增、删除或改名技能时，同步更新 README 的「可用技能」表格。

缺少评测提示的技能不能合并。

Darwin 审查规则

发布前，以及每次有实质性技能改动后，都必须使用 darwin-skill 审查纪律：

1. 执行运行时中立性扫描。
2. 从 frontmatter、工作流清晰度、失败分支、检查点、具体性、资源集成、架构、真实输出风险、反模式覆盖等维度评分。
3. 先修复 P0 级运行时漂移，再做其他优化。
4. 每次编辑优先只改进一个维度。
5. 当技能可能被拉偏时，添加明确失败分支。
6. 根据验证结果保留或回滚，不根据个人偏好判断。
7. 当下一次编辑只是在加字、没有改善行为时停止。

文档规则

• README 和技能文档必须简洁。
• README 默认使用中文；品牌名、命令、链接和机器标识保持原样。
• 删除泛泛而谈的宣传、填充语和自我解释。
• 优先写可执行命令和硬约束，少写解释。
• 版本号以 package.json 为唯一来源；根目录 VERSION 必须与其一致。
• 每次发布都必须更新 CHANGELOG.md。
• 发布流程只放在 AGENTS.md，README 只面向使用者。

可视化进度大盘与状态同步

• 对多步骤、跨阶段，或需要用户持续掌握全局的任务，维护一个可直接在浏览器打开的单文件 HTML 进度大盘；优先自包含、离线可用，不要求额外构建步骤。
• 大盘以阅读体验和直观表达为先：少字去噪，优先使用任务看板、图表、流程图和适量 SVG。只有确实能降低理解或决策成本时才添加可视化。
• 看板应能点击查看任务详情，明确展示规划中、进行中、已完成、阻塞等状态；让用户快速看懂进度、风险、验证情况和下一步。
• 每次阶段性任务完成后，及时更新同一份大盘和当天进展；不要等到整个项目结束才补写。无需为每个微小动作重复创建页面。
• 大盘中的状态必须与真实代码、交付物和验证结果一致。重要任务应附可追溯证据，例如文件、测试结果、提交、PR 或报告链接；明确区分已实现与已验证。
• 当需求、优先级、技术路线或范围发生变化时，同步更新持久化开发计划和大盘，并记录变更内容、原因、影响、决策依据及后续动作。
• 计划用于记录完整决策与工作状态，大盘用于快速掌握全局；两者必须保持一致。出现冲突时，先核对仓库现实和最新证据，再校准计划与大盘。
• 简单、一次性且无需持续跟踪的任务不必强行制作大盘。

文档防漂移规则

• README 的「可用技能」表格必须与 skills/ 目录一致。
• README 不要写死当前版本号、发布步骤、标签命令或内部审查流程。
• AGENTS 是维护者规则的唯一入口；不要把同一条发布规则复制到 README。
• CHANGELOG.md 只记录真实历史变更，不为了“当前命名”改写旧版本事实。
• VERSION、package.json 和 package-lock.json 的版本号必须一致。
• 改名技能时，必须同时更新目录名、SKILL.md 的 name、evals/evals.json 的 skill_name、README 表格和变更日志。
• 每次文档或技能改动后，至少运行 npm run check:release。

发布流程

每次发布前都必须执行以下流程：