skill-quality-reviewer

スキル品質レビュアー

概要

Claude Skills の品質を評価するメタスキルです。説明の品質（25%）、コンテンツの構成（30%）、文体（20%）、構造の整合性（25%）という4つの主要な観点から包括的に分析し、加重スコア、レターグレード、実行可能な改善計画を作成します。

スキルを共有する前の検証、改善機会の特定、スキル開発のベストプラクティスへの準拠確認に使用します。

このスキルを使用するタイミング

次の場合にこのスキルを呼び出します：

• 配布前にスキルの品質を分析する
• スキルのドキュメントをベストプラクティスに照らしてレビューする
• スキル開発標準への準拠状況を評価する
• 既存スキルの改善提案を作成する
• スキルの構造と完全性を検証する

トリガーフレーズ：

• 「./my-skill のスキル品質を分析して」
• 「このスキルを評価して：~/.claude/skills/api-helper」
• 「git-workflow のスキル品質をレビューして」
• 「自分のスキルがベストプラクティスに沿っているか確認して」
• 「このスキルの品質レポートを作成して」

レビューモード

タスクに応じて、次の3つのレビューモードのいずれかを使用します：

1. score-only
   • 1つのスキルをすばやく初回評価します。
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 フロントマターを解析する

SKILL.md から YAML フロントマターを抽出し、検証します。

必須フィールド：

• name - スキルの識別子
• description - トリガーフレーズを含む説明

確認項目：

• YAML 構文が有効である
• 禁止フィールドが含まれていない
• 書式が適切である

ステップ 3：説明の品質を評価する（25%）

フロントマターの説明の品質と有効性を評価します。

採点内訳：

基準	点数	評価
トリガーフレーズの明確さ	25	具体的なユーザーフレーズが3～5個ある
三人称形式	25	「This skill should be used when...」という表現を使用している
説明の長さ	25	100～300文字が理想
具体的なシナリオ	25	曖昧ではなく、具体的なユースケースがある

注意すべき点：

• 「タスクに役立つ」などの曖昧なトリガー
• 二人称の説明（「Use this when you...」）
• 説明がない、または一般的すぎる説明
• 実行可能なトリガーフレーズがない

参考： 模範的な説明については 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 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 フロントマター	30	必須フィールドがすべて存在する
ディレクトリ構造	30	適切に整理されている
リソースの参照	40	参照されているファイルがすべて存在する

検証項目：

• YAML フロントマターに 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：レポートを生成する

現在の作業ディレクトリに 2 つのドキュメントを作成します。

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}

理由：{品質がどのように向上するか}

[すべての問題について続ける...]

簡単にできる改善

1. {簡単な修正}
2. {簡単な修正}

完了までの推定時間

• 優先度：高：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 が評価し、以下を報告します：]

• 全体の一覧表
• 問題の分類グループ
• 2 回目の修正作業に向けた候補リスト