project-skill-audit

项目技能审计

概述

在推荐技能之前，先审计项目中真实且反复出现的工作流。优先依据记忆、运行摘要、现有技能目录和当前仓库惯例，而不是泛泛构思。

如果现有项目技能已接近所需行为，应优先建议更新，而不是新增技能。

工作流

1. 梳理当前项目情况。 找出仓库根目录，并优先阅读最相关的项目指导文件，例如 AGENTS.md、README.md、路线图／台账文件，以及定义工作流或验证预期的本地文档。

2. 先建立记忆／会话路径。 若已设置 $CODEX_HOME，则将其用作记忆根目录；否则默认为 ~/.codex。 使用以下位置：

   • 记忆索引：$CODEX_HOME/memories/MEMORY.md 或 ~/.codex/memories/MEMORY.md
   • 运行摘要：$CODEX_HOME/memories/rollout_summaries/
   • 原始会话：$CODEX_HOME/sessions/ 或 ~/.codex/sessions/

3. 按以下顺序读取项目过往会话。 如果运行时提示中已包含记忆摘要，则从该摘要开始。 然后在 MEMORY.md 中搜索：

   • 仓库名称
   • 仓库基本名称
   • 当前 cwd
   • 重要模块或文件名称 首先仅打开最相关的 1-3 份运行摘要。 只有当摘要缺少所需的确切证据时，才回退到原始会话 JSONL。

4. 在提出任何新建议之前，先扫描现有的项目本地技能。 检查相对于当前仓库根目录的以下位置：

   • .agents/skills
   • .codex/skills
   • skills 如存在 SKILL.md 和 agents/openai.yaml，请同时阅读。

5. 将项目本地技能与重复出现的工作进行对比。 在过往会话中查找重复模式：

   • 重复的验证步骤
   • 重复的失败防护措施
   • 反复出现的职责边界
   • 重复的根因类别
   • 反复需要相同仓库专属上下文的工作流 如果某种模式反复出现且尚未得到充分体现，它就是候选技能。

6. 区分「新建技能」与「更新现有技能」。 如果现有技能已属于合适的类别，但触发条件过时、缺少防护措施、路径已过期、验证说明不足或范围不完整，则建议更新。 只有当工作流足够独特，若强行纳入现有技能会使其变得含糊或令人困惑时，才建议新建技能。

7. 仅在审查项目本地技能之后，才检查与全局技能的重叠。 使用 $CODEX_HOME/skills 和 $CODEX_HOME/skills/public，避免为已有通用共享技能妥善解决的工作流提出项目本地技能。 不要仅仅因为存在全局技能就否决项目本地技能；项目专属防护措施仍可能足以证明需要本地专用版本。

会话分析

1. 先搜索记忆索引

• 使用 rg 在 MEMORY.md 中搜索仓库名称、基本名称和 cwd。
• 优先选择引用了相同仓库路径运行摘要的条目。
• 记录：
  • 重复出现的工作流
  • 验证命令
  • 失败防护措施
  • 职责边界
  • 与里程碑或路线图的关联

2. 打开目标运行摘要

• 打开 memories/rollout_summaries/ 下最相关的摘要文件。
• 优先选择文件名、cwd 或 keywords 与当前项目匹配的摘要。
• 提取：
  • 用户反复提出的要求
  • 反复出现的步骤
  • 反复发生的问题
  • 能证明正确性的命令
  • 必须重新查找的项目专属上下文

3. 仅在必要时使用原始会话

• 只有当运行摘要缺少具体细节时，才搜索 sessions/ 下的 JSONL 文件。
• 按以下内容搜索：
  • 完整的 cwd
  • 仓库基本名称
  • 运行摘要中的线程 ID
  • 特定文件路径或命令
• 使用原始会话找回确切提示、命令序列、差异内容或错误文本，而不是用它替代摘要审阅。

4. 将会话证据转化为技能候选项

• 候选的 new skill 应对应反复出现的工作流，而不只是反复出现的主题。
• 候选的 skill update 应对应某项本地技能已覆盖的工作流，但该技能的触发条件、防护措施或验证说明已不再符合记录的会话。
• 优先采用具体证据，例如：
  • “这一验证流程出现在 4 次会话中”
  • “提取器和运行时修复中反复出现了相同的所有权归属混淆”
  • “同一个本地脚本和遥测探针不得不反复重新查找”

建议规则

• 在以下情况下建议创建新技能：

  • 同一个特定于仓库的工作流或故障模式在多个会话中反复出现
  • 成功依赖于特定于项目的路径、脚本、所有权规则或验证步骤
  • 工作流能从强默认设置或防故障措施中受益

• 在以下情况下建议更新技能：

  • 现有项目本地技能已经覆盖了大部分需求
  • SKILL.md 和 agents/openai.yaml 彼此不一致
  • 路径、脚本、验证命令或里程碑引用已过时
  • 技能正文过于笼统，未能反映项目的实际工作方式

• 在以下情况下不要建议创建技能：

  • 模式是一次性错误，而非可复用的工作流
  • 通用全局技能已经足够，无需添加有意义的项目特定内容
  • 工作流尚未反复到足以证明其维护成本合理

扫描内容

• 过往会话和记忆：

  • 当前上下文中已有的记忆摘要（如果有）
  • $CODEX_HOME/memories/MEMORY.md 或 ~/.codex/memories/MEMORY.md
  • 与当前仓库最相关的 1-3 份 rollout 摘要
  • 仅在摘要信息不足时，才查看原始 $CODEX_HOME/sessions 或 ~/.codex/sessions JSONL 文件

• 项目本地技能范围：

  • ./.agents/skills/*/SKILL.md
  • ./.agents/skills/*/agents/openai.yaml
  • ./.codex/skills/*/SKILL.md
  • ./skills/*/SKILL.md

• 项目约定：

  • AGENTS.md
  • README.md
  • 路线图、账本、架构或验证文档
  • 如有需要，可查看当前工作树或近期改动的区域以了解背景

输出要求

返回一份精简的审查报告，包含：

1. Existing skills 列出找到的项目本地技能及其覆盖的主要工作流。

2. Suggested updates 对每个更新候选项，说明：

   • 技能名称
   • 它不完整或已过时的原因
   • 最有价值的改进内容

3. Suggested new skills 对每个新技能，说明：

   • 建议的技能名称
   • 创建它的原因
   • 哪些情况会触发它
   • 它应编码的核心工作流

4. Priority order 按预期价值对优先建议进行排序。

命名指南

• 优先使用简短的连字符命名。
• 如果有助于明确区分，项目本地技能应使用项目名前缀。
• 优先使用以动词开头或面向行动的名称，避免含义模糊的名词。

防故障措施

• 没有会话或仓库证据时，不要臆造反复出现的模式。
• 如果更新现有技能即可满足需求，不要建议创建重复技能。
• 如果当前仓库显然已发生变化，不要只依赖单条记忆记录。
• 不要批量加载所有 rollout 摘要；应有针对性地查看。
• 不要跳过 rollout 摘要，直接查看原始会话，除非摘要信息不足。
• 不要仅凭主题建议创建技能；建议应源自反复出现的流程、验证步骤或故障模式。
• 不要将项目当前的实现任务与可复用的技能需求混为一谈。

后续操作

如果用户要求实际创建或更新某项建议的技能，请切换到 $skill-creator，并着手实现所选技能，而不是继续进行审查。