claude-red 攻防技能库贡献指南：SKILL.md 格式规范、编写流程与审查标准-育师

AI 技能
网络安全
渗透测试
红蓝对抗
应用安全

【免费下载链接】Claude-Red

claude-red is a curated library of offensive security skills designed for the Claude skills system. Each skill is a structured SKILL.md file that primes Claude with expert-level methodology for a specific attack surface — from SQLi to shellcode, EDR evasion to exploit development.

项目地址：https://gitcode.com/GitHub_Trending/cl/Claude-Red

点击查看免费下载

claude-red是一个面向 Claude Skills 系统的攻击性安全技能库，每个技能都是一份结构化的SKILL.md文件，为 Claude 注入特定攻击面（从 SQLi 到 shellcode、EDR 绕过到漏洞利用开发）的专家级方法论。本指南以仓库根目录的 CONTRIBUTING.md 为核心骨架，系统讲解该库的技能格式标准、frontmatter 规范、正文模板、风格要求以及从新增、修改、拆分到评审的完整协作流程。读完本文，你将掌握如何在claude-red中编写一份可被 Claude Skills 系统正确加载、可被检索匹配、符合维护者质量门槛的SKILL.md技能文件。

一、为什么需要一份贡献规范

claude-red的核心理念是"一个技能对应一个攻击面"。当前仓库已收录 78 个技能、横跨 23 个类别（见 README.md），覆盖 Web、无线、活动目录、容器、CI/CD、密码学、供应链等攻击领域。当一个库以这种规模持续增长时，若无统一格式约束，技能的加载机制、触发匹配和审查效率都会迅速劣化。

CONTRIBUTING.md开篇即点明了这份规范的职责：解释技能格式、评审流程以及保持库在增长过程中一致性的约定。它面向的是想要向该库贡献技能的开发者——不强制要求你熟悉每个攻击面的细节，但要求你遵循一套可复用的结构标准，让每一份SKILL.md既能被 Claude 正确解析，也能被人类操作员顺畅阅读和执行。

二、Quick Rules：贡献前必须遵守的五条铁律

贡献者提交任何内容前，先对照这份快速规则清单（原文档 "Quick Rules" 一节）：

一个技能，一个攻击面（One skill, one surface）。优先编写聚焦型技能（如offensive-kerberoasting），而不是把整个领域塞进一个"巨型综述"（如offensive-active-directory）。这一原则直接塑造了仓库的目录结构——Skills/下每个分类目录里都是单一主题的技能文件夹。
必须携带 YAML frontmatter。没有 frontmatter 的技能无法被 Claude Skills 系统加载。
引用来源（Cite sources）。每项技术都应当可溯源，链接到对应的 CVE、安全公告或原始研究。
禁止未授权目标。不得包含硬编码的受害方域名、真实客户数据或凭据。
代码块必须带语言标签。这是 Claude（以及人类）正确解析代码的最佳方式。

第 2、5 条在技术上直接决定了技能的可加载性与可执行性，第 3、4 条则划定了内容的法律与伦理边界，与仓库 SECURITY.md 中声明的"仅供授权红队、渗透测试、漏洞赏金、CTF 与培训场景使用"保持一致。

三、Skill Format：目录结构与 frontmatter 标准

3.1 目录约定

每个技能存放于固定路径模式：

Skills/<category>/<skill-folder>/SKILL.md

其中文件夹名称必须与 frontmatter 中的name:字段完全一致。这一点在仓库中可以得到直接印证：Skills/web/offensive-sqli/SKILL.md的name:是offensive-sqli，Skills/wireless/offensive-wpa2-psk/SKILL.md的name:是offensive-wpa2-psk，目录名与技能名一一对应。

分类目录名采用单数语义的简短命名（web/、auth/、wireless/、exploit-dev/、post-exploitation/等），技能文件夹统一使用offensive-前缀加攻击面/缺陷类别命名的 kebab-case。

3.2 Frontmatter（必填）

