testing-handbook-generator

测试手册技能生成器

根据 Trail of Bits 测试手册生成并维护 Claude Code 技能。

适用场景

在以下情况下调用此技能：

• 根据手册内容创建新的安全测试技能
• 用户提到“测试手册”“appsec.guide”，或询问技能生成相关事宜
• 需要批量生成或刷新技能

请勿用于：

• 一般安全测试问题（请使用生成的技能）
• 与手册无关的技能创建

手册位置

此技能需要测试手册仓库。完整详情请参阅 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 技能	fuzzer-skill.md
/fuzzing/techniques/	技术技能	technique-skill.md
/crypto/[tool]/	领域技能	domain-skill.md
/web/[tool]/	工具技能	tool-skill.md

技能候选信号

信号	表明
_index.md 中含有 bookCollapseSection: true	主要工具/主题
编号文件（00-、10-、20-）	结构化内容
techniques/ 子章节	方法论内容
99-resources.md 或 91-resources.md	含有外部链接

排除信号

信号	操作
frontmatter 中含有 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

两阶段生成（阶段 3）

生成采用两轮处理，以解决前向引用问题（技能引用了尚不存在的其他技能）。

第一轮：内容生成（并行）

并行生成所有技能，不包含“相关技能”部分：

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)

第一轮 Agent：

• 生成除“相关技能”之外的所有章节
• 留下占位符：## Related Skills\n\n
• 输出报告包含 references: DEFERRED

第二轮：填充交叉引用（顺序执行）

第一轮的所有 Agent 完成后，运行第二轮以填充“相关技能”部分：

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

第二轮流程：

1. 收集所有已生成的技能名称：ls -d skills/*/SKILL.md
2. 根据 discovery 中的映射，为每项技能确定相关技能
3. 编辑各个 SKILL.md，将占位符替换为实际链接
4. 验证交叉引用是否存在（确保没有失效链接）

Agent 提示词模板

完整提示词模板请参阅 agent-prompt.md，其中包括：

• 变量替换参考（包括 pass 变量）
• 写入前验证清单
• Hugo shortcode 转换规则
• 行数拆分规则
• 错误处理指南
• 输出报告格式

收集结果

第一轮后：汇总输出报告，确认所有技能均已生成。
第二轮后：运行验证器检查交叉引用。

处理 Agent 故障

如果 Agent 发生故障或生成无效输出：

故障类型	检测方式	恢复操作
Agent 崩溃	没有输出报告	使用相同输入重新运行单个 Agent
验证失败	输出报告显示错误	检查缺漏项／警告，手动修补或重新运行
技能类型错误	内容与模板不符	使用修正后的 type 参数重新运行
内容缺失	输出报告列出缺漏项	如果问题较小则接受，或提供额外的 related_sections
Pass 2 引用失效	验证器显示技能缺失	检查技能是否被跳过，并更新引用

重要： 单个 Agent 发生故障时，切勿重新运行整个并行批次。应单独修复各项故障。

重新生成单个技能

若要重新生成单个技能，而不重新运行整个批次：

# 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. 仅针对该技能重新运行 Pass 2，以更新交叉引用
5. 对单个技能运行验证器：uv run scripts/validate-skills.py --skill {skill-name}

输出位置

生成的技能写入：

skills/[skill-name]/SKILL.md

每个技能都有自己的目录，用于存放可能需要的支持文件（与 testing-handbook-generator 并列）。

质量检查清单

交付生成的技能前：

• 已分析所有手册章节（阶段 1）
• 已在生成前向用户展示计划（阶段 2）
• 已启动并行 Agent，每个技能对应一个 Agent（阶段 3）
• 已针对每种技能类型正确应用模板
• 验证器通过：uv run scripts/validate-skills.py
• 激活测试通过——参见 testing.md
• 已在主 README.md 中更新生成的技能表格
• 已更新 README.md 技能交叉引用图
• 已记录自我改进说明
• 已向用户发送摘要通知

生成后任务

1. 更新主 README

生成技能后，更新仓库的主 README.md，将这些技能列出。

格式： 将生成的技能添加到同一个“可用插件”表格中，紧接在 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 中的 技能交叉引用 部分，加入展示技能关系的 mermaid 图。

流程：

1. 阅读每个生成技能的 SKILL.md，并提取其 ## Related Skills 部分
2. 按技能类型（模糊测试器、技术、工具、领域）对节点分组，构建 mermaid 图
3. 根据相关技能之间的关系添加边：
   • 使用实线箭头（-->）表示主要技术依赖
   • 使用虚线箭头（-.->）表示备选工具建议
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，了解质量保证方法。