review-skill

技能审查

审查 Agent Skill PR 的结构有效性、设计质量和市场一致性。

参数

• $ARGUMENTS：审查结果的输出文件路径（必需，由调用方框架或用户传入）
• --base <branch>：用于比较差异的基准分支（默认值：main）

工作流

步骤 1：解析参数

从 $ARGUMENTS 中提取输出路径。如果未提供路径，则默认为 .review-output.md。如果提供了 --base，则提取其值；否则默认为 main。

步骤 2：识别发生变更的技能

git diff --name-only $(git merge-base HEAD <base>)..<HEAD> | grep -E '(SKILL\.md|skills/[^/]+/)'

按技能目录对变更文件分组。每个不同的技能目录都是一个审查目标。如果没有技能文件发生变更，则将 "No skill files changed" 写入输出路径并停止。

步骤 3：从头到尾阅读每个发生变更的技能

对于每个发生变更的技能：

1. 阅读完整的 SKILL.md（而不仅仅是差异行）
2. 阅读技能目录中的所有文件（参考资料、脚本）
3. 记录父插件目录，并找到其中的 plugin.json

步骤 4：运行结构检查（高置信度）

执行 references/structural-checks.md 中的所有检查。这些检查采用二元通过/不通过判定，违规情况明确无误。

结构违规属于高置信度，因为可以通过机械方式验证。

步骤 5：运行设计检查（中置信度）

执行 references/design-checks.md 中的所有检查。这些检查需要判断；只有问题明确时才标记，不要仅仅因为做法与你的选择不同就标记。

设计问题属于中置信度，因为涉及主观判断。

步骤 6：运行市场检查（高置信度）

执行 references/marketplace-checks.md 中的所有检查。这些检查用于验证技能是否与所属市场正确集成。

市场违规属于高置信度，因为可以通过阅读清单文件验证。

步骤 7：加载并应用验证协议

加载 review-verification-protocol 技能。报告任何发现之前，请先验证：

1. 你阅读了实际技能内容，而不仅仅是差异上下文
2. 问题确实存在，而非风格偏好
3. 问题具体适用于技能文件（而非一般代码审查问题）
4. 你可以指出能够证明问题的具体行

删除所有无法验证的发现。

步骤 8：写入输出

按照以下确切格式，将所有发现写入步骤 1 中指定的输出路径。

输出格式

## Review Summary

[1-2 sentence overview of findings across all reviewed skills]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters for skill quality or marketplace health
   - Fix: Specific recommended fix
   - Confidence: HIGH

### Major (Should Fix)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...
   - Confidence: HIGH|MEDIUM

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...
   - Confidence: HIGH|MEDIUM

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...
   - Confidence: MEDIUM

## Verdict

Ready: Yes | No | With fixes 1-N
Rationale: [1-2 sentences — only Critical and Major items block approval]

每个问题都应有连续编号。每个问题都应包含 Confidence: HIGH|MEDIUM。判定结果不考虑轻微和信息性问题。

严重性分级

严重（阻止合并）

• YAML frontmatter 无效或缺失（技能无法加载）
• 缺少必需的 name 或 description 字段
• SKILL.md 超过 500 行（导致性能下降）
• 与市场中现有技能的名称冲突

主要（应修复）

• name 不符合格式规则（不是 kebab-case、过长或为保留字）
• description 缺少“是什么”或“何时使用”要素、使用了错误的人称，或超过 1024 个字符
• 嵌套参考链（参考资料又引用其他参考资料）
• description 过于含糊，无法准确触发
• 结构化输出没有格式模板或示例
• 文件引用中使用 Windows 风格路径

轻微（有则更好）

• 内容有时效性（硬编码日期、“最近”、“新”等）
• 技能文件间术语不一致
• SKILL.md 内容密集，却未使用渐进式披露
• 工作流缺少验证步骤
• 缺少交叉引用（SKILL.md 链接到不存在的文件）

信息性（供参考）

• 与市场中现有技能的触发关键词重叠
• 建议添加其他参考文件
• 有机会提高描述的具体性
• 脚本缺少 --help 或使用交互式提示

复审规则

在修复完成后的后续审查中：

1. 仅核实先前标记的问题是否已正确解决
2. 不要提出与先前问题无关的新发现
3. 接受未修复的次要问题，不要再次标记
4. 复审的目标是核实，而不是发现新问题

参考资料

• 结构检查：references/structural-checks.md — frontmatter、命名、行数限制、路径格式
• 设计检查：references/design-checks.md — 描述质量、渐进式披露、自由度
• 市场检查：references/marketplace-checks.md — 名称冲突、plugin.json 一致性、触发条件重叠