--- name: offensive-<bug-class-or-domain> description: "One paragraph (50–500 words). State the surface, the techniques covered, and when to use this skill. Claude uses this for trigger matching — be specific about scenarios, tools, and sub-topics." ---

两个字段的语义与分工：

name：技能的公开标识符。命名约定为offensive-前缀 + 缺陷类别或领域，例如offensive-sqli、offensive-ssrf、offensive-jwt、offensive-wpa3-sae。这个字段是"公共身份"，后续章节会强调它不可随意改名。
description：50–500 字的一段描述，必须讲清三件事——该技能覆盖的攻击面、包含的技术、何时使用。文档明确强调：description就是 Claude 做触发匹配（trigger matching）的依据，所以要写满操作员会提到的相关术语（场景、工具、子主题），并避免营销式语言。

仓库中的实际 frontmatter 是这条标准的最佳范例。例如 Skills/web/offensive-sqli/SKILL.md 的描述覆盖了错误型、UNION、布尔/时间盲注、带外、二阶、NoSQL、GraphQL、WebSocket、JSON 操作符等全部注入形态，并列出了 WAF 绕过、MySQL/MSSQL/PostgreSQL/Oracle 各数据库特性、云原生攻击路径、ORM CVE 追踪与 SQLmap 自动化——几乎每个关键词都是操作员在对话中会使用的检索词。再如 Skills/utility/offensive-reporting/SKILL.md，其描述枚举了报告结构、CVSS v3.1/v4.0 评分、证据卫生、交付格式等术语，并在结尾明确"何时使用"（Use at the end of an engagement when authoring a deliverable...），与 frontmatter 标准要求的"场景 + 工具 + 子主题"高度吻合。

3.3 Frontmatter 与清单生成的底层关系

description不仅是 Claude 的触发依据，也是仓库机器可读清单的数据源。仓库根目录的 tools/build_manifest.py 会递归扫描Skills/树，用正则^---\n(.*?)\n---提取每个SKILL.md的 frontmatter，并生成 claude-skills.json 清单，其中每条技能记录包含name、category、path、description四个字段（build_manifest.py），并按分类聚合（build_manifest.py）。

这意味着：frontmatter 写得越规范、description越充实，清单（claude-skills.json）的质量就越高，Claude 的触发匹配、第三方工具对库的索引都会直接受益。写反了——例如name:与文件夹名不一致——清单中就会以文件夹名兜底（fm.get("name", skill_dir.name)），造成标识符漂移。

四、Body Structure：正文推荐模板

frontmatter 之下的正文采用推荐的五段式结构：

# <Short Skill Title> <One-paragraph framing. Why this matters, what makes it distinct.> ## Quick Workflow 1. <Numbered, ordered steps an operator follows in the field> --- ## <Section per phase or technique cluster> <Concrete, copy-paste commands or code blocks. Annotate the why.> --- ## Detection / Defender View <Optional but valuable — what defenders will see, common evasions.> --- ## Engagement Cheatsheet <A short copy-paste-ready sequence summarizing the methodology.> --- ## Key References - MITRE ATT&CK / CWE / OWASP IDs - Canonical research papers, conference talks - Tool docs, advisory URLs - Source: link to upstream checklist if applicable

各部分的写作要点：

