skill-quality-reviewer

技能质量审查员

概述

用于评估 Claude Skills 质量的元技能。围绕四个关键维度进行全面分析——描述质量（25%）、内容组织（30%）、写作风格（20%）和结构完整性（25%）——生成加权评分、字母等级和可执行的改进计划。

使用此技能可在分享技能前进行验证、发现改进机会，或确保符合技能开发最佳实践。

何时使用此技能

在以下情况下调用此技能：

• 发布前分析技能质量
• 审查技能文档是否符合最佳实践
• 评估是否遵循技能开发标准
• 为现有技能生成改进建议
• 验证技能结构和完整性

触发短语：

• “分析 ./my-skill 的技能质量”
• “评估此技能：~/.claude/skills/api-helper”
• “审查 git-workflow 的技能质量”
• “检查我的技能是否符合最佳实践”
• “为此技能生成质量报告”

审查模式

根据任务使用以下三种审查模式之一：

1. score-only
   • 对单个技能进行快速初步评分。
2. remediation-backlog
   • 将发现的问题转化为包含具体证据的 P0 / P1 / P2 修复队列。
3. batch-portfolio
   • 一并审查多个技能，将重复问题归类，并生成按优先级排序的候选清单。

当用户询问接下来应该修复什么时，优先使用 remediation-backlog。 一次审核多个技能时，优先使用 batch-portfolio。

分析工作流

步骤 1：加载技能

接受技能路径作为输入。验证该路径存在且包含 SKILL.md。读取完整的技能目录结构。

# Example invocation
ls -la ~/.claude/skills/target-skill/

验证：

• SKILL.md 存在
• 目录可读取
• 路径指向有效技能

步骤 2：解析 YAML Frontmatter

从 SKILL.md 中提取并验证 YAML frontmatter。

必需字段：

• name - 技能标识符
• description - 包含触发短语的触发说明

检查：

• YAML 语法有效
• 不包含禁止字段
• 格式正确

步骤 3：评估描述质量（25%）

评估 frontmatter 描述的质量和有效性。

评分细则：

标准	分值	评估
触发短语清晰度	25	包含 3-5 个具体的用户短语
第三人称格式	25	使用“This skill should be used when...”
描述长度	25	100-300 个字符为宜
具体场景	25	提供具体用例，而非含糊描述

风险信号：

• “帮助处理任务”等含糊的触发语
• 第二人称描述（“在……时使用此技能”）
• 缺少描述或描述过于笼统
• 没有可执行的触发短语

参考： references/examples-good.md 中的优秀描述示例

步骤 4：评估内容组织（30%）

评估是否遵循渐进式披露原则。

评分细则：

标准	分值	评估
渐进式披露	30	SKILL.md 简洁，详细内容放在 references/ 中
SKILL.md 长度	25	少于 5,000 个单词（理想长度为 1,500-2,000 个单词）
References/ 的使用	25	详细内容已妥善移出
逻辑组织	20	章节清晰，结构流畅

检查：

• SKILL.md 正文简洁且重点突出
• 详细内容已移至 references/
• 示例和模板放在适当的目录中
• 文件之间没有信息重复

参考： references/scoring-criteria.md 中的详细评分标准

第 5 步：评估写作风格（20%）

检查是否遵循技能写作规范。

评分明细：

标准	分值	评估
祈使句形式	40	全程使用动词开头的指令
正文中不使用第二人称	30	避免在主要工作流正文中使用对话式第二人称
客观表述	30	采用客观、指导性的语气

检查以下内容：

• 祈使动词：“Create the file”“Validate input”“Check structure”
• 避免使用：“You should”“You can”“You need to”
• 语言客观、具有指导性
• 全文风格一致

正面示例：

Create the skill directory structure.
Validate the YAML frontmatter.
Check for required fields.

反面示例：

You should create the directory.
You need to validate the frontmatter.
Check if the fields are there.

第 6 步：评估结构完整性（25%）

检查技能的实际结构和完整性。

评分明细：

标准	分值	评估
YAML frontmatter	30	包含所有必需字段
目录结构	30	组织规范
资源引用	40	所有引用的文件均存在

验证以下内容：

• YAML frontmatter 包含 name 和 description
• 目录结构符合规范：

  skill-name/
  ├── SKILL.md
  ├── references/ (optional)
  ├── examples/ (optional)
  └── scripts/ (optional)
  

• SKILL.md 中引用的所有文件均实际存在
• 示例完整且可运行
• 脚本可执行

第 7 步：计算加权分数

使用加权维度计算总体质量分数。

公式：

Overall Score = (Description × 0.25) + (Organization × 0.30) +
                (Style × 0.20) + (Structure × 0.25)

等级映射：

分数范围	等级	含义
97-100	A+	卓越
93-96	A	优秀
90-92	A-	很好
87-89	B+	良好
83-86	B	高于平均水平
80-82	B-	扎实
77-79	C+	可接受
73-76	C	满意
70-72	C-	勉强可接受
67-69	D+	低于标准
63-66	D	较差
60-62	D-	很差
0-59	F	不及格

第 8 步：生成报告

在当前工作目录中创建两份输出文档。

1. 质量报告（quality-report-{skill-name}.md）

• 执行摘要，包含总分和等级
• 按维度逐项列出明细
• 列出各维度的优势和不足
• 等级明细表
• 改进计划链接

