project-skill-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Skill Audit

项目技能审计

Overview

概述

Audit the project's real recurring workflows before recommending skills. Prefer evidence from memory, rollout summaries, existing skill folders, and current repo conventions over generic brainstorming.

Recommend updates before new skills when an existing project skill is already close to the needed behavior.

在推荐技能前，先审计项目中实际重复出现的工作流。优先参考来自内存、部署总结、现有技能文件夹及当前仓库约定的证据，而非通用头脑风暴。

当现有项目技能已接近所需行为时，优先推荐更新而非创建新技能。

Workflow

工作流

Map the current project surface. Identify the repo root and read the most relevant project guidance first, such as
```
AGENTS.md
```
,
```
README.md
```
, roadmap/ledger files, and local docs that define workflows or validation expectations.
Build the memory/session path first. Resolve the memory base as
```
$CODEX_HOME
```
when set, otherwise default to
```
~/.codex
```
. Use these locations:
- memory index:
```
$CODEX_HOME/memories/MEMORY.md
```
  or
```
~/.codex/memories/MEMORY.md
```
- rollout summaries:
```
$CODEX_HOME/memories/rollout_summaries/
```
- raw sessions:
```
$CODEX_HOME/sessions/
```
  or
```
~/.codex/sessions/
```
Read project past sessions in this order. If the runtime prompt already includes a memory summary, start there. Then search
```
MEMORY.md
```
for:
- repo name
- repo basename
- current
```
cwd
```
- important module or file names Open only the 1-3 most relevant rollout summaries first. Fall back to raw session JSONL only when the summaries are missing the exact evidence you need.
Scan existing project-local skills before suggesting anything new. Check these locations relative to the current repo root:
- ```
.agents/skills
```
- ```
.codex/skills
```
- ```
skills
```
  Read both
```
SKILL.md
```
  and
```
agents/openai.yaml
```
  when present.
Compare project-local skills against recurring work. Look for repeated patterns in past sessions:
- repeated validation sequences
- repeated failure shields
- recurring ownership boundaries
- repeated root-cause categories
- workflows that repeatedly require the same repo-specific context If the pattern appears repeatedly and is not already well captured, it is a candidate skill.
Separate
```
new skill
```
from
```
update existing skill
```
. Recommend an update when an existing skill is already the right bucket but has stale triggers, missing guardrails, outdated paths, weak validation instructions, or incomplete scope. Recommend a new skill only when the workflow is distinct enough that stretching an existing skill would make it vague or confusing.
Check for overlap with global skills only after reviewing project-local skills. Use
```
$CODEX_HOME/skills
```
and
```
$CODEX_HOME/skills/public
```
to avoid proposing project-local skills for workflows already solved well by a generic shared skill. Do not reject a project-local skill just because a global skill exists; project-specific guardrails can still justify a local specialization.

映射当前项目范围。识别仓库根目录，首先阅读最相关的项目指南，例如
```
AGENTS.md
```
、
```
README.md
```
、路线图/分类账文件，以及定义工作流或验证预期的本地文档。
先构建内存/会话路径。当
```
$CODEX_HOME
```
已设置时，将其作为内存基础，否则默认使用
```
~/.codex
```
。使用以下位置：
- 内存索引：
```
$CODEX_HOME/memories/MEMORY.md
```
  或
```
~/.codex/memories/MEMORY.md
```
- 部署总结：
```
$CODEX_HOME/memories/rollout_summaries/
```
- 原始会话：
```
$CODEX_HOME/sessions/
```
  或
```
~/.codex/sessions/
```
按以下顺序读取项目过往会话。如果运行时提示已包含内存总结，从该总结开始。然后在
```
MEMORY.md
```
中搜索：
- 仓库名称
- 仓库基础名称
- 当前
```
cwd
```
- 重要模块或文件名首先仅打开1-3个最相关的部署总结。仅当总结缺少你需要的准确证据时，才回退到原始会话JSONL文件。
在提出任何新建议前，先扫描现有项目本地技能。检查相对于当前仓库根目录的以下位置：
- ```
.agents/skills
```
- ```
.codex/skills
```
- ```
skills
```
  若存在
```
SKILL.md
```
  和
```
agents/openai.yaml
```
  ，均需阅读。
对比项目本地技能与重复工作内容。查找过往会话中的重复模式：
- 重复的验证序列
- 重复的故障防护措施
- 重复出现的职责边界
- 重复的根本原因类别
- 反复需要相同仓库特定上下文的工作流如果该模式重复出现且未被现有技能很好覆盖，则可作为候选技能。
区分「新技能」与「更新现有技能」。当现有技能属于正确分类，但存在触发条件过时、缺少防护机制、路径陈旧、验证指令薄弱或范围不完整时，推荐更新。仅当工作流足够独特，扩展现有技能会使其模糊或混乱时，才推荐创建新技能。
仅在审查完项目本地技能后，再检查与全局技能的重叠情况。使用
```
$CODEX_HOME/skills
```
和
```
$CODEX_HOME/skills/public
```
，避免为已被通用共享技能很好解决的工作流推荐项目本地技能。不要仅因存在全局技能就拒绝项目本地技能；项目特定的防护机制仍可证明本地定制的合理性。

Session Analysis

会话分析

1. Search memory index first

1. 优先搜索内存索引

Search
```
MEMORY.md
```
with
```
rg
```
using the repo name, basename, and
```
cwd
```
.
Prefer entries that already cite rollout summaries with the same repo path.
Capture:
- repeated workflows
- validation commands
- failure shields
- ownership boundaries
- milestone or roadmap coupling

使用
```
rg
```
工具，根据仓库名称、基础名称和
```
cwd
```
搜索
```
MEMORY.md
```
。
优先选择已引用相同仓库路径部署总结的条目。
捕获以下内容：
- 重复的工作流
- 验证命令
- 故障防护措施
- 职责边界
- 与里程碑或路线图的关联

2. Open targeted rollout summaries

2. 打开目标部署总结

Open the most relevant summary files under
```
memories/rollout_summaries/
```
.
Prefer summaries whose filenames,
```
cwd
```
, or
```
keywords
```
match the current project.
Extract:
- what the user asked for repeatedly
- what steps kept recurring
- what broke repeatedly
- what commands proved correctness
- what project-specific context had to be rediscovered

打开
```
memories/rollout_summaries/
```
下最相关的总结文件。
优先选择文件名、
```
cwd
```
或
```
keywords
```
与当前项目匹配的总结。
提取以下内容：
- 用户反复提出的需求
- 反复出现的步骤
- 反复出现的故障
- 被证明有效的验证命令
- 必须重新查找的项目特定上下文

3. Use raw sessions only as a fallback

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

Only search
```
sessions/
```
JSONL files if rollout summaries are missing a concrete detail.
Search by:
- exact
```
cwd
```
- repo basename
- thread ID from a rollout summary
- specific file paths or commands
Use raw sessions to recover exact prompts, command sequences, diffs, or failure text, not to replace the summary pass.

仅当部署总结缺少具体细节时，才搜索
```
sessions/
```
下的JSONL文件。
按以下条件搜索：
- 精确的
```
cwd
```
- 仓库基础名称
- 部署总结中的线程ID
- 特定文件路径或命令
使用原始会话恢复精确的提示、命令序列、差异或故障文本，而非替代总结环节。

4. Turn session evidence into skill candidates

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

A candidate
```
new skill
```
should correspond to a repeated workflow, not just a repeated topic.
A candidate
```
skill update
```
should correspond to a workflow already covered by a local skill whose triggers, guardrails, or validation instructions no longer match the recorded sessions.
Prefer concrete evidence such as:
- "this validation sequence appeared in 4 sessions"
- "this ownership confusion repeated across extractor and runtime fixes"
- "the same local script and telemetry probes had to be rediscovered repeatedly"