标题与引段：#一级标题用简短的技能名；引段用一段话说明"为什么重要、它与别的技能有何不同"。
Quick Workflow：编号列出现场操作员实际会执行的步骤，是整个技能的方法论浓缩。以 Skills/web/offensive-sqli/SKILL.md 为例，它的 Quick Workflow 是 5 步流水线：映射所有到达数据库的输入向量 → 插入探测载荷（无可见报错则转盲注）→ 识别数据库类型并枚举 schema → 在授权范围内提取数据/提权/RCE → 记录发现并给出修复建议。再如 Skills/active-directory/offensive-active-directory/SKILL.md 的 Quick Workflow，从离线收集（BloodHound/ADExplorer）到凭据收割、攻击路径映射、以最低检测成本执行、建立持久化并记录时间戳，五步即是一条完整的 AD 攻击主线。
按阶段或技术簇分节：每个攻击阶段一个##小节，给出可直接复制粘贴的命令或代码块，并标注"为什么这么做"（Annotate the why）。
Detection / Defender View：可选但很有价值——说明防御方会看到什么、常见的规避手段。这一节是红队技能区别于普通笔记的关键，也呼应了仓库中offensive-*技能普遍内置的防御视角。
Engagement Cheatsheet：一段可整体复制的短序列，汇总整个方法论。
Key References：列出 MITRE ATT&CK / CWE / OWASP 编号、权威研究论文与会谈、工具文档与公告 URL、上游清单来源。

正文模板是"推荐"而非"强制"，但它被设计成既服务于 Claude 的结构化理解，也服务于人类操作员在现场按序执行——每个---分隔符也在视觉上把长文档切成可独立阅读的区块。

五、Style Guide：行文规范

维度	规范
语态	技术化、第二人称（"you"）、现在时
篇幅	通常 200–800 行；在单一攻击面追求深度，而非横跨多领域的广度
代码块	始终标注语言（`bash`、`python`、`c`、`powershell`、`sql`、`yaml`、`http`）
表格	用于紧凑参考（CVE → 利用方式、能力 → 逃逸手段等）
emoji	除非作为表格中的视觉标记（✓ ✗ ⚠）且克制使用，否则一律不用

这条规范在仓库技能中体现得非常一致：offensive-sqli的探测载荷与时间盲注示例全部带sql/javascript/json/bash语言标注；offensive-reporting用表格与编号清单组织报告结构；offensive-active-directory的 SharpHound、PowerView、bloodhound-python 命令均以powershell/bash标注，可直接复制执行。

六、Adding a New Skill：新增技能的七步流程

原文档给出了新增技能的标准操作流程，结合仓库工具可以完整落地：

选择正确的分类目录。参考 README.md 的 Categories 表与 Skill Index，确认技能归属；如果现有分类都不合适，在 PR 描述中提议新分类（仓库历史上就经历过多次分类重组，见 CHANGELOG.md 中 v0.2.0 将技能重组进 13 个分类子目录、v0.3.0 新增 10 个分类的事件）。
创建Skills/<category>/<skill-name>/SKILL.md。
按上文格式写 frontmatter 与正文（第三节与第四节的标准）。
更新 README.md——把新技能加入对应分类的技能表。
更新 CHANGELOG.md——登记到下一个版本条目下。
更新 claude-skills.json——如果该文件存在，运行清单生成器：
```
python tools/build_manifest.py
```
该脚本会自动重扫Skills/树、解析所有 frontmatter，并重写根目录的claude-skills.json，输出形如Wrote claude-skills.json with 78 skills across 23 categories.的统计信息。清单本身就是这个贡献流程的机器可读产物：新增技能后若不重新生成，清单会与仓库脱节。
运行本地 lint 检查（原文档给出的命令）：
```
./tools/check-skill.sh Skills/<category>/<skill-name>/SKILL.md
```
需要说明：在当前仓库快照中，tools/ 目录实际提供的自动化工具是 build_manifest.py（清单生成器），check-skill.sh的 lint 命令是 CONTRIBUTING.md 中登记的标准流程，提交前可对照本文第三、四、五节的格式清单人工自查。

另外，仓库的 install.sh 为贡献者验证安装效果提供了便利：./install.sh --list可列出各分类及技能数量，./install.sh --category web可只安装指定分类到~/.claude/skills/claude-red，安装后技能会在下次 Claude 会话启动时被自动发现（install.sh），你可以据此实测新技能能否被正确加载。

七、Modifying 与 Splitting：修改与拆分既有技能

7.1 修改既有技能

