testing-handbook-generator

テストハンドブックスキルジェネレーター

Trail of Bits Testing Handbook から Claude Code スキルを生成し、保守します。

使用するタイミング

次の場合にこのスキルを呼び出してください：

• ハンドブックの内容から新しいセキュリティテストスキルを作成する
• ユーザーが「testing handbook」や「appsec.guide」に言及する、またはスキルの生成について尋ねる
• スキルを一括生成または更新する必要がある

次の用途には使用しないでください：

• 一般的なセキュリティテストに関する質問（生成済みのスキルを使用してください）
• ハンドブック以外のスキルの作成

ハンドブックの場所

このスキルには Testing Handbook リポジトリが必要です。詳しくは discovery.md を参照してください。

クイックリファレンス： ./testing-handbook、../testing-handbook、~/testing-handbook を確認 → ユーザーに尋ねる → 最終手段としてクローンする。

リポジトリ： https://github.com/trailofbits/testing-handbook

ワークフローの概要

Phase 0: Setup              Phase 1: Discovery
┌─────────────────┐        ┌─────────────────┐
│ Locate handbook │   →    │ Analyze handbook│
│ - Find or clone │        │ - Scan sections │
│ - Confirm path  │        │ - Classify types│
└─────────────────┘        └─────────────────┘
         ↓                          ↓
Phase 3: Generation        Phase 2: Planning
┌─────────────────┐        ┌─────────────────┐
│ TWO-PASS GEN    │   ←    │ Generate plan   │
│ Pass 1: Content │        │ - New skills    │
│ Pass 2: X-refs  │        │ - Updates       │
│ - Write to gen/ │        │ - Present user  │
└─────────────────┘        └─────────────────┘
         ↓
Phase 4: Testing           Phase 5: Finalize
┌─────────────────┐        ┌─────────────────┐
│ Validate skills │   →    │ Post-generation │
│ - Run validator │        │ - Update README │
│ - Test activation│       │ - Update X-refs │
│ - Fix issues    │        │ - Self-improve  │
└─────────────────┘        └─────────────────┘

スコープの制限

次の場所のみを変更してください：

• plugins/testing-handbook-skills/skills/[skill-name]/* - 生成されたスキル（testing-handbook-generator と同じ階層）
• plugins/testing-handbook-skills/skills/testing-handbook-generator/* - 自己改善
• リポジトリのルートにある README.md - 生成されたスキルを表に追加する

次のものは変更または分析しないでください：

• 他のプラグイン（plugins/property-based-testing/、plugins/static-analysis/ など）
• このプラグイン以外のスキル

testing-handbook-skills/ 以外のスキルをスキャンしたり、コンテキストに取り込んだりしないでください。ハンドブックの内容と、ハンドブックから参照されるリソースのみに基づいてスキルを生成してください。

クイックリファレンス

セクション → スキルタイプの対応表

ハンドブックのセクション	スキルタイプ	テンプレート
/static-analysis/[tool]/	ツールスキル	tool-skill.md
/fuzzing/[lang]/[fuzzer]/	ファザーのスキル	fuzzer-skill.md
/fuzzing/techniques/	手法スキル	technique-skill.md
/crypto/[tool]/	ドメインスキル	domain-skill.md
/web/[tool]/	ツールスキル	tool-skill.md

スキル候補の兆候

兆候	示す内容
bookCollapseSection: true を含む _index.md	主要なツール／トピック
番号付きファイル（00-、10-、20-）	構成されたコンテンツ
techniques/ サブセクション	手法に関するコンテンツ
99-resources.md または 91-resources.md	外部リンクを含む

除外の兆候

兆候	対応
フロントマターの draft: true	セクションをスキップ
空のディレクトリ	セクションをスキップ
テンプレート／プレースホルダーファイル	セクションをスキップ
GUI 専用ツール（例：web/burp/）	セクションをスキップ（Claude は GUI ツールを操作できません）

判断ツリー

スキル生成を開始しますか？

├─ Need to analyze handbook and build plan?
│  └─ Read: discovery.md
│     (Handbook analysis methodology, plan format)
│
├─ Spawning skill generation agents?
│  └─ Read: agent-prompt.md
│     (Full prompt template, variable reference, validation checklist)
│
├─ Generating a specific skill type?
│  └─ Read appropriate template:
│     ├─ Tool (Semgrep, CodeQL) → templates/tool-skill.md
│     ├─ Fuzzer (libFuzzer, AFL++) → templates/fuzzer-skill.md
│     ├─ Technique (harness, coverage) → templates/technique-skill.md
│     └─ Domain (crypto, web) → templates/domain-skill.md
│
├─ Validating generated skills?
│  └─ Run: scripts/validate-skills.py
│     Then read: testing.md for activation testing
│
├─ Finalizing after generation?
│  └─ See: Post-Generation Tasks below
│     (Update main README, update Skills Cross-Reference, self-improvement)
│
└─ Quick generation from specific section?
   └─ Use Quick Reference above, apply template directly

2 パス生成（フェーズ 3）

生成では、前方参照の問題（まだ存在しない他のスキルを参照するスキル）を解決するため、2 パス方式を使用します。

パス 1：コンテンツの生成（並列）

関連スキルのセクションを含めずに、すべてのスキルを並列に生成します。

Pass 1 - Generating 5 skills in parallel:
├─ Agent 1: libfuzzer (fuzzer) → skills/libfuzzer/SKILL.md
├─ Agent 2: aflpp (fuzzer) → skills/aflpp/SKILL.md
├─ Agent 3: semgrep (tool) → skills/semgrep/SKILL.md
├─ Agent 4: harness-writing (technique) → skills/harness-writing/SKILL.md
└─ Agent 5: wycheproof (domain) → skills/wycheproof/SKILL.md

Each agent uses: pass=1 (content only, Related Skills left empty)

パス 1 のエージェント：

• 関連スキルを除くすべてのセクションを生成する
• プレースホルダー ## Related Skills\n\n を残す
• 出力レポートに references: DEFERRED を含める

パス 2：相互参照の追加（逐次）

パス 1 のすべてのエージェントが完了したら、パス 2 を実行して関連スキルを追加します。

Pass 2 - Populating cross-references:
├─ Read all generated skill names from skills/*/SKILL.md
├─ For each skill, determine related skills based on:
│   ├─ related_sections from discovery (handbook structure)
│   ├─ Skill type relationships (fuzzers → techniques)
│   └─ Explicit mentions in content
└─ Update each SKILL.md's Related Skills section

