audit-agents-skills

agents/skills/commands の監査（高度なスキル）

Claude Code のエージェント、スキル、コマンドを包括的に品質監査するシステムです。業界のベストプラクティスに基づき、定量的なスコアリング、比較分析、本番環境への対応状況の評価を行います。

目的

問題：エージェントやスキルの手動検証は、エラーが発生しやすく、一貫性にも欠けます。LangChain Agent Report 2026 によると、組織の 29.5% は体系的な評価を行わずにエージェントをデプロイしており、その結果、「エージェントのバグ」がチームの最大の課題となっています（18%）。

解決策：16 の重み付け基準に基づく自動品質スコアリングと、本番環境への対応状況のしきい値を提供します（本番環境へのデプロイには 80% 以上、最低でもグレード B が必要です）。

主な機能：

• 定量的なスコアリング（エージェント／スキルは 32 点、コマンドは 20 点）
• 重み付け基準（Identity は 3 倍、Prompt は 2 倍、Validation は 1 倍、Design は 2 倍）
• 本番環境への対応状況の評価（しきい値 80% の A〜F 評価）
• 参照テンプレートとの比較分析
• プログラムによる統合に対応した JSON／Markdown の両形式での出力
• 基準を満たさない項目の修正案

---

モード

モード	用途	出力
クイック監査	重要度の高い上位 5 項目のみ	高速な合否判定（20 ファイルで 3〜5 分）
完全監査	ファイルごとに全 16 項目を確認	詳細なスコアと推奨事項（10〜15 分）
比較	完全監査に加え、テンプレートをベンチマークとして比較	分析とギャップの特定（15〜20 分）

デフォルト：完全監査（初回の実行に推奨）

---

方法論

この基準を採用する理由

16 項目のフレームワークは、以下に基づいています。

1. Claude Code のベストプラクティス（Ultimate Guide の 4921 行目：Agent Validation Checklist）
2. 業界データ（LangChain Agent Report 2026：評価の不足）
3. 本番環境での障害（ハードコードされたパスやエラーハンドリングの不足に関するコミュニティからのフィードバック）
4. 構成パターン（スキルは他のスキルを参照し、エージェントはモジュール化されているべきです）

スコアリングの方針

重み付けの理由：

• Identity（3 倍）：ユーザーがエージェントを見つけて呼び出せなければ、品質は意味をなしません（品質より見つけやすさが重要です）
• Prompt（2 倍）：出力の信頼性と正確性を左右します
• Validation（1 倍）：堅牢性を高めますが、コア機能より優先度は低い項目です
• Design（2 倍）：長期的な保守性と拡張性に影響します

評価基準：

• A（90〜100%）：本番環境ですぐに利用でき、リスクは最小限です
• B（80〜89%）：良好で、本番環境へのしきい値を満たしています
• C（70〜79%）：本番環境に導入する前に改善が必要です
• D（60〜69%）：大きな不足があり、本番環境への導入には適していません
• F（60% 未満）：重大な問題があり、大規模なリファクタリングが必要です

業界標準との整合性：80% のしきい値は、本番環境へのデプロイにおけるソフトウェアエンジニアリングのベストプラクティス（例：コードカバレッジ 80% 超、セキュリティスキャンの合格率）に沿っています。

---

ワークフロー

フェーズ 1：検出

1. ディレクトリをスキャン：

   .claude/agents/
   .claude/skills/
   .claude/commands/
   examples/agents/      (if exists)
   examples/skills/      (if exists)
   examples/commands/    (if exists)
   

2. ファイルを種類（エージェント／スキル／コマンド）別に分類します

3. 参照テンプレートを読み込み（比較モードの場合）：

   guide/examples/agents/     (benchmark files)
   guide/examples/skills/     (benchmark files)
   guide/examples/commands/   (benchmark files)
   

フェーズ 2：スコアリングエンジン

scoring/criteria.yaml からスコアリング基準を読み込みます。

agents:
  max_points: 32
  categories:
    identity:
      weight: 3
      criteria:
        - id: A1.1
          name: "Clear name"
          points: 3
          detection: "frontmatter.name exists and is descriptive"
        # ... (16 total criteria)