保留name:字段——它是公开标识符，改名属于破坏性变更（breaking change）。这也是 CHANGELOG 约定"Semantic Versioning 中破坏性变更即技能改名/移除/分类重构"的原因。
在 CHANGELOG.md 中简要记录改动。
实质性重写时，链接旧版本的 SHA，方便审查者 diff 对比。

7.2 拆分巨型技能

当一个技能膨胀到超出单一攻击面时（原文档给出的例子：offensive-wifi同时覆盖 WPA2、WPA3、BLE、Zigbee），应执行拆分：

保留原技能作为简短的概览入口，指向新拆出的聚焦技能；
将详细内容移入新的单攻击面技能；
同步更新 README、CHANGELOG 与清单。

这条拆分策略在当前仓库已有完整的落地案例：offensive-wifi被保留为 802.11 概述入口（README 中标注 "802.11 overview — entrypoint for wireless assessments"），而offensive-wifi-recon、offensive-wpa2-psk、offensive-wpa3-sae、offensive-wpa-enterprise、offensive-wps、offensive-evil-twin、offensive-krack-fragattacks、offensive-bluetooth-ble、offensive-zigbee-thread-matter、offensive-z-wave、offensive-lorawan-sub-ghz等 14 个聚焦技能（见 README.md 的 Wireless 章节）构成了一个"概览 + 单点深入"的完整体系——这正是"一个技能一个攻击面"原则的规模化体现。

八、Review Process：评审流程与拒绝标准

8.1 评审五要素

Pull Request 会围绕五个维度接受审查：

技术准确性（Technical accuracy）：该方法是否有效？是否仍与当前威胁环境相关？
清晰度（Clarity）：一个称职的操作员能否理解并执行？
范围（Scope）：是否只覆盖一个攻击面，而非三个？
归因（Attribution）：是否引用了来源？
安全（Safety）：无真实目标、无真实机密、无恶意辅助工具。

流程上通常经历一轮评审，维护者可能在合并前要求修改（"Expect one round of review. Maintainers may request edits before merging."）。

8.2 明确不接受的贡献

硬编码真实受害方基础设施的技能；
默认行为具有破坏性且无警告的工具；
在缺乏合法红队背景的情况下绕过厂商强制安全遥测（security telemetry）的手段；
非 MIT 兼容许可证下的内容；
未经操作员复核的 AI 生成技能——规范允许用 Claude 起草，但必须由人验证、编辑后再提交。这一点与技能库自身的定位形成呼应：技能是给 AI 用的方法论，但质量标准始终由人类操作员把关。

九、问题与敏感发现的处理

进行大型 PR 之前，先在 GitHub Discussion 中开启讨论，让维护者确认方向。
遇到敏感发现（如示例中泄露的凭据等），不要公开提交，而是参照 SECURITY.md 的流程：该文件明确了仓库自身的漏洞上报渠道（security@snailsploit.com）、上报内容要素（受影响文件与 commit hash、影响描述、复现步骤、建议修复）以及 72 小时确认、14 天解决的承诺；同时它也划定了使用边界——这些技能仅用于有书面授权的渗透测试、赏金项目、CTF 与独立漏洞研究，禁止未授权访问。

结语：一份规范如何维持技能库的生命力

claude-red的贡献规范把"给 Claude 用的技能文件"变成了一种可复制的工程制品：YAML frontmatter 保证机器可加载、可触发匹配、可生成清单；五段式正文保证人类操作员按序执行且每个动作有据可依；分类与命名约定保证库在 78+ 技能规模下依然可导航、可检索；评审与拒绝标准则从技术、范围、归因、安全四个维度守住质量底线。对于希望为这个技能库贡献技能的开发者，本文梳理的目录结构、frontmatter 写法、正文模板、七步贡献流程与评审标准，就是一份可直接照做的完整操作手册——更深入的内容，建议直接翻阅 CONTRIBUTING.md、对照 Skills/ 下的真实技能样本，并用 tools/build_manifest.py 验证你的 frontmatter 是否合规。