候选「新技能」应对应重复的工作流，而非仅重复的主题。
候选「技能更新」应对应已被本地技能覆盖的工作流，但该技能的触发条件、防护机制或验证指令与记录的会话不再匹配。
优先选择以下具体证据：
- 「该验证序列出现在4次会话中」
- 「这种职责混淆在提取器和运行时修复中反复出现」
- 「相同的本地脚本和遥测探针必须反复重新查找」

Recommendation Rules

What To Scan

扫描范围

Past sessions and memory:
- memory summary already in context, if any
- ```
$CODEX_HOME/memories/MEMORY.md
```
  or
```
~/.codex/memories/MEMORY.md
```
- the 1-3 most relevant rollout summaries for the current repo
- raw
```
$CODEX_HOME/sessions
```
  or
```
~/.codex/sessions
```
  JSONL files only if summaries are insufficient

Project-local skill surface:

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

Project conventions:
- ```
AGENTS.md
```
- ```
README.md
```
- roadmap, ledger, architecture, or validation docs
- current worktree or recent touched areas if needed for context

过往会话与内存：
- 上下文已包含的内存总结（若有）
- ```
$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
```
- 路线图、分类账、架构或验证文档
- 若需要上下文，可参考当前工作树或最近修改的区域

Output Expectations

输出预期

Return a compact audit with:

```
Existing skills
```
List the project-local skills found and the main workflow each one covers.
```
Suggested updates
```
For each update candidate, include:
- skill name
- why it is incomplete or stale
- the highest-value change to make
```
Suggested new skills
```
For each new skill, include:
- recommended skill name
- why it should exist
- what would trigger it
- the core workflow it should encode
```
Priority order
```
Rank the top recommendations by expected value.

返回简洁的审计结果，包含：

```
现有技能
```
列出找到的项目本地技能，以及每个技能覆盖的主要工作流。
```
建议更新
```
针对每个更新候选，包含：
- 技能名称
- 其不完整或过时的原因
- 最具价值的修改内容
```
建议新增技能
```
针对每个新技能，包含：
- 推荐的技能名称
- 其存在的必要性
- 触发条件
- 应编码的核心工作流
```
优先级排序
```
按预期价值对顶级推荐进行排名。

Naming Guidance

命名指南

Prefer short hyphen-case names.
Use project prefixes for project-local skills when that improves clarity.
Prefer verb-led or action-oriented names over vague nouns.

优先使用短连字符命名（hyphen-case）。
当有助于提升清晰度时，为项目本地技能添加项目前缀。
优先使用动词主导或面向动作的名称，而非模糊的名词。

Failure Shields

故障防护

Do not invent recurring patterns without session or repo evidence.
Do not recommend duplicate skills when an update to an existing skill would suffice.
Do not rely on a single memory note if the current repo clearly evolved since then.
Do not bulk-load all rollout summaries; stay targeted.
Do not skip rollout summaries and jump straight to raw sessions unless the summaries are insufficient.
Do not recommend skills from themes alone; recommendations should come from repeated procedures, repeated validation flows, or repeated failure modes.
Do not confuse a project's current implementation tasks with its reusable skill needs.

若无会话或仓库证据，不得虚构重复模式。
当更新现有技能即可满足需求时，不得推荐重复技能。
若当前仓库自上次记录后明显演进，不得仅依赖单一内存记录。
不得批量加载所有部署总结；保持针对性。
除非总结信息不足，不得跳过部署总结直接使用原始会话。
不得仅基于主题推荐技能；建议应来自重复的流程、重复的验证流或重复的故障模式。
不得将项目当前的实现任务与其可复用的技能需求混淆。

Follow-up

后续操作

If the user asks to actually create or update one of the recommended skills, switch to $skill-creator and implement the chosen skill rather than continuing the audit.

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