各ファイルについて、以下を行います。

1. フロントマター（YAML）を解析します
2. コンテンツのセクションを抽出します
3. 検出パターン（正規表現、キーワード検索）を実行します
4. スコアを計算します：(points / max_points) × 100
5. グレード（A〜F）を割り当てます

フェーズ 3：比較分析（比較モードのみ）

プロジェクト内の各ファイルについて、以下を行います。

1. 最も近いテンプレートを見つけます（説明の類似度に基づく）
2. 基準ごとにスコアを比較します
3. ギャップを特定します：template_score - project_score
4. 大きなギャップ（差が 10 点超）にフラグを付けます

例：

Project file: .claude/agents/debugging-specialist.md (Score: 78%, Grade C)
Closest template: examples/agents/debugging-specialist.md (Score: 94%, Grade A)

Gaps:
- Anti-hallucination measures: -2 points (template has, project missing)
- Edge cases documented: -1 point (template has 5 examples, project has 1)
- Integration documented: -1 point (template references 3 skills, project none)

Total gap: 16 points (explains C vs A difference)

フェーズ 4：レポートの生成

Markdown レポート（audit-report.md）：

• サマリー表（全体および種類別）
• 主な問題を含む、個別のスコア
• ファイルごとの詳細な内訳（折りたたみ式）
• 優先順位を付けた推奨事項

JSON 出力（audit-report.json）：

{
  "metadata": {
    "project_path": "/path/to/project",
    "audit_date": "2026-02-07",
    "mode": "full",
    "version": "1.0.0"
  },
  "summary": {
    "overall_score": 82.5,
    "overall_grade": "B",
    "total_files": 15,
    "production_ready_count": 10,
    "production_ready_percentage": 66.7
  },
  "by_type": {
    "agents": { "count": 5, "avg_score": 85.2, "grade": "B" },
    "skills": { "count": 8, "avg_score": 78.9, "grade": "C" },
    "commands": { "count": 2, "avg_score": 92.0, "grade": "A" }
  },
  "files": [
    {
      "path": ".claude/agents/debugging-specialist.md",
      "type": "agent",
      "score": 78.1,
      "grade": "C",
      "points_obtained": 25,
      "points_max": 32,
      "failed_criteria": [
        {
          "id": "A2.4",
          "name": "Anti-hallucination measures",
          "points_lost": 2,
          "recommendation": "Add section on source verification"
        }
      ]
    }
  ],
  "top_issues": [
    {
      "issue": "Missing error handling",
      "affected_files": 8,
      "impact": "Runtime failures unhandled",
      "priority": "high"
    }
  ]
}

フェーズ 5：修正案（任意）

基準を満たさない項目ごとに、実行可能な修正案を生成します。

### File: .claude/agents/debugging-specialist.md
**Issue**: Missing anti-hallucination measures (2 points lost)

**Fix**:
Add this section after "Methodology":

## Source Verification

- Always cite sources for technical claims
- Use phrases: "According to [documentation]...", "Based on [tool output]..."
- If uncertain, state: "I don't have verified information on..."
- Never invent: statistics, version numbers, API signatures, stack traces

**Detection**: Grep for keywords: "verify", "cite", "source", "evidence"

---

スコアリング基準

定義の詳細については、scoring/criteria.yaml を参照してください。概要：

エージェント（最大32ポイント）

カテゴリ	重み	基準数	最大ポイント
アイデンティティ	3x	4	12
プロンプトの品質	2x	4	8
検証	1x	4	4
設計	2x	4	8

主な基準：

• 明確な名前（3ポイント）：「agent1」のような汎用的な名前ではない
• トリガーを含む説明（3ポイント）：「when」／「use」を含む
• 役割の定義（2ポイント）：「You are...」という記述
• 3つ以上の例（1ポイント）：使用シナリオが記載されている
• 単一の責務（2ポイント）：用途が絞られており、「汎用」ではない

スキル（最大32ポイント）

