confluent-skill-reviewer

confluent-skill-reviewer — 审查 Confluent Agent 技能

本仓库中的每项技能都必须满足以下三项要求：

1. Agent Skills 规范——frontmatter 结构、命名规则、目录布局、令牌预算（https://agentskills.io/specification）。
2. Confluent 约定——延迟加载的参考资料、反触发条款、模式表分支、≥90% 的评估结果、SME + DTX/DevRel 签核（CLAUDE.md、.github/pull_request_template.md）。
3. 评估即契约——evals/evals.json 中包含具体、可验证的预期；fixture 保持同步。

此技能会引导 Agent 执行结构化审查，并返回一份 Markdown 报告。默认情况下为只读——绝不修改正在审查的技能。

预检关卡

在给出任何审查结果之前，先简要明确地确认以下三项：

1. 范围：你处于哪种模式？请参阅模式检测。如果不明确，只询问用户一次。
2. 目标路径是否存在：列出要审查的 skills/<name>/ 目录。如果没有，停止。
3. 工具是否可用：从仓库根目录运行 bash skills/confluent-skill-reviewer/scripts/run_skill_validator.sh --probe，检查是否已安装外部 skill-validator 二进制文件。如果未安装，在报告中注明并继续执行原生检查——不要因此中止。

跳过这些关卡是审查不佳的最常见原因。明确审查范围能让用户尽早纠正方向。

模式检测

