reviewing-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reviewing Skills

技能评审

Objective

目标

Evaluate a skill directory as if you are an AI agent encountering it for the first time. Produce a read-only review with:

A weighted score + letter grade
Spec violations (blockers)
Prioritized findings (P1/P2/P3) with concrete, minimal fixes
Optional rewritten sections (only when needed to reach the quality bar)

This skill is intended to act as the critic in a generator<->critic loop (e.g., with

$writing-skills

以AI Agent首次接触技能目录的视角对其进行评估。生成一份只读评审报告，包含：

加权分数 + 字母等级
规范违反项（阻塞问题）
按优先级划分的问题（P1/P2/P3）及具体、精简的修复方案
可选的重写章节（仅在需要达到质量标准时提供）

本技能旨在充当生成器<->评审器循环中的评审角色（例如与

$writing-skills

配合使用）。

When to use / When not to use

适用场景 / 非适用场景

Use when:

The user asks to review, grade, or audit a skill folder containing
```
SKILL.md
```
.
The user wants rubric-based scoring and actionable edits (not just general advice).

Do not use when:

The user wants you to write a skill from scratch (use a writing skill instead).
The request is not about a skill directory or does not involve
```
SKILL.md
```
.

适用场景：

用户要求评审、评级或审计包含
```
SKILL.md
```
的技能文件夹时。
用户需要基于评分标准的打分和可落地的修改建议（而非仅通用建议）时。

非适用场景：

用户要求从零开始编写技能时（请使用写作类技能）。
请求内容与技能目录无关或不涉及
```
SKILL.md
```
时。

Inputs

输入要求

You need a path to a skill directory that contains

SKILL.md

(and optionally

agents/openai.yaml

scripts/

references/

assets/

If the user did not provide a path:

Look for directories in CWD that contain
```
SKILL.md
```
.
If multiple, ask the user to choose.

需要提供包含

SKILL.md

的技能目录路径（可选包含

agents/openai.yaml

、

scripts/

、

references/

、

assets/

）。

若用户未提供路径：

查找当前工作目录（CWD）中包含
```
SKILL.md
```
的目录。
若存在多个目录，请让用户选择目标目录。

Outputs

输出内容

A read-only Markdown report with weighted grade, findings, and copy/paste patch text (see workflow step 6 for format rules).

一份只读Markdown报告，包含加权等级、问题项，以及可直接复制粘贴的补丁文本（格式规则见工作流第6步）。

Safety / Constraints (non-negotiable)

安全/约束条件（不可协商）

Read-only: do not edit, create, delete, or move files.
Do not execute untrusted code: do not run repo scripts/binaries unless the user explicitly asks and you can justify the risk.
Secrets: do not open or quote secrets (e.g.,
```
.env
```
, API keys, credentials). If encountered, redact and warn.
Network: do not browse the web or call external systems unless the user explicitly requests it.
No fabrication: if you cannot verify something, say so and recommend a verification step.
No deep reference chasing: read only what is needed to score accurately (one level deep).

只读限制：不得编辑、创建、删除或移动文件。
禁止执行不可信代码：除非用户明确要求且风险可控，否则不得运行仓库中的脚本/二进制文件。
保密处理：不得打开或引用敏感信息（如
```
.env
```
、API密钥、凭证）。若遇到此类内容，需进行脱敏并发出警告。
网络限制：除非用户明确要求，否则不得浏览网页或调用外部系统。
禁止编造内容：若无法验证某内容，需明确说明并建议验证步骤。
限制深度引用：仅读取为准确打分所需的内容（最多一层深度）。

Verification Rules

验证规则

Follow the verification protocol in references/skills-rubric.md. Budget: ~20 reads max.

遵循references/skills-rubric.md中的验证协议。读取次数上限：约20次。

Workflow (decision-complete)

工作流（决策闭环）

Resolve the target skill directory
- Confirm the path contains
```
SKILL.md
```
  . If it does not, stop and ask for the correct folder.
Read the minimum necessary context (in order)
1. ```
<skill>/SKILL.md
```
2. ```
<skill>/agents/openai.yaml
```
  (if present)
3. Any files under
```
<skill>/scripts/
```
  referenced by
```
SKILL.md
```
  (only those)
4. Any files under
```
<skill>/references/
```
  referenced by
```
SKILL.md
```
  (only those)
(If in a git repo) gather change context
- Prefer the repo’s base branch; if unknown, check
```
git remote show origin
```
  for “HEAD branch”, otherwise try
```
main
```
  then
```
master
```
  (and state what you chose).
- ```
git diff <base> -- <skill>/
```
- ```
git log --oneline -20 -- <skill>/
```
- For non-trivial diffs:
```
git log -p -5 -- <skill>/SKILL.md
```
- If
```
<skill>/
```
  is new/untracked (so
```
git diff <base>
```
  shows nothing), state that explicitly and treat contents as “new.”
- If a score or finding is driven by a recent change, cite the relevant diff hunk or commit short-hash.
Score using the rubric
- Use
```
references/skills-rubric.md
```
  (single source of truth).
- Give each dimension a 1.0–5.0 score (0.5 increments allowed).
- Compute weighted score as:
```
sum(weight_i * score_i) / 100
```
  .
Identify issues and merge duplicates
- First list spec violations (blockers).
- Then produce prioritized findings (max ~15 total), merging near-duplicates.
- Every P1/P2 finding includes concrete patch text.
- Patch rules: keep patches small/local; prefer "replace X with Y"; rewrite only the smallest section needed to clear P1/P2.
Produce the report
- Default to
```
references/review-template.md
```
  structure.
- If the user requires a different structure, preserve the same content (grade, dimension scores, blockers, prioritized findings with patch text, token efficiency notes).
- If the user requests a forensic or diff-centric review, add a hunk-by-hunk analysis for meaningful changes (
```
+/-
```
  context), and classify each as improvement/regression/neutral.
- Only include “Rewritten sections” when score < 4.5, any P1 exists, or the author requests a rewrite.

Do not read assets unless explicitly relevant.

确定目标技能目录
- 确认路径中包含
```
SKILL.md
```
  。若未找到，需停止操作并询问正确的文件夹路径。
按顺序读取必要的最少上下文
1. ```
<skill>/SKILL.md
```
2. ```
<skill>/agents/openai.yaml
```
  （若存在）
3. ```
SKILL.md
```
  中引用的
```
<skill>/scripts/
```
  下的文件（仅引用到的文件）
4. ```
SKILL.md
```
  中引用的
```
<skill>/references/
```
  下的文件（仅引用到的文件）
（若在Git仓库中）收集变更上下文
- 优先使用仓库的基准分支；若未知，通过
```
git remote show origin
```
  查看“HEAD branch”，否则依次尝试
```
main
```
  和
```
master
```
  分支（需说明所选分支）。
- 执行
```
git diff <base> -- <skill>/
```
- 执行
```
git log --oneline -20 -- <skill>/
```
- 对于非微小差异：执行
```
git log -p -5 -- <skill>/SKILL.md
```
- 若
```
<skill>/
```
  为新增/未跟踪目录（
```
git diff <base>
```
  无输出），需明确说明并将内容视为“新增”。
- 若分数或问题项由近期变更导致，需引用相关差异片段或提交短哈希值。
基于评分标准打分
- 以
```
references/skills-rubric.md
```
  为唯一评分依据。
- 为每个维度给出1.0–5.0的分数（允许0.5的增量）。
- 加权分数计算公式：
```
sum(weight_i * score_i) / 100
```
  。
识别问题并合并重复项
- 首先列出规范违反项（阻塞问题）。
- 然后生成按优先级划分的问题项（最多约15个），合并近似重复项。
- 每个P1/P2问题项需包含具体的补丁文本。
- 补丁规则：保持补丁小而局部；优先使用“将X替换为Y”的形式；仅重写解决P1/P2问题所需的最小章节。
生成报告
- 默认采用
```
references/review-template.md
```
  的结构。
- 若用户要求不同结构，需保留相同核心内容（等级、维度分数、阻塞问题、带补丁文本的优先级问题项、Token效率说明）。
- 若用户要求取证或基于差异的评审，需对有意义的变更添加逐段分析（
```
+/-
```
  上下文），并将其分类为改进/退化/中性。
- 仅当分数<4.5、存在P1问题或作者要求重写时，才包含“重写章节”。

除非明确相关，否则不得读取assets目录下的内容。

Review Guidelines

评审指南

What to reward

加分项

High signal per token: dense, directive, minimal prose.
Correct triggering: description precisely indicates what and when.
Decision-complete workflow: the skill leaves no key decisions ambiguous.
Guardrails: destructive actions gated; secrets handled safely; constraints explicit.
Portability: avoids tool-vendor lock-in; uses capability language with optional adapters.

高Token信号比：内容密集、指令明确、文字精简。
触发条件准确：描述精准说明做什么和何时做。
决策闭环工作流：技能未留下关键决策模糊点。
防护机制完善：破坏性操作受限制；敏感信息处理安全；约束条件明确。
可移植性强：避免工具供应商锁定；使用能力描述语言并支持可选适配器。

What to penalize

扣分项

Vague directives (“as appropriate”, “best practices”, “use standard approach”).
Over-broad scope (one skill trying to do too many disjoint jobs).
Reference chains (SKILL.md → reference → another reference).
Missing or non-actionable validation loops.
“Cute” verbosity that costs tokens without improving outcomes.

模糊指令（如“视情况而定”、“最佳实践”、“使用标准方法”）。
范围过宽（一个技能试图完成多个不相关的任务）。
引用链过长（SKILL.md → 参考文档 → 另一参考文档）。
缺失或不可落地的验证循环。
无意义的冗余表述，浪费Token且未提升效果。

Additional checks (inform findings; not scored as a separate dimension)

额外检查项（用于补充问题项；不单独作为评分维度）

Terminology consistency for core concepts across sections.
Presence and usefulness of concrete examples/templates when output style matters.
Anti-pattern scan: Windows-style paths, too many options without a default, time-sensitive claims, deep reference chains, and assumed package installs.

核心概念术语在各章节中的一致性。
当输出风格重要时，是否存在具体示例/模板且实用。
反模式扫描：Windows风格路径、无默认值的过多选项、时效性声明、深层引用链、未说明的依赖包安装假设。

Edge cases (common failure modes)

边缘情况（常见失败模式）

No git / no base branch: state what you could not verify; review file contents only.
Large skills: stick to the tight-budget read order; do not “read everything” by default.
Missing referenced files: treat as a spec violation or P1 (broken workflow), depending on severity.
Secrets in context: redact and warn; do not quote.

无Git环境/无基准分支：说明无法验证的内容；仅评审文件本身。
大型技能目录：严格遵循限定的读取顺序；默认不得“读取全部内容”。
缺失引用文件：根据严重程度，将其视为规范违反项或P1问题（工作流中断）。
上下文包含敏感信息：脱敏并发出警告；不得引用。

Examples

示例

“Use $reviewing-skills to review
```
./some-skill/
```
and provide a weighted grade, spec blockers, and prioritized patch text.”
“Use $reviewing-skills to do a forensic/diff-centric review of
```
./some-skill/
```
focusing on recent changes.”
For a worked example format, see references/example-review.md.

“使用$reviewing-skills评审
```
./some-skill/
```
，并提供加权等级、规范阻塞问题及按优先级划分的补丁文本。”
“使用$reviewing-skills对
```
./some-skill/
```
进行取证/基于差异的评审，重点关注近期变更。”
关于示例格式，可参考references/example-review.md。