skill-quality-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Quality Review

Skill 质量审查

Use this skill to evaluate a SKILL.md file against Anthropic's agent-skill best practices. This is a content-quality review — token efficiency, discoverability, calibration. It is NOT a structural validator (the deterministic R1–R7 checks live in

scripts/build/validate_skills.py

and run in CI).

使用本 Skill 根据 Anthropic 的 agent-skill 最佳实践评估 SKILL.md 文件。这是一次内容质量审查——重点关注 Token 效率、可发现性和校准程度。它不是结构验证器（确定性的 R1–R7 检查位于

scripts/build/validate_skills.py

中，并在 CI 中运行）。

When to Use

使用时机

Reviewing a PR that adds or modifies a
```
skills/<name>/SKILL.md
```
file in
```
mulesoft/mulesoft-dx
```
.
Auditing an existing skill that the user suspects is bloated, vague, or hard to trigger.
Before publishing a new skill to the bundle.

Do NOT use this skill for:

Pure structural checks (frontmatter present, code fences balanced) — that's
```
make validate-skills
```
.
API-spec reviews — use
```
api-spec-validator
```
.
Generic prose editing — this is specifically about agent-skill ergonomics.

审查在

mulesoft/mulesoft-dx

中添加或修改

skills/<name>/SKILL.md

文件的 PR。

审计用户认为内容臃肿、含糊或难以触发的现有 Skill。
在将新 Skill 发布到 bundle 之前。

不要将本 Skill 用于：

纯结构检查（frontmatter 是否存在、代码围栏是否平衡）——应使用
```
make validate-skills
```
。
API 规范审查——使用
```
api-spec-validator
```
。
通用文稿编辑——本 Skill 专门用于评估 Agent Skill 的使用体验。

How to Run

运行方式

Load references:
- ```
references/anthropic-best-practices.md
```
  (vendored Anthropic doc, ~1100 lines) — generic agent-skill best practices, source of truth for dimensions 1-8.
- ```
docs/job-template.md
```
  and
```
docs/jobs-readme.md
```
  from the repo root — repo-specific JTBD conventions.
- ```
skills/skills-metadata.yaml
```
  — declares which skills are
```
jtbd
```
  vs
```
prose
```
  . Determines which extra rules apply.