2. 改进计划（improvement-plan-{skill-name}.md）

• 按优先级排列的改进清单（高/中/低）
• 问题对应的具体文件位置和行号
• 当前内容与建议内容对比
• 对分数的预估影响
• 修复所需时间估算
• 预期分数提升

输出模板

质量报告模板

# Skill Quality Report: {skill-name}

## Executive Summary
- **Overall Score**: X/100 ({Grade})
- **Evaluated**: {Date}
- **Skill Path**: {path}

## Dimension Scores

### 1. Description Quality (25%)
**Score**: X/100

**Strengths**:
- ✅ {specific strength}

**Weaknesses**:
- ❌ {specific weakness}

**Recommendations**:
1. {actionable recommendation}

[Repeat for other dimensions...]

## Grade Breakdown
| Dimension | Score | Weight | Contribution |
|-----------|-------|--------|--------------|
| Description | X/100 | 25% | X.X |
| Organization | X/100 | 30% | X.X |
| Style | X/100 | 20% | X.X |
| Structure | X/100 | 25% | X.X |
| **Overall** | **X/100** | **100%** | **X.X ({Grade})** |

## Next Steps
See `improvement-plan-{skill-name}.md` for detailed improvement suggestions.

改进计划模板

# Skill Improvement Plan: {skill-name}

## Priority Summary
- **High Priority**: {count} items
- **Medium Priority**: {count} items
- **Low Priority**: {count} items

## High Priority Improvements

### 1. [Issue Title]
**File**: SKILL.md:line:line
**Dimension**: Description Quality
**Impact**: +X points

**Current**:
```yaml
{current content}

建议：

{suggested content}

原因：{why this improves quality}

[继续列出所有问题...]

快速见效的改进（轻松修复）

1. {quick fix}
2. {quick fix}

预计完成时间

• 高优先级：X 小时
• 中优先级：X 小时
• 低优先级：X 小时
• 总计：X 小时

预期分数提升

• 当前：X/100（{Grade}）
• 完成高优先级后：X/100（{Grade}）
• 全部完成后：X/100（{Grade}）

## Additional Resources

### Reference Files

For detailed evaluation criteria and examples, consult:

- **`references/scoring-criteria.md`** - Comprehensive scoring rubrics for each dimension
- **`references/examples-good.md`** - Exemplary skills demonstrating best practices
- **`references/examples-bad.md`** - Common anti-patterns to avoid

### Scripts

- **`scripts/extract-yaml.sh`** - Utility for extracting YAML frontmatter from SKILL.md
- **`scripts/skill-audit.py`** - Lightweight integrity audit for missing references, word count, and sibling-path checks

### Related Skills

- **`skill-development`** - Comprehensive guide for creating skills
- **`code-review-excellence`** - Best practices for code review

## Best Practices

### When Analyzing Skills

1. **Be objective and specific** - Base scores on observable criteria, not opinions
2. **Provide actionable feedback** - Each recommendation should be concrete and implementable
3. **Include examples** - Show current vs. suggested content for clarity
4. **Estimate impact** - Help users understand which changes matter most
5. **Be constructive** - Frame feedback as opportunities for improvement

### Common Quality Issues

**Description Quality:**
- Vague or generic trigger phrases
- Second-person descriptions
- Missing concrete use cases

**Content Organization:**
- SKILL.md too long (>5,000 words)
- Detailed content not moved to references/
- Poor information hierarchy

**Writing Style:**
- Second-person language ("you", "your")
- Mixed imperative and descriptive styles
- Subjective or conversational tone

**Structural Integrity:**
- Missing required YAML fields
- Referenced files don't exist
- Incomplete examples or broken scripts

### Grade Benchmarks

**A grade (90-100)**: Exemplary skills serving as templates for others
- All dimensions score 85+
- Clear, specific descriptions
- Excellent progressive disclosure
- Consistent imperative style
- Complete, well-organized structure

**B grade (80-89)**: High-quality skills with minor improvements needed
- Most dimensions score 75+
- Good descriptions and organization
- Generally follows best practices
- May have minor style inconsistencies

**C grade (70-79)**: Acceptable skills requiring moderate improvements
- Key areas meet minimum standards
- Some weaknesses in organization or style
- Functional but not exemplary

**D/F grade (below 70)**: Skills needing significant work
- Multiple dimensions below 70
- Major structural or style issues
- Requires comprehensive revision

## Usage Examples

**Example 1: Analyze a local skill**

用户：“分析 ~/.claude/skills/git-workflow 的技能质量”

[Claude 执行这套 8 步工作流并生成：]

• quality-report-git-workflow.md
• improvement-plan-git-workflow.md

**Example 2: Review before sharing**

用户：“在发布前检查我的新技能”

[Claude 分析技能并提供：]

• 详细的质量评估
• 具体的改进建议
• 实施修复后的预期分数

**Example 3: Quality check for existing skill**

用户：“检查 api-helper 的技能质量”

[Claude 评估并报告：]

• 当前等级和分数
• 最值得改进的方面
• 轻松提高分数的快速见效项

**Example 4: Batch portfolio review**

用户：“检查 ~/.claude/skills 中的所有技能，并告诉我应该先修复什么”

[Claude 评估并报告：]

• 技能组合矩阵
• 分类汇总的问题集群
• 二次修复的候选清单