カテゴリ	重み	基準数	最大ポイント
構造	3x	4	12
内容	2x	4	8
技術	1x	4	4
設計	2x	4	8

主な基準：

• 有効な SKILL.md（3ポイント）：適切な命名
• 有効な名前（3ポイント）：小文字、1～64文字、スペースなし
• 方法論の説明（2ポイント）：ワークフローのセクションがある
• ハードコードされたパスがない（1ポイント）：/Users/、/home/ がない
• 明確なトリガー（2ポイント）：「使用するタイミング」のセクションがある

コマンド（最大20ポイント）

カテゴリ	重み	基準数	最大ポイント
構造	3x	4	12
品質	2x	4	8

主な基準：

• 有効なフロントマター（3ポイント）：name と description
• 引数のヒント（3ポイント）：$ARGUMENTS を使用する場合
• ステップごとのワークフロー（3ポイント）：番号付きのセクション
• エラー処理（2ポイント）：失敗モードへの言及

---

検出パターン

フロントマターの解析

import yaml
import re

def parse_frontmatter(content):
    match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
    if match:
        return yaml.safe_load(match.group(1))
    return None

キーワードの検出

def has_keywords(text, keywords):
    text_lower = text.lower()
    return any(kw in text_lower for kw in keywords)

# Example
has_trigger = has_keywords(description, ['when', 'use', 'trigger'])
has_error_handling = has_keywords(content, ['error', 'failure', 'fallback'])

重複の検出（重複チェック）

def jaccard_similarity(text1, text2):
    words1 = set(text1.lower().split())
    words2 = set(text2.lower().split())
    intersection = words1 & words2
    union = words1 | words2
    return len(intersection) / len(union) if union else 0

# Flag if similarity > 0.5 (50% keyword overlap)
if jaccard_similarity(desc1, desc2) > 0.5:
    issues.append("High overlap with another file")

トークン数のカウント（概算）

def estimate_tokens(text):
    # Rough estimate: 1 token ≈ 0.75 words
    word_count = len(text.split())
    return int(word_count * 1.3)

# Check budget
tokens = estimate_tokens(file_content)
if tokens > 5000:
    issues.append("File too large (>5K tokens)")

---

業界の状況

出典：LangChain Agent Report 2026（公開レポート、14～22ページ）

主な調査結果：

• 29.5% の組織が体系的な評価なしでエージェントを導入している
• 18% が主な課題として「エージェントのバグ」を挙げている
• わずか12% が自動品質チェックを使用している（88% は手動または未実施）
• 43% がエージェントの品質を長期にわたり維持することに難しさを感じている
• 主な問題：ハルシネーション（31%）、不十分なエラー処理（28%）、不明確なトリガー（22%）

示唆：

1. 自動化の不足：ほとんどのチームが手動チェックリストに頼っている（大規模運用ではエラーが発生しやすい）
2. 品質負債：検証なしで導入されたエージェントは技術的負債が蓄積する
3. メンテナンスの負担：43% が長期的な品質維持に苦労している（追跡システムがない）

このスキルが対処する課題：

• 自動化：手動チェックリストを定量的なスコアリングに置き換える
• 追跡：JSON 出力によって経時的な傾向分析が可能になる
• 標準：80% のしきい値によって、本番環境への明確な移行基準を設ける

---

出力例

クイック監査（上位5つの基準）

# Quick Audit: Agents/Skills/Commands

**Files**: 15 (5 agents, 8 skills, 2 commands)
**Critical Issues**: 3 files fail top-5 criteria

## Top-5 Criteria (Pass/Fail)

| File | Valid Name | Has Triggers | Error Handling | No Hardcoded Paths | Examples |
|------|------------|--------------|----------------|--------------------|----------|
| agent1.md | ✅ | ✅ | ❌ | ✅ | ❌ |
| skill2/ | ✅ | ❌ | ✅ | ❌ | ✅ |

## Action Required

1. **Add error handling**: 5 files
2. **Remove hardcoded paths**: 3 files
3. **Add usage examples**: 4 files

完全な監査