Identify the target skill(s): the caller will name a path (e.g.
```
skills/omni-gateway/install-omni-gateway/SKILL.md
```
) or a list of paths. If the caller asks to review every skill changed in the current branch, resolve the list with
```
git diff --name-only <base>... -- 'skills/**/SKILL.md'
```
.
Determine skill type by reading
```
skills-metadata.yaml
```
(or the parent bundle's):
```
jtbd
```
(default) or
```
prose
```
(override). The type drives which extra checks apply (see "Type-specific dimensions" below).
Read the full SKILL.md plus any referenced files (
```
references/
```
,
```
scripts/
```
) — progressive disclosure means a top-level SKILL.md is only half the picture.
Evaluate against each dimension below, in order. For each dimension, decide: PASS / WARN / FAIL, with a one-line rationale and a quote from the SKILL.md.
Return the findings to the caller in the structure shown in "Output Format" below. Do not create or write to any file unless the caller explicitly asks for it — the caller decides whether to display the report, append it to a review document, attach it to a PR comment, or use it to revise a skill in-flight.

加载参考资料：
- ```
references/anthropic-best-practices.md
```
  （随仓库引入的 Anthropic 文档，约 1100 行）——通用 Agent Skill 最佳实践，也是维度 1–8 的权威依据。
- 仓库根目录中的
```
docs/job-template.md
```
  和
```
docs/jobs-readme.md
```
  ——仓库特定的 JTBD 约定。
- ```
skills/skills-metadata.yaml
```
  ——声明哪些 Skill 属于
```
jtbd
```
  、哪些属于
```
prose
```
  ，用于确定适用的额外规则。
确定目标 Skill：调用方会给出路径（例如
```
skills/omni-gateway/install-omni-gateway/SKILL.md
```
）或路径列表。如果调用方要求审查当前分支中所有发生变更的 Skill，请使用
```
git diff --name-only <base>... -- 'skills/**/SKILL.md'
```
获取列表。
确定 Skill 类型：读取
```
skills-metadata.yaml
```
（或父 bundle 的对应文件）：
```
jtbd
```
（默认）或
```
prose
```
（覆盖值）。类型决定需要应用哪些额外检查，详见下文“类型特定维度”。
完整读取 SKILL.md 及其引用的所有文件（
```
references/
```
、
```
scripts/
```
）——渐进式披露意味着顶层 SKILL.md 只反映了一半情况。
按以下顺序逐项评估每个维度。对每个维度作出 PASS / WARN / FAIL 判定，并给出一行理由说明和 SKILL.md 原文引用。
按照“输出格式”将发现结果返回给调用方。除非调用方明确要求，否则不要创建或写入任何文件——是由调用方决定将报告直接展示、附加到审查文档、附到 PR 评论，还是用于在当前开发过程中修改 Skill。

Review Dimensions

审查维度

For each, cite the exact best-practices section and quote the offending text from SKILL.md. Do not invent rules — if a check isn't grounded in the reference doc, don't include it.

对于每一项，引用最佳实践文档中的确切章节，并引用 SKILL.md 中有问题的原文。不得臆造规则——如果某项检查没有参考文档作为依据，就不要将其纳入审查。

1. Concision (Core principles → "Concise is key")

1. 简洁性（Core principles → “Concise is key”）

Is every paragraph earning its tokens? Flag prose that explains things Claude already knows (what a PDF is, what a library is, what HTTP is).
Is SKILL.md body under ~500 lines? If over, is the overflow content split into
```
references/
```
files that load on demand?
Are there redundant restatements of the same instruction?

每个段落是否都值得占用其 Token？标记那些解释 Claude 本已知晓内容的冗余文字，例如什么是 PDF、库或 HTTP。
SKILL.md 正文是否控制在约 500 行以内？如果超出，溢出内容是否已拆分到可按需加载的
```
references/
```
文件中？
是否存在对同一条指令的重复复述？

2. Description quality (Skill structure → "Writing effective descriptions")

2. 描述质量（Skill structure → “Writing effective descriptions”）

Third person — flag any "I can…" or "You can…" or "Use this to…" framings.
Specific + trigger-rich — does the description list both what the skill does and when to use it (concrete user-phrasings, file types, scenarios)?
Length — under 1024 chars but specific enough that Claude can disambiguate from 100+ other skills.
Vague rejects — "Helps with X", "Manages Y", "Does stuff with Z" → fail.

第三人称——标记任何“I can…”“You can…”或“Use this to…”式的表述。
具体且触发词丰富——描述是否同时列明 Skill 的功能和使用时机（包括具体的用户表述、文件类型和场景）？
长度——少于 1024 个字符，同时具体到足以让 Claude 从 100 多个其他 Skill 中正确区分它。
拒绝含糊描述——“Helps with X”“Manages Y”“Does stuff with Z”均判定为失败。

3. Naming (Skill structure → "Naming conventions")

3. 命名（Skill structure → “Naming conventions”）

Lowercase + hyphens + numbers only.
No reserved words:
```
anthropic
```
,
```
claude
```
.
Prefer gerund form (
```
processing-pdfs
```
) or noun phrases (
```
pdf-processing
```
); flag
```
helper
```
,
```
utils
```
,
```
tools
```
.
The
```
name:
```
field must match the directory.

仅使用小写字母、连字符和数字。
不使用保留字：
```
anthropic
```
、
```
claude
```
。
优先使用动名词形式（
```
processing-pdfs
```
）或名词短语（
```
pdf-processing
```
）；标记
```
helper
```
、
```
utils
```
、
```
tools
```
。
```
name:
```
字段必须与目录名匹配。

4. Degree-of-freedom calibration (Core principles → "Set appropriate degrees of freedom")

4. 自由度校准（Core principles → “Set appropriate degrees of freedom”）

Fragile / one-true-path operations (DB migrations, build commands, exact env setup) should be low freedom — exact scripts, "do not modify".
Judgment calls (code review, design decisions) should be high freedom — heuristics + criteria, not lockstep steps.
Flag mismatches: a code-review skill with 17 rigid steps, or a
```
mvn deploy
```
skill that says "use whatever flags seem right".

脆弱或只有唯一正确路径的操作（DB migrations、build commands、精确的环境配置）应采用低自由度——提供确切脚本并明确说明“do not modify”。
需要判断的操作（code review、design decisions）应采用高自由度——提供启发式原则和判断标准，而不是强制执行完全一致的步骤。
标记不匹配情况，例如一个 code-review Skill 包含 17 个僵化步骤，或一个
```
mvn deploy
```
Skill 声称“use whatever flags seem right”。

5. Progressive disclosure (Skill structure → "Pattern 1/2/3")

5. 渐进式披露（Skill structure → “Pattern 1/2/3”）

Long reference content (catalogs, error tables, schemas) belongs in
```
references/foo.md
```
, loaded on demand.
Helper logic belongs in
```
scripts/
```
, executed not loaded.
Flag a 1500-line SKILL.md where the bottom 1000 lines are reference material that should have been split.

大段参考资料（目录、错误表、schema）应放在
```
references/foo.md
```
中并按需加载。
辅助逻辑应放在
```
scripts/
```
中，执行而不是加载。
标记这类问题：一个 1500 行的 SKILL.md，其中末尾 1000 行是本应拆分出去的参考资料。

6. Discoverability triggers (Skill structure → "Writing effective descriptions" + "How Skills work")

6. 可发现性触发词（Skill structure → “Writing effective descriptions” + “How Skills work”）

Description should contain the literal terms a user is likely to type ("validate", "review", "deploy", "Mule", "OAS") so Claude's selector matches.
If the skill applies to a specific tool/format/file extension, that should appear verbatim.

描述应包含用户可能输入的原样术语（“validate”“review”“deploy”“Mule”“OAS”），以便 Claude 的选择器匹配。
如果 Skill 适用于特定工具、格式或文件扩展名，应原样出现。

7. Cross-references (skill-bundle pattern in this repo)

7. 交叉引用（本仓库的 skill-bundle 模式）

If SKILL.md references other skills by name, those skills must exist in the same bundle (or be marked "coming in vX.Y").
URLs and file paths inside the skill must resolve.
Trigger phrases listed in the description should be plausible — not invented.

如果 SKILL.md 按名称引用了其他 Skill，这些 Skill 必须存在于同一 bundle 中（或标记为“coming in vX.Y”）。
Skill 内的 URL 和文件路径必须可以解析。
描述中列出的触发语句应合理可信，而不是凭空编造。

8. Tone consistency (Skill structure → third person)

8. 语气一致性（Skill structure → third person）

Any first-person ("I'll do…") or second-person command framing aimed at the human ("you should…") within instructions block is a red flag — instructions are for Claude.

指令块中任何面向人的第一人称（“I'll do…”）或第二称命令式表述（“you should…”）都是危险信号——这些指令是写给 Claude 的。

Type-specific dimensions

类型特定维度

This repo classifies skills as jtbd
(default) or prose
in

skills/skills-metadata.yaml

(or the bundle-level

<bundle>/skills-metadata.yaml

). Apply only the dimensions that match the declared type. Type↔structure coherence (does the content match the type?) is already enforced by R7 of the deterministic validator — flag here only when the AI reading detects subtler drift.

Scope reminder: the deterministic validators (
validate_skills.py
,
validate_jtbd.py
) already enforce structural correctness — step numbering gaps, frontmatter parseability, kebab-case names, bundle metadata,
urn:
resolution, step dependency order, type-vs-structure coherence. Do not re-check those. If a finding can be expressed as a regex/AST rule, it belongs in the deterministic layer, not here. Below are only judgment calls.

本仓库在

skills/skills-metadata.yaml

（或 bundle 级别的

<bundle>/skills-metadata.yaml

）中将 Skill 分类为 jtbd
（默认）或 prose
。仅应用与声明类型匹配的维度。类型与结构的连贯性（内容是否与类型匹配）已由确定性验证器的 R7 强制检查——此处仅在 AI 阅读发现更细微的偏移时进行标记。

范围提醒： 确定性验证器（
validate_skills.py
、
validate_jtbd.py
）已经强制检查结构正确性——步骤编号缺口、frontmatter 可解析性、kebab-case 名称、bundle metadata、
urn:
解析、步骤依赖顺序、类型与结构一致性。不要重复检查这些项目。 如果某项发现可以用正则表达式或 AST 规则表达，就应放在确定性层，而不是这里。以下仅包含需要判断的问题。

JTBD-specific (when

type: jtbd

)

JTBD 特定维度（当

type: jtbd

时）

Imperative voice in step titles — "Search Exchange" is correct; "Searching Exchange", "How to search Exchange", "Exchange search" are not. Determinístic check can't tell a verb from a gerund — that's why this is here. Apply the same criteria as
```
validate-imperative-format
```
does for API descriptions.
inputs:
/
outputs:
capture the real dependency, not just the obvious ones — if Step 7's prose says "use the GAV from Step 4", but Step 4 declares no
```
outputs.gav
```
and Step 7 declares no
```
inputs.gav
```
, the data flow is invisible to the agent. Determinístic checks see the YAML structure but can't read the prose to detect the mismatch.
Step prose stays consistent with step numbering after renumbering — when a PR renumbers steps, internal references like "as in Step 5" or "Step 8 will use this" must point to the new step numbers. Determinístic validators don't know what Step 5 was about; an LLM does.
Phase boundaries are real, not decorative — if a JTBD declares a "user-approval gate" between phases, the gate must actually mean something (the next step refuses to proceed without explicit user input). Cosmetic phase headings without enforcement are a smell.

步骤标题使用祈使语气——“Search Exchange”正确；“Searching Exchange”“How to search Exchange”“Exchange search”不正确。确定性检查无法判断一个词是动词还是动名词——这正是需要在此处理的原因。应用与
```
validate-imperative-format
```
检查 API 描述时相同的标准。
inputs:
/
outputs:
应反映真实依赖关系，而不只是显而易见的依赖——如果步骤 7 的正文写着“use the GAV from Step 4”，但步骤 4 未声明
```
outputs.gav
```
，且步骤 7 未声明
```
inputs.gav
```
，那么 Agent 就无法看到这条数据流。确定性检查可以看到 YAML 结构，却无法阅读正文来检测不一致。
重新编号后，步骤正文应与步骤编号保持一致——当 PR 重新编号步骤时，“as in Step 5”或“Step 8 will use this”等内部引用必须指向新的步骤编号。确定性验证器不知道“步骤 5”原本代表什么；LLM 可以判断。
阶段边界必须真实有效，而非仅起装饰作用——如果 JTBD 在阶段之间声明了“user-approval gate”，该 gate 就必须真正发挥作用（下一步必须拒绝在没有明确用户输入的情况下继续）。仅有表面上的阶段标题而没有约束力是一种隐患。

Prose-specific (when

type: prose

)

Prose 特定维度（当

type: prose

时）

The skill is genuinely prose, not a JTBD wearing a costume — if a prose skill has 8 sequential
```
### Step N
```
headings with bash commands and explicit ordering, it should probably be
```
type: jtbd
```
. R7 only flags binary mismatches (has steps / has none); the gradual slippage requires reading.
Decision-routing structure exists in bundle-root prose skills — for a multi-skill bundle (like
```
omni-gateway/SKILL.md
```
), the root should route the agent to sub-skills via a decision table or mermaid flowchart. A bundle-root prose skill that's just a paragraph of "this bundle does X, Y, Z" without routing wastes the entry point.
Mermaid diagrams render — confirm fenced as
```
```mermaid
```
(not in YAML frontmatter) and that node references match labels. Mermaid in frontmatter is the bug we hit on PR #129.

Skill 的本质确实是 prose，而不是披着外衣的 JTBD——如果一个 prose Skill 包含 8 个连续的
```
### Step N
```
标题、bash 命令和明确的执行顺序，它很可能应该是
```
type: jtbd
```
。R7 只能标记二元不匹配（有步骤或没有步骤）；这种渐进式偏移需要通过阅读来判断。
bundle-root prose Skill 中存在决策路由结构——对于多 Skill bundle（如
```
omni-gateway/SKILL.md
```
），根 Skill 应通过决策表或 mermaid flowchart 将 Agent 路由到子 Skill。如果 bundle-root prose Skill 只是用一段文字说明“这个 bundle 完成 X、Y、Z”，却没有提供路由，就会浪费这个入口。
Mermaid 图能够正确渲染——确认其使用
```
```mermaid
```
围栏（而不是放在 YAML frontmatter 中），并且节点引用与标签匹配。在 frontmatter 中使用 Mermaid 正是我们在 PR #129 中遇到的缺陷。

Bundle-level (when reviewing a whole bundle, not a single skill)

Bundle 级别（审查整个 bundle，而非单个 Skill 时）

The bundle's
SKILL.md
(root) actually adds value — if it's just a list of sub-skill names, the agent could discover those from descriptions alone. The root should help disambiguate, route, or set shared context.
CHANGELOG entry matches the actual user-visible change — a CHANGELOG that says "improved error handling" when the diff added a new sub-skill is misleading. R-level validators don't read the CHANGELOG semantically.

bundle 的根
```
SKILL.md
```
应真正增加价值——如果它只是子 Skill 名称的列表，Agent 本来就能从各项描述中发现它们。根 Skill 应帮助消除歧义、提供路由或设置共享上下文。
CHANGELOG 条目应与实际的用户可见变更一致——如果 diff 添加了一个新子 Skill，而 CHANGELOG 却写着“improved error handling”，就会产生误导。R 级验证器无法从语义层面读取 CHANGELOG。

Output Format

输出格式

Return findings as a markdown block per skill reviewed, using this exact structure. The block goes in the response to the caller; do not write it to a file.

markdown

undefined

对每个已审查的 Skill，按以下确切结构返回一个 markdown 块。该块应放入对调用方的响应中；不要将其写入文件。

markdown

undefined

Quality review —

<path/to/SKILL.md>

质量审查 —

<path/to/SKILL.md>

Blocking findings

<short title> — Best-practice violated: <section name>. Quote: "<offending text>". Why it harms the agent: <1 sentence>. Suggested fix: <1 sentence>.

Should fix

(same shape)

Optional polish

(same shape, only if non-trivial)

Verdict: Approve / Approve with comments / Request changes


When reviewing more than one skill in the same call, emit one such block per skill, in the order they were named.

Keep findings **action-oriented**. A finding like "the prose feels long" is not actionable; "lines 40-90 explain what XML namespaces are — Claude knows. Cut to one line referencing the canonical XSD section" is actionable.

阻塞性问题

<简短标题> — 违反的最佳实践：<章节名称>。引用："<有问题的文本>"。对 Agent 的影响：<1 句>。建议修复：<1 句>。

应修复项

（格式同上）

可选优化

（格式同上，仅在具有实质意义时列出）

结论：批准 / 批准但有意见 / 请求修改


一次调用中审查多个 Skill 时，请按照指定顺序为每个 Skill 输出一个这样的块。

发现问题应**具有可操作性**。诸如“正文感觉太长”不是可操作发现；“第 40–90 行解释了 XML namespace——Claude 已经知道。将其缩减为一行，并引用规范的 XSD 章节”才是可操作发现。

Anti-Patterns to Avoid in the Review Itself

审查本身应避免的反模式

Do not invent rules beyond
```
references/anthropic-best-practices.md
```
. If something feels wrong but doesn't violate a documented principle, don't flag it as a finding — at most note as optional polish with that caveat.
Do not nit-pick prose style (Oxford commas, sentence length). Best-practices doc is about token efficiency and discoverability, not English-teacher polish.
Do not over-trigger. If the SKILL.md is short and clear, just say "Approve — no findings" and move on. Padding the review with weak findings dilutes the strong ones.
Cite literally. Every finding must include a real quote from the SKILL.md and a real section name from the best-practices reference.

不要臆造规则——不得超出
```
references/anthropic-best-practices.md
```
的范围。如果某项内容感觉不对，但未违反有文档依据的原则，就不要将其标记为发现；最多可以将其作为可选优化提及，并附带相应说明。
不要吹毛求疵地挑文案风格（牛津逗号、句子长度）。最佳实践文档关注的是 Token 效率和可发现性，而不是英语教师式润色。
不要过度触发——如果 SKILL.md 简短且清晰，只需说明“批准——无发现”并继续。用弱发现填充审查只会稀释重要发现。
逐字引用——每项发现都必须包含 SKILL.md 中的真实原文，以及最佳实践参考文档中的真实章节名称。

Reference

参考资料

```
references/anthropic-best-practices.md
```
— vendored copy of Anthropic's official agent-skill best-practices doc (fetched 2026-06-10). Re-fetch with
```
defuddle parse <url> --md
```
if Anthropic publishes updates.
```
docs/job-template.md
```
— repo-canonical JTBD template; new JTBD skills should structurally match it.
```
docs/jobs-readme.md
```
— guide explaining the JTBD format and its triple purpose (AI skill, doc, executable spec).
```
docs/x-jobs-to-be-done-schema.md
```
— JTBD schema reference.
```
skills/skills-metadata.yaml
```
(and per-bundle
```
<bundle>/skills-metadata.yaml
```
) — declares
```
type: jtbd
```
(default) or
```
type: prose
```
per skill. Drives type-specific review dimensions.
```
scripts/build/validate_skills.py
```
— deterministic R1–R7 structural validator (R1: name↔dir, R2: kebab-case, R3: uniqueness, R4: required metadata, R5: cross-refs, R6: type resolvable, R7: type↔structure). This skill complements those checks; it does not duplicate them.
```
scripts/build/validate_jtbd.py
```
— deterministic JTBD-format validator (frontmatter, step numbering, YAML step blocks, dependencies). Run before this skill — fix structural errors first.
```
.claude/skills/validate-imperative-format/SKILL.md
```
— sibling skill that validates API
```
info.description
```
imperative voice. Same principle applies to JTBD step titles; reuse its criteria there.

```
references/anthropic-best-practices.md
```
——Anthropic 官方 Agent Skill 最佳实践文档的随仓库引入副本（获取于 2026-06-10）。如果 Anthropic 发布更新，使用
```
defuddle parse <url> --md
```
重新获取。
```
docs/job-template.md
```
——仓库的标准 JTBD 模板；新的 JTBD Skill 应在结构上与其保持一致。
```
docs/jobs-readme.md
```
——解释 JTBD 格式及其三重用途（AI Skill、文档、可执行规范）的指南。
```
docs/x-jobs-to-be-done-schema.md
```
——JTBD schema 参考文档。
```
skills/skills-metadata.yaml
```
（以及每个 bundle 的
```
<bundle>/skills-metadata.yaml
```
）——为每个 Skill 声明
```
type: jtbd
```
（默认）或
```
type: prose
```
。它决定需要应用哪些类型特定审查维度。
```
scripts/build/validate_skills.py
```
——确定性的 R1–R7 结构验证器（R1：名称↔目录，R2：kebab-case，R3：唯一性，R4：必需 metadata，R5：交叉引用，R6：类型可解析，R7：类型↔结构）。本 Skill 补充这些检查，不重复它们。
```
scripts/build/validate_jtbd.py
```
——确定性的 JTBD 格式验证器（frontmatter、步骤编号、YAML 步骤块、依赖关系）。运行本 Skill 前先运行它——先修复结构错误。
```
.claude/skills/validate-imperative-format/SKILL.md
```
——用于验证 API
```
info.description
```
祈使语气的同级 Skill。JTBD 步骤标题适用相同原则，可复用其中的标准。