skill-review

スキルレビュー

概要

エージェントスキルを Agent Skills 標準およびまとめられたベストプラクティスに照らして検証します。構造、フロントマター、説明の品質、段階的な情報開示、一般的なアンチパターンをレビューします。

使用するタイミング

• ユーザーがスキルのレビューまたは検証を依頼した場合
• ユーザーが新しいスキルを作成していて、フィードバックを求めている場合
• ユーザーが「このスキルは適切に書かれていますか？」と尋ねた場合
• ユーザーがスキルの品質、ベストプラクティス、改善について言及した場合

レビュープロセス

フェーズ 1：参考資料を読み込む

レビューの前に、以下を読みます。

• references/best-practices.md — 包括的なガイドライン
• references/checklist.md — 簡易検証チェックリスト

フェーズ 2：対象を特定する

レビュー対象を判断します。

• 単一のスキル：skills/<name>/SKILL.md とその構造をレビューします
• すべてのスキル：skills/ ディレクトリ全体を監査します
• 新しいスキルの草案：作成前に提供された内容をレビューします

フェーズ 3：構造の監査

スキルのディレクトリ構造を確認します。

skill-name/
├── SKILL.md              # Required
├── references/           # Optional - loaded docs
├── scripts/              # Optional - executable code
└── assets/               # Optional - output files (not loaded)

確認事項：

• SKILL.md が存在する
• ディレクトリ名がフロントマターの name と一致する
• 参照ファイルは 1 階層までである（入れ子の連鎖がない）
• スクリプトではスラッシュを使用している（Windows パスがない）
• 不要なファイル（README.md、CHANGELOG.md など）がない
• SKILL.md 本文のスクリプトパス（scripts/foo.py）がディレクトリ内に存在する
• スクリプトが外部バイナリを使用する場合、依存関係が記載されている

フェーズ 4：フロントマターの検証

YAML フロントマターを確認します。

---
name: skill-name          # Required: lowercase, hyphens, ≤64 chars
description: >-           # Required: ≤1024 chars, third-person
  What it does. When to use it.
---

検証項目：

• name：小文字とハイフンのみ（[a-z0-9-]）
• name：64 文字以下
• name：「anthropic」または「claude」を含まない
• description：空でなく、1024 文字以下
• description：三人称で書かれている（「I can」や「You can」ではない）
• description：機能と使用するタイミングの両方を含む
• description：具体的なトリガーフレーズを含む

フェーズ 5：説明の品質

説明はトリガーの仕組みそのものです。以下を評価します。

良い説明に含まれるもの：

• 具体的な操作：「PDF ファイルからテキストと表を抽出する」
• トリガーフレーズ：「Excel ファイル、スプレッドシート、.xlsx を分析する場合に使用」
• ユーザーが使いそうな類義語：「表形式データ、CSV、ワークブック」

悪い説明の例：

• 曖昧：「ドキュメントを支援する」
• 一般的：「データを処理する」
• トリガーがない：「スプレッドシートを分析する」（「使用するタイミング」がない）

フェーズ 6：本文の分析

SKILL.md の本文をレビューします。

長さ：

• 500 行未満（wc -l で確認）
• それより長い場合は、参照ファイルに分割する

段階的な情報開示：

• 冒頭付近にクイックスタートまたは概要がある
• 詳細は references/ に移されている
• 長い参照ファイル（100 行超）に目次がある

トークン効率：

• 自明な説明がない（Claude はすでに理解している）
• 長い文章より例を優先している
• 各行がトークン消費に見合っている

自由度：

• コンテキストに依存するタスクでは自由度が高い
• 壊れやすい、またはエラーが起こりやすいタスクでは自由度が低い
• 複数の選択肢がある場合、既定値が示されている

フェーズ 7：アンチパターンの確認

一般的な問題がないか確認します。

アンチパターン	確認する内容
Windows パス	scripts/file.py ではなく scripts\file.py
入れ子の参照	A.md → B.md → C.md の連鎖
時間依存の情報	「2025 年 8 月より前の場合は……」
マジックナンバー	説明のない値
選択肢が多すぎる	既定値なしに「X、Y、Z のいずれかを使用できます……」
用語の不統一	「endpoint」／「URL」／「route」の混用
ユーザー向けドキュメント	README、CHANGELOG、インストールガイド
一人称・二人称の説明	「I can help」や「You can use」

フェーズ 8：レビュー結果を報告する

以下の形式で結果を提示します。

## Skill Review: [skill-name]

### Summary
[1-2 sentence overall assessment]

### Structure
[✓/✗] Directory organization
[✓/✗] File presence
[✓/✗] Reference depth

### Frontmatter
[✓/✗] name validation
[✓/✗] description validation

### Description Quality
**Score**: [Strong / Adequate / Needs Work]
**Issues**: [List specific problems]
**Suggested rewrite** (if needed):
```yaml
description: >-
  [Improved description]

本文の分析

行数：[X] 行 トークン効率：[良好／削減の余地あり] 段階的な情報開示：[✓/✗]

見つかったアンチパターン

• [問題 1] — 場所：file:line
• [問題 2] — 場所：file:line

推奨事項

1. [実行可能な修正]
2. [実行可能な修正]

## Quick Review Mode

For rapid validation, run through the checklist in `references/checklist.md` and report only failures.

## Resources

### references/best-practices.md
Comprehensive guide covering architecture, design principles, writing effective descriptions, bundled resources, workflow patterns, and advanced patterns from production skills.

### references/checklist.md
Quick-reference validation checklist for fast reviews.