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. 将会话证据转化为技能候选

• 候选「新建技能」应对应重复的工作流，而非仅仅是重复的话题。
• 候选「技能更新」应对应已被本地技能覆盖的工作流，但其触发器、防护措施或验证指令已不再匹配记录的会话。
• 优先选择具体证据，例如：
  • "这个验证序列出现在 4 个会话中"
  • "这种职责混淆在提取器和运行时修复中反复出现"
  • "相同的本地脚本和遥测探针不得不反复重新发现"

推荐规则

• 以下情况推荐新建技能：

  • 相同的仓库特定工作流或失败模式在多个会话中多次出现
  • 成功依赖于项目特定的路径、脚本、所有权规则或验证步骤
  • 工作流受益于强默认值或失败防护

• 以下情况推荐更新：

  • 现有项目本地技能已覆盖大部分需求
  • SKILL.md 和 agents/openai.yaml 之间存在偏差
  • 路径、脚本、验证命令或里程碑引用已过时
  • 技能正文过于通用，无法反映项目的实际工作方式

• 以下情况不推荐技能：

  • 该模式是一次性 bug 而非可复用的工作流
  • 通用全局技能已适用，且无有意义的项目特定补充
  • 工作流重现次数不足以证明维护成本合理

扫描范围

• 历史会话和记忆：

  • 上下文中已有的记忆摘要（如有）
  • $CODEX_HOME/memories/MEMORY.md 或 ~/.codex/memories/MEMORY.md
  • 当前仓库最相关的 1-3 个发布摘要
  • 仅在摘要不足时使用原始 $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. 已有技能 列出发现的项目本地技能及其覆盖的主要工作流。

2. 建议更新 对每个更新候选，包含：

   • 技能名称
   • 为何不完整或过时
   • 最有价值的改动

3. 建议新建技能 对每个新技能，包含：

   • 推荐的技能名称
   • 为何应该存在
   • 什么条件会触发它
   • 它应编码的核心工作流

4. 优先级排序 按预期价值对首要推荐进行排序。

命名指导

• 优先使用简短的连字符命名。
• 当有助于清晰度时，为项目本地技能使用项目前缀。
• 优先使用动词引导或面向动作的名称，而非模糊的名词。

失败防护

• 不要在没有会话或仓库证据的情况下编造重复模式。
• 当更新现有技能就足够时，不要推荐重复技能。
• 如果当前仓库自那时起已明显演进，不要依赖单一记忆条目。
• 不要批量加载所有发布摘要；保持针对性。
• 除非摘要不足，否则不要跳过发布摘要直接使用原始会话。
• 不要仅从主题出发推荐技能；推荐应来自重复的流程、重复的验证流或重复的失败模式。
• 不要将项目的当前实现任务与其可复用的技能需求混淆。

后续操作

如果用户要求实际创建或更新推荐的技能之一，切换到 $skill-creator 实现所选技能，而非继续审计。

局限性

• 仅当任务明确匹配上述范围时才使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，停下来请求澄清。