パス 2 の手順：

1. 生成されたすべてのスキル名を収集します：ls -d skills/*/SKILL.md
2. 各スキルについて、discovery の対応表を使用して関連スキルを特定します
3. 各 SKILL.md を編集し、プレースホルダーを実際のリンクに置き換えます
4. 相互参照が存在することを検証します（リンク切れがないこと）

エージェントプロンプトのテンプレート

次の項目を含む完全なプロンプトテンプレートについては、agent-prompt.md を参照してください：

• 変数置換のリファレンス（pass 変数を含む）
• 書き込み前の検証チェックリスト
• Hugo ショートコードの変換ルール
• 行数に基づく分割ルール
• エラー処理のガイダンス
• 出力レポートの形式

結果の収集

パス 1 の後：出力レポートを集約し、すべてのスキルが生成されたことを確認します。
パス 2 の後：バリデーターを実行して相互参照を確認します。

エージェントの失敗への対処

エージェントが失敗したり、無効な出力を生成したりした場合：

失敗の種類	検出方法	復旧方法
エージェントがクラッシュした	出力レポートがない	同じ入力で単一のエージェントを再実行する
検証に失敗した	出力レポートにエラーが表示される	不足項目や警告を確認し、手動で修正するか再実行する
スキルの種類が間違っている	コンテンツがテンプレートと一致しない	type パラメーターを修正して再実行する
コンテンツが不足している	出力レポートに不足項目が記載されている	軽微であればそのまま受け入れるか、追加の related_sections を指定する
パス 2 で参照が壊れている	バリデーターにスキルの欠落が表示される	スキルがスキップされたか確認し、参照を更新する

重要： 単一のエージェントが失敗した場合、並列バッチ全体を再実行しないでください。個々の失敗を独立して修正してください。

単一スキルの再生成

バッチ全体を再実行せずに、単一のスキルを再生成するには：

# Regenerate single skill (Pass 1 - content only)
"Use testing-handbook-generator to regenerate the {skill-name} skill from section {section_path}"

# Example:
"Use testing-handbook-generator to regenerate the libfuzzer skill from section fuzzing/c-cpp/10-libfuzzer"

再生成ワークフロー：

1. ハンドブックのセクションを再読し、新しいコンテンツを確認する
2. 適切なテンプレートを適用する
3. skills/{skill-name}/SKILL.md に書き込む（既存のファイルを上書きします）
4. そのスキルのみを対象にパス 2 を再実行し、相互参照を更新する
5. 単一スキルに対してバリデーターを実行する：uv run scripts/validate-skills.py --skill {skill-name}

出力先

生成されたスキルは次の場所に書き込まれます：

skills/[skill-name]/SKILL.md

各スキルには、サポート用ファイルを配置できる専用のディレクトリが作成されます（testing-handbook-generator と同じ階層に配置されます）。

品質チェックリスト

生成したスキルを引き渡す前に、以下を確認してください：

• ハンドブックの全セクションを分析済み（フェーズ 1）
• 生成前に計画をユーザーに提示済み（フェーズ 2）
• 並列エージェントを起動済み（スキルごとに 1 つ）（フェーズ 3）
• スキルの種類ごとにテンプレートを正しく適用済み
• バリデーターに合格：uv run scripts/validate-skills.py
• アクティベーションテストに合格。testing.md を参照
• メインの README.md を生成したスキルの表で更新済み
• README.md のスキル相互参照グラフを更新済み
• 自己改善に関するメモを記録済み
• 概要をユーザーに通知済み

生成後のタスク

1. メインの README を更新する

スキルを生成したら、リポジトリのメインの README.md を更新して、生成したスキルを一覧に追加します。

形式： 生成したスキルを同じ「Available Plugins」テーブルに追加し、testing-handbook-skills の直後に配置します。作成者にはプレーンテキストの testing-handbook-generator を使用します（リンクは付けません）。

例：

| Plugin | Description | Author |
|--------|-------------|--------|
| ... other plugins ... |
| [testing-handbook-skills](plugins/testing-handbook-skills/) | Meta-skill that generates skills from the Testing Handbook | Paweł Płatek |
| [libfuzzer](plugins/testing-handbook-skills/skills/libfuzzer/) | Coverage-guided fuzzing with libFuzzer for C/C++ | testing-handbook-generator |
| [aflpp](plugins/testing-handbook-skills/skills/aflpp/) | Multi-core fuzzing with AFL++ | testing-handbook-generator |
| [semgrep](plugins/testing-handbook-skills/skills/semgrep/) | Fast static analysis for finding bugs | testing-handbook-generator |

2. スキル相互参照を更新する

スキルを生成したら、README.md の Skills Cross-Reference セクションを更新し、スキル間の関係を示す mermaid グラフを追加します。

手順：

1. 生成した各スキルの SKILL.md を読み、その ## Related Skills セクションを抽出する
2. スキルの種類ごとにノードをグループ化して、mermaid グラフを作成する（ファザー、テクニック、ツール、ドメイン）
3. Related Skills の関係に基づいてエッジを追加する：
   • 主要なテクニックの依存関係には実線の矢印（-->）を使用する
   • 代替ツールの提案には破線の矢印（-.->）を使用する
4. README.md 内の既存の mermaid コードブロックを置き換える

エッジの分類：

関係	矢印のスタイル	例
ファザー → テクニック	-->	libfuzzer --> harness-writing
ツール → ツール（代替）	-.->	semgrep -.-> codeql
ファザー → ファザー（代替）	-.->	libfuzzer -.-> aflpp
テクニック → テクニック	-->	harness-writing --> coverage-analysis

検証： 更新後、validate-skills.py を実行して、参照されているすべてのスキルが存在することを確認します。

3. 自己改善

各生成の実行後に、今後の実行を改善できる点を振り返ります。

改善点の記録先：

• テンプレート（不足しているセクション、より適切な構成）
• 検出ロジック（見落としたパターン、誤検出）
• コンテンツ抽出（未対応のショートコード、書式の問題）

更新手順：

1. 生成中に発生した問題を記録します
2. 問題の原因となったパターンを特定します
3. 関連するファイルを更新します：
   • SKILL.md - ワークフロー、判断ツリー、クイックリファレンスの更新
   • templates/*.md - テンプレートの改善
   • discovery.md - 検出ロジックの更新
   • testing.md - 新しい検証チェック
4. コミットメッセージに改善内容を記載します

自己改善の例：

Issue: libFuzzer skill missing sanitizer flags table
Fix: Updated templates/fuzzer-skill.md to include ## Compiler Flags section

使用例

検出と生成の全工程

User: "Generate skills from the testing handbook"

1. Locate handbook (check common locations, ask user, or clone)
2. Read discovery.md for methodology
3. Scan handbook at {handbook_path}/content/docs/
4. Build candidate list with types
5. Present plan to user
6. On approval, generate each skill using appropriate template
7. Validate generated skills
8. Update main README.md with generated skills table
9. Update README.md Skills Cross-Reference graph from Related Skills sections
10. Self-improve: note any template/discovery issues for future runs
11. Report results

単一セクションの生成

User: "Create a skill for the libFuzzer section"

1. Read /testing-handbook/content/docs/fuzzing/c-cpp/10-libfuzzer/
2. Identify type: Fuzzer Skill
3. Read templates/fuzzer-skill.md
4. Extract content, apply template
5. Write to skills/libfuzzer/SKILL.md
6. Validate and report

ヒント

実施すること：

• 生成前に必ず計画を提示します
• スキルの種類に適したテンプレートを使用します
• コードブロックを正確に保持します
• 生成後に検証します

実施しないこと：

• ユーザーの承認なしに生成しません
• 動画以外の外部リソースの取得を省略しません（WebFetchを使用します）
• 動画のURLは取得しません（YouTube、Vimeoはタイトルのみ）
• ハンドブックの画像を直接含めません
• 検証の手順を省略しません
• SKILL.md が500行を超えないようにします

---

初めて使用する場合： ハンドブックの分析プロセスを理解するため、discovery.md から始めてください。

テンプレートを参照する場合： スキルの種類別テンプレートについては、templates/ ディレクトリを参照してください。

検証について： 品質保証の方法については、testing.md を参照してください。