用户意图 / 信号	模式	操作
“审查这个 PR”、“审查我的分支”、skills/ 下有未提交的更改，或提到了 PR 编号	PR 差异	执行 git diff main...HEAD -- skills/ 或 gh pr diff <N>；只审查有更改的技能；运行全部五个阶段，包括阶段 E
“审查 skills/<name>”、指定了单个技能路径，或从单个技能目录内调用	单技能	端到端审查一项技能；运行阶段 A–D
“审查所有技能”、未指定范围	全仓库	遍历 skills/*/，对每项技能运行阶段 A–D，并按严重程度汇总审查结果

如果无法判断，只询问用户一次：“你要审查 PR 差异、单项技能，还是整个仓库？” 然后继续。

检查阶段

按顺序运行各阶段。只有在发现问题时，才读取对应的参考资料。将审查结果收集到一个内存列表中，并标注严重程度：

• 阻断项——违反规范、CLAUDE.md 或 PR 模板关卡。合并前必须修复。
• 警告——违反约定，但不会导致工具无法运行；由审查者判断。
• 小问题——风格或清晰度问题，不影响功能。

阶段 A — 结构与规范符合性

从仓库根目录运行 bash skills/confluent-skill-reviewer/scripts/run_skill_validator.sh <skill-path>。有以下三种情况：

• 已安装二进制文件 → 脚本输出 skill-validator 的 JSON。将 results[].level == "error" 解析为阻断项，将 "warning" 解析为警告。在报告中记录每项结果的 file 和 line。
• 缺少二进制文件 → 脚本以状态码 0 退出，并在 stderr 中给出安装提示。在报告中将“未安装 skill-validator，跳过规范检查”记为警告，并原生执行规范检查（读取 references/spec-conformance.md 中的规则列表并逐项检查）。
• 已安装二进制文件，但技能属于多技能路径（路径中没有 SKILL.md）→ 脚本会继续输出按技能划分的 JSON；逐项独立处理。

无论验证器状态如何，都要执行以下原生检查，因为验证器无法很好地覆盖本仓库中的这些检查：

• 技能目录名称必须与 name: frontmatter 字段完全一致。
• evals/ 不应被标记为孤立目录（本仓库要求包含 evals；直接调用验证器时请传入 --allow-dirs=evals）。

只有在需要解读不熟悉的问题代码时，才读取 references/spec-conformance.md。

Phase B — Confluent 规范

根据 CLAUDE.md 中的 § Skill anatomy 和 § Evals 检查 SKILL.md，它们是验收标准。重点检查以下高影响项：

1. 延迟加载：SKILL.md 是否内联了 references/ 下任何文件的内容？搜索 references 中也出现的标题，以及重复引用资料的长代码围栏块。内联引用内容属于 阻塞项。
2. 反触发条款：description: 是否包含 Do NOT trigger for… 条款？如果相邻描述中有相同关键词（Phase C 会确认），缺少该条款属于 阻塞项；否则属于 警告。
3. 模式表分支：如果 SKILL.md 超过约 200 行，或涵盖多个不同工作流（例如构建 和 调试），则应在靠近顶部的位置提供模式检测表。缺少此表属于 警告。
4. 引用层级：引用文件嵌套在技能根目录以下超过一层属于 阻塞项（规范对此有限制）。
5. 来源元数据：在此仓库中编写的技能应声明 metadata.author: confluent、metadata.version（语义化版本）和 metadata.last_updated（YYYY-MM-DD）。缺少字段属于 警告。如果技能需要特定软件包、CLI 工具或环境访问权限，则应提供 compatibility 字段；明显需要环境支持的技能缺少此字段属于 轻微问题。
6. 平台范围：如果 name 包含平台标记（confluent-cloud-*、confluent-platform-*、warpstream-*、apache-kafka-*），正文必须将指令限定在该平台范围内；如果内容笼统地涵盖所有平台，则属于 阻塞项。反之，如果 name 不含平台标记，但正文执行了因平台而异的操作（Cloud API 密钥、WarpStream 对象存储配置、本地部署的 SASL），则应包含平台检测步骤 和 各平台的引用文件（references/confluent-cloud.md、references/warpstream.md 等）。缺少其中任一项属于 警告。
7. 先规划再执行：会创建、修改或删除资源（Kafka 主题、架构、Flink 语句、连接器、Terraform 状态）的技能，必须在任何修改资源的调用之前，明确要求“展示计划，等待用户确认”。具备 CRUD 能力的技能未包含此步骤，属于 阻塞项。
8. 凭据处理：读取凭据的技能不得直接对 .env 文件使用 cat、Read、head 或 grep，而应通过变量名引用（$BOOTSTRAP_SERVERS），并使用 test -n "$VAR" 验证变量是否存在。读取 .env 内容的 SKILL.md 或随附脚本属于 阻塞项。消耗凭据的技能完全没有防护说明，属于 警告。
9. 仅使用合成数据：运行 python3 skills/confluent-skill-reviewer/scripts/scan_pii.py <skill-path>（从仓库根目录运行），检查技能中是否提交了真实客户数据或机密信息——SKILL.md、references/、评估提示词、磁盘上的固定数据以及随附脚本都必须仅使用合成数据。该脚本会输出 JSON；请将每项发现映射到报告中。severity: "blocking"（美国 SSN、通过 Luhn 校验的支付卡、AWS 密钥 ID、私钥块）→ 阻塞项；severity: "warning"（非示例域名的电子邮件、电话号码）→ 警告。CI 会在 skills/ 上运行同一扫描器，因此此处扫描通过也意味着符合 CI 门禁。

阅读 references/confluent-conventions.md，了解完整规则列表和 PR 模板门禁。

阶段 C — 触发词重叠

运行 python3 skills/confluent-skill-reviewer/scripts/check_trigger_overlap.py <root>（在仓库根目录下）。脚本接受仓库根目录（扫描 <root>/skills/*/SKILL.md）或“skills 根目录”（扫描 <root>/*/SKILL.md）——运行 evals/mock-skills/ 时请使用后者。脚本会解析每个 SKILL.md 的 frontmatter，将 description: 字段拆分为词元（过滤停用词和领域宽泛词语，如 confluent、kafka、schema、producer、consumer、topic、stream），并报告关键词冲突。对于每个冲突：

• 存在 ≥3 个重叠的非宽泛关键词（例如“拓扑”“重新平衡”“窗口化”），且双方没有互相点名的反触发词 → 阻塞项。
• 存在 2 个重叠的非宽泛关键词，且双方没有互相点名的反触发词 → 警告。
• 仅重叠 1 个非宽泛关键词 → 小问题。
• 重叠内容完全由经过过滤的领域宽泛词语构成 → 脚本静默通过（这些是巧合，并非冲突）。

仅在需要拟定反触发词修复措辞时，阅读 references/trigger-overlap.md——其中包含基于本仓库现有技能撰写的实用示例。

阶段 D — Evals 约定

运行 python3 skills/confluent-skill-reviewer/scripts/check_eval_schema.py <skill-path>/evals/evals.json（在仓库根目录下）。脚本会验证：

• 存在顶层 skill_name（字符串）和 evals（数组）键。
• 每个 eval 都包含 id、prompt、expected_output、files，且检查项位于 assertions 键下。仓库已统一采用一种格式：assertions 的值为字符串列表。以下两种偏离现已列为阻塞项——旧版 expectations 键（必须重命名为 assertions）和对象格式条目 [{id, type, description, …}]（必须展平为字符串）。
• prompt 应采用真实的用户措辞，而非抽象描述（启发式标准：≥40 个字符，且不能只是“帮我构建一个 X”）。较短的提示词属于警告。
• assertions[] 应具体明确（启发式标准：包含动词、名词，以及至少一个具体标识符——文件路径、类名、配置键或“NOT”子句）。含糊的断言属于警告；请引用 CLAUDE.md § Evals are the contract：“expectations encode hard-won correctness — treat them as regression tests, not aspirations”。

交叉检查测试样例同步情况：files: [...] 中的每个条目要么是磁盘上的路径（相对于技能根目录——当技能包含 evals/mock-repos/ 或 evals/mock-skills/ 目录时，必须能解析；缺失的测试样例属于阻塞项），要么是内联测试样例对象 {path, content}，其中包含 eval 自身所需的文件正文（无需从磁盘解析）。

阅读 references/evals-contract.md，了解 JSON schema、两种 expectations 格式，以及薄弱与有力 expectations 的实用示例。

阶段 E — PR 模板关卡（仅 PR 差异模式）

在单技能和全仓库模式下跳过。

阅读一次 .github/pull_request_template.md，了解当前清单。针对当前 PR，核对每一项：

PR 模板关卡	检查方法
文档已更新，以反映新增技能	git diff main...HEAD -- README.md docs/；如果新增了技能，但 README 的技能表未改动，则标记为阻塞项
Evals 达到 90%+ 阈值	查看 CI 日志或 PR 评论中的 eval 运行结果；如果没有，请作者粘贴分数——确认前均为阻塞项
已确定 SME 审核者	gh pr view --json reviewRequests,assignees——相关领域（Kafka Streams、Schema Registry 等）至少有一位 SME；若为新技能但缺少 SME，则为阻塞项
已指派 DTX/DevRel 审核者	执行同一命令——至少有一位审核者来自 @confluentinc/dtx 或 @confluentinc/developer-advocates；缺少则为阻塞项

如果当前模板中的关卡措辞已发生变化，请阅读 references/confluent-conventions.md § PR template。

报告格式

输出一份 Markdown 报告。按严重程度而非阶段对调查结果分组——审核者会从上往下查看：

# Skill review: <skill name or PR title>

**Mode:** PR-diff | Single-skill | Repo-wide
**Validator:** installed (v1.5.6) | not installed (spec checks done natively)
**Scope:** <list of skills audited>

## Blocking (N)

- `skills/<name>/SKILL.md:14` — Inlined contents of `references/build-templates.md` into the SKILL.md body. CLAUDE.md § Skill anatomy (lazy-load references bullet) requires lazy-loaded references. Move the content back and route to it from a decision point.
- `skills/<name>/evals/evals.json:42` — Eval id 3 references `evals/mock-repos/missing/` which does not exist on disk. Add the fixture or update the path.

## PR-template checklist (PR-diff mode only)

- [x] Docs updated
- [ ] Evals at 90%+ — author has not pasted score
- [x] SME reviewer assigned (@alice)
- [ ] DTX/DevRel reviewer — none assigned

## Summary

Recommend: **request changes** | **approve with nits** | **approve**.

如果没有阻塞项和警告，建议结果为 批准。存在一个或多个阻塞项 → 请求修改。

此技能不会做什么

• 不会编辑正在审查的技能。只报告发现的问题。
• 不会运行该技能自身的评估（测试框架位于 ~/.claude/skills/skill-creator/；如果希望获得 90% 的评分，Agent 应单独调用它）。
• 不会分析运行时或日志行为——这由 tools/skill_review_dashboard.py 负责。
• 不会审查 skills/ 之外的文件（构建系统、Makefile、service.yml 和 .claude-plugin/ 不在审查范围内；如果这些文件发生变更，请提醒人工审查者）。