全体の構成については、上記のフェーズ4「レポート生成」を参照してください。

比較（完全版＋ベンチマーク）

# Comparative Audit

## Project vs Templates

| File | Project Score | Template Score | Gap | Top Missing |
|------|---------------|----------------|-----|-------------|
| debugging-specialist.md | 78% (C) | 94% (A) | -16 pts | Anti-hallucination, edge cases |
| testing-expert/ | 85% (B) | 91% (A) | -6 pts | Integration docs |

## Recommendations

Focus on these gaps to reach template quality:
1. **Anti-hallucination measures** (8 files): Add source verification sections
2. **Edge case documentation** (5 files): Add failure scenario examples
3. **Integration documentation** (4 files): List compatible agents/skills

---

使用方法

基本（完全な監査）

# In Claude Code
Use skill: audit-agents-skills

# Specify path
Use skill: audit-agents-skills for ~/projects/my-app

オプションを指定

# Quick audit (fast)
Use skill: audit-agents-skills with mode=quick

# Comparative (benchmark analysis)
Use skill: audit-agents-skills with mode=comparative

# Generate fixes
Use skill: audit-agents-skills with fixes=true

# Custom output path
Use skill: audit-agents-skills with output=~/Desktop/audit.json

JSON 出力のみ

# For programmatic integration
Use skill: audit-agents-skills with format=json output=audit.json

---

CI/CD との統合

プリコミットフック

#!/bin/bash
# .git/hooks/pre-commit

# Run quick audit on changed agent/skill/command files
changed_files=$(git diff --cached --name-only | grep -E "^\.claude/(agents|skills|commands)/")

if [ -n "$changed_files" ]; then
    echo "Running quick audit on changed files..."
    # Run audit (requires Claude Code CLI wrapper)
    # Exit with 1 if any file scores <80%
fi

GitHub Actions

name: Audit Agents/Skills
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run quality audit
        run: |
          # Run audit skill
          # Parse JSON output
          # Fail if overall_score < 80

---

比較：コマンドとスキル

項目	コマンド（/audit-agents-skills）	スキル（このファイル）
対象範囲	現在のプロジェクトのみ	複数プロジェクト、比較
出力	Markdown レポート	Markdown ＋ JSON
速度	高速（5～10分）	低速（比較ありの場合は10～20分）
深さ	標準の16項目	同じ基準＋ベンチマーク分析
修正の提案	--fix フラグで実行	推奨事項とともに組み込み済み
プログラムからの利用	ターミナル出力	CI/CD 統合用の JSON
最適な用途	クイックチェック、開発ワークフロー	詳細な監査、品質の追跡

推奨：日常のチェックにはコマンドを、リリース基準の判定と品質の追跡にはスキルを使用してください。

---

メンテナンス

基準の更新

scoring/criteria.yaml を編集します：

agents:
  categories:
    identity:
      criteria:
        - id: A1.5  # New criterion
          name: "API versioning specified"
          points: 3
          detection: "mentions API version or compatibility"

バージョンの更新：基準を変更した場合は、フロントマターの version を増やします。

ファイルタイプの追加

新しいファイルタイプ（例: 「ワークフロー」）をサポートするには:

1. scoring/criteria.yaml に追加します:

   workflows:
     max_points: 24
     categories: [...]
   

2. 検出ロジック（ファイルパスのパターン）を更新します
3. レポートテンプレートを更新します

---

関連

• コマンド版: .claude/commands/audit-agents-skills.md
• エージェント検証チェックリスト: ガイド行 4921（手動 16 基準）
• スキル検証: ガイド行 5491（仕様ドキュメント）
• 参照テンプレート: examples/agents/、examples/skills/、examples/commands/

---

変更履歴

v1.0.0 (2026-02-07):

• 初回リリース
• 16 基準のフレームワーク（エージェント/スキル/コマンド）
• 3 つの監査モード（クイック/フル/比較）
• JSON + Markdown 出力
• 修正提案
• 業界コンテキスト（LangChain 2026 レポート）

---

すぐに使用できるスキル: audit-agents-skills