Created
March 11, 2026 15:12
-
-
Save taichi/9b8f9c9bbd2b394ae9e688e682d5d89b to your computer and use it in GitHub Desktop.
https://claude.com/blog/complete-guide-to-building-skills-for-claude からエッセンスを抽出しつつ、自分の観点をいくつか追加したスキルのレビュースキル
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| --- | |
| name: skill-review | |
| description: >- | |
| スキル定義（SKILL.md）とエージェント定義の品質をレビューし改善提案を出す。 | |
| 「スキルをレビューして」「SKILL.mdをチェックして」「エージェント定義を見直して」 | |
| 「スキルの品質を確認」「設定をレビュー」など、スキルやエージェントの | |
| 定義ファイルの品質改善が必要な場合に使用する。 | |
| 新規スキル作成後や既存スキル改修後の品質チェックに積極的に使う。 | |
| argument-hint: "[skill or agent path] (e.g., .claude/skills/draft/SKILL.md)" | |
| allowed-tools: Read, Glob, Grep | |
| model: sonnet | |
| metadata: | |
| version: 0.1.0 | |
| --- | |
| # Skill Review | |
| スキル定義（SKILL.md）とエージェント定義（agents/*.md）の品質を、 | |
| Anthropic公式ガイドラインとプロジェクト固有のパターンの両面からレビューする。 | |
| ## 入力 | |
| 渡された引数: $ARGUMENTS | |
| - パスが指定された場合: そのファイルまたはディレクトリをレビュー対象とする | |
| - パスが未指定の場合: `.claude/skills/` と `.claude/agents/` 配下の全ファイルを対象とする | |
| ## レビュー手順 | |
| ### 1. 対象ファイルの収集 | |
| Glob で対象ファイルを列挙し、Read で内容を取得する。 | |
| - スキル: `.claude/skills/*/SKILL.md` | |
| - エージェント: `.claude/agents/*.md` | |
| - スキーマ: `.claude/skills/*/schemas/*.json`（存在する場合） | |
| - リファレンス: `.claude/skills/*/references/*.md`（存在する場合） | |
| ### 2. レビュー実行 | |
| 各ファイルに対して以下の観点でレビューする。 | |
| 観点ごとに pass / warning / critical を判定する。 | |
| ### 3. レポート出力 | |
| 結果をユーザーに報告する。critical → warning の順に、具体的な修正案を添えて提示する。 | |
| ## レビュー観点 | |
| ### A. YAML Frontmatter（スキル・エージェント共通） | |
| | # | 観点 | 判定基準 | | |
| |---|---|---| | |
| | A1 | name | kebab-case かつ64文字以内であること。スペース・大文字・アンダースコアは critical。64文字超過は critical | | |
| | A2 | description | WHAT（何をするか）と WHEN（いつ使うか）の両方を含むこと。片方欠落は warning | | |
| | A3 | description trigger phrases | ユーザーが実際に言いそうなフレーズを含むこと。抽象的すぎる場合は warning | | |
| | A4 | description length | 1024文字以内であること。超過は critical | | |
| | A5 | XML tags | frontmatter内に `<` `>` を含まないこと。含む場合は critical | | |
| | A6 | argument-hint | スキルがオプション引数を持つ場合、argument-hint に反映されていること。欠落は warning | | |
| ### B. Progressive Disclosure（スキル） | |
| | # | 観点 | 判定基準 | | |
| |---|---|---| | |
| | B1 | SKILL.md行数 | 500行以内が理想。超過している場合、references/ への分離を提案（warning） | | |
| | B2 | references配置 | 大きな参照情報がSKILL.md本体にインラインで埋め込まれていないこと。300行超のセクションは分離候補（warning） | | |
| | B3 | references参照 | references/ ファイルがSKILL.mdから明確にリンク・参照されていること。孤立ファイルは warning | | |
| ### C. 出力フォーマット（エージェント） | |
| エージェントがファイル出力を行う場合に適用する。 | |
| 構造化の必要度は「出力を誰が・どう消費するか」で決まる。 | |
| 一律にJSONスキーマを求めるのではなく、以下の判定フローで評価する。 | |
| #### C0. 消費パターンの特定（判定フロー） | |
| エージェントの出力先ファイルを特定し、親スキルや下流エージェントでの消費方法を確認する。 | |
| 1. **親スキル/下流が出力をパースして分岐判定に使うか？** | |
| （例: `recommendation` フィールドで pass/revise を分岐、判定ラベルでリトライ判定） | |
| → Yes → **消費パターンA**（プログラム的消費） | |
| 2. **下流が特定のセクション見出しを前提に内容を参照するか？** | |
| （例: 親スキルが「Constraints」「Risks」セクションから質問を生成） | |
| → Yes → **消費パターンB**（セクション見出し消費） | |
| 3. **中間成果物で、構造が複雑か？** | |
| → Yes → **消費パターンC**（構造的中間成果物） | |
| 4. **最終成果物（人間が読む設計文書等）か？** | |
| → Yes → **消費パターンD**（最終成果物） | |
| | # | 観点 | 適用パターン | 判定基準 | | |
| |---|---|---|---| | |
| | C1 | 構造化出力 | A のみ | JSONスキーマで定義されていること。パターンAでスキーマ未定義は critical | | |
| | C2 | スキーマ参照 | A のみ | スキーマファイルへの相対パスが記載されていること。パターンAでパスなしは warning | | |
| | C3 | 出力例 | A, B | 具体的な出力例が含まれていること。パターンA で例なしは warning、パターンB は info | | |
| | C4 | セクション構成の固定 | B | 親スキルが参照するセクション見出しがエージェント定義で明示されていること。未明示は warning | | |
| | C5 | 過剰な構造化 | C, D | パターンC/DにJSONスキーマを要求していないこと。過剰な構造化は info（柔軟性を損なう） | | |
| パターンB/Dでは、セクション内の記述は自由形式で問題ない（LLMが自然言語として解釈するため）。 | |
| ### D. ワークフロー構造（スキル） | |
| | # | 観点 | 判定基準 | | |
| |---|---|---| | |
| | D1 | サブエージェント委譲 | 複雑なマルチステップワークフローが単一スキル内で完結していないこと。5ステップ以上のワークフローでサブエージェント委譲がない場合は info | | |
| | D2 | エラーハンドリング | 失敗時の対処方法が記載されていること。記載なしは warning | | |
| | D3 | 完了報告 | 完了時の報告形式が定義されていること。未定義は info | | |
| ### E. 指示の品質 | |
| | # | 観点 | 判定基準 | | |
| |---|---|---| | |
| | E1 | 具体性 | 指示が具体的でアクション可能であること。「適切に処理する」等の曖昧表現は warning | | |
| | E2 | WHYの説明 | 重要な制約にはその理由が説明されていること。理由なしの MUST/NEVER/ALWAYS は warning | | |
| | E3 | 例の有無 | 入出力の具体例が含まれていること。例なしは warning | | |
| | E4 | ツール指定 | 使用すべきツールが明示されていること（Read, Write, Glob等）。暗黙的なツール使用は info | | |
| ### F. メタデータ・一貫性 | |
| | # | 観点 | 判定基準 | | |
| |---|---|---| | |
| | F1 | metadata.version | version フィールドが存在すること。欠落は info | | |
| | F2 | 命名一貫性 | スキルフォルダ名と frontmatter の name が一致すること。不一致は critical | | |
| | F3 | エージェント-スキル整合 | エージェントが参照するスキーマパスが実在すること。存在しないパスは critical | | |
| ## レポート形式 | |
| ```text | |
| # Skill Review Report | |
| ## Summary | |
| - Reviewed: N files | |
| - Critical: N | |
| - Warning: N | |
| - Info: N | |
| ## Critical | |
| ### [C1] <ファイルパス> | |
| - 観点: <観点ID + 名前> | |
| - 内容: <問題の説明> | |
| - 修正案: <具体的な修正方法> | |
| ## Warning | |
| ### [W1] <ファイルパス> | |
| ... | |
| ## Info | |
| ### [I1] <ファイルパス> | |
| ... | |
| ``` | |
| ### G. 容量制限（全体） | |
| スキルが個別制限を守っていても、全体の合計が予算を超過するとスキルがコンテキストから除外される。 | |
| 対象パス未指定（全スキルレビュー）の場合にのみ適用する。 | |
| | # | 観点 | 判定基準 | | |
| |---|---|---| | |
| | G1 | description合計文字数 | 全スキル・エージェントの description 合計が16,000文字以内であること。超過は warning（一部スキルがコンテキストから除外される可能性がある） | | |
| | G2 | description効率 | 個々の description が冗長でないこと。WHAT+WHEN を維持しつつ、不要なフレーズの重複や過度な列挙がある場合は info（合計予算を圧迫する） | | |
| 備考: 合計予算はコンテキストウィンドウの2%（フォールバック16,000文字）。環境変数 `SLASH_COMMAND_TOOL_CHAR_BUDGET` でオーバーライド可能。 | |
| ## 注意事項 | |
| - レビューは非破壊的な読み取り専用操作として行う。ファイルの変更は行わない | |
| - 修正案は具体的なコード片やYAMLスニペットを含めて提示する | |
| - プロジェクト固有のパターン（JSON出力、スキーマ参照等）は既存スキルの実装を参照して判断する |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment