如何向hack-skills贡献技能SKILL.md编写规范与categories.yaml单一真相源实践【免费下载链接】hack-skillsHelping AI Agent become an awesome practical hacker!项目地址: https://gitcode.com/gh_mirrors/ha/hack-skillshack-skills 是一个面向 AI Agent 的开源安全技能知识库把真实渗透测试、Bug 赏金、CTF 中可复用的攻防知识蒸馏成 101 个可安装、可检索、可组合的安全技能覆盖 Web/API 安全、认证授权、Linux/Windows/macOS 提权、Active Directory、二进制利用、密码学攻击等 14 大安全域。想给它添加一个新技能本文带你走通完整贡献流程SKILL.md 怎么写、categories.yaml 怎么登记、CI 构建脚本会校验什么——新手照着做就能提交一个标准 PR。一、贡献前先上手获取仓库与三层加载架构先用 git 克隆仓库到本地git clone https://gitcode.com/gh_mirrors/ha/hack-skillshack-skills 的核心设计是三层技能加载架构贡献前必须先理解每一层的职责才能判断你的技能该放在哪一层层级职责推荐暴露策略代表技能️ Master 主入口全局路由、操作准则、跨分类切换最先加载skills/hack/SKILL.md️ Category 分类入口按攻击面路由到稳定的主题族最先加载skills/api-sec/SKILL.md Deep 细分主题完整的攻击手册与执行细节按需加载skills/ssrf-server-side-request-forgery/SKILL.md设计原则很明确不要把每个小技巧都暴露成入口而是把加载器真正需要的内容压缩到主入口和分类入口中细分技能按需深入。二、SKILL.md 编写规范目录命名 frontmatter 正文结构1. 目录命名一眼看懂安全语义每个技能独占一个目录统一使用skills/{语义标识符}/SKILL.md结构skills/ ssrf-server-side-request-forgery/ SKILL.md # 技能主体 SCENARIOS.md # 可选进阶场景 URL_PARSER_TRICKS.md # 可选参考资料目录名必须满足两点语义直白如path-traversal-lfi、heap-exploitation让人一眼看出攻击面ASCII 短横线目录名会成为 URL 锚点和过滤参数不能用下划线或中文。2. frontmatter检索与路由的命门每个 SKILL.md 必须以---包裹的 YAML frontmatter 开头包含两个必填字段。以 skills/api-sec/SKILL.md 为例--- name: api-sec description: - Entry P1 category router for API security. Use when choosing between API recon, authorization, token abuse, and hidden-parameter workflows before any deeper API topic skill. ---编写建议name与目录名保持一致构建脚本解析失败时会回退用目录名但规范做法是显式声明description是这个技能能被 Agent 正确加载的关键——请写清楚什么时候该用它Use when...包含技术关键词参考 skills/hack/SKILL.md 中同时覆盖英文术语与中文场景词的写法。3. 正文结构按需加载 分诊表 内容红线✅推荐结构参考 SSRF 技能开头一段AI LOAD INSTRUCTION说明本技能覆盖什么、边界在哪大内容拆到同目录的伴生文档如SCENARIOS.md、URL_PARSER_TRICKS.mdSKILL.md 中用相对链接按需加载避免单文件过长撑爆上下文加一张Quick Triage 分诊表观察 → 路由到哪个子主题帮助 Agent 做决策而不是死记硬背。⚠️内容红线来自项目 README.md 的 Harmless PoC Policy只保留非破坏性验证方式用SLEEP(5)时间延迟证明注入而不是DROP TABLERCE 类访问原语写 webshell、反弹 shell属于授权测试必需保留不写任何客户信息、厂商可识别的案例细节贡献内容应可验证、可审计帮助 Agent 在真实任务中更稳健地推理。三、categories.yaml 单一真相源新增技能必登记的注册表 这是最容易踩坑的一步在skills/下新建目录后必须在 site/data/categories.yaml 中登记到合适分类否则构建脚本会直接报错。这个文件是整个分类体系的单一真相源Single Source of Truth文件头部注释即维护规则categories: - id: api # URL 锚点/过滤参数必须 ASCII 短横线 name: API Security order: 2 # 决定主页展示顺序 description: REST / GraphQL / 移动后端 skills: - api-sec - api-recon-and-docs - api-authorization-and-bola - api-auth-and-jwt-abuse - graphql-and-hidden-parameters登记时的硬性约束规则说明唯一归属一个技能只能登记在一个分类跨分类重复声明会被构建脚本断言拦截非空校验每个分类必须有非空的skills列表顺序对齐分类内技能顺序需与 README.md 中的索引表一致便于 grep 对照顺序编号order控制 18 个分类在主页侧栏的展示顺序recon1 … forensics18tier 三档推断规则hack→ master名字以-sec结尾或在tier_overrides白名单中如recon-for-sec、injection-checking→ category其余一律 → deep。如果你的技能不符合命名惯例就在 categories.yaml 末尾的tier_overrides段落显式覆盖而不必强行改名。四、本地自校验build-skills-index.yak 会检查什么提交 PR 前建议用仓库自带的 scripts/build-skills-index.yak 本地跑一遍。它是 Pages 站点的索引构建脚本也是你贡献内容的守门员依次执行解析 frontmatter扫描skills/*/SKILL.md提取name/description统计全部.md行数双向一致性校验这是核心磁盘上有、categories.yaml没登记 → 报错missing in categories.yamlcategories.yaml声明了、磁盘上没目录 → 报错missing on diskCI 默认 strict 模式任一不一致直接构建失败输出索引生成 site/data/skills.json 供前端消费并做回环验证重新加载 JSON 核对totalSkills总数构建摘要打印 tier 分布master/category/deep与各分类技能数方便肉眼确认结果。支持的常用参数--project-root项目根目录、--skills-dir技能源目录默认skills、--categories分类文件默认site/data/categories.yaml、--output默认输出site/data/skills.json、--strict分类不一致时是否失败。五、PR 提交前检查清单 ✅skills/{语义目录名}/SKILL.md已创建目录名 ASCII 短横线、语义直白frontmatter 含name与descriptiondescription 写清何时使用大体积场景已拆到伴生.md文档并做按需加载链接已在 site/data/categories.yaml 对应分类登记且未重复归属README.md 中对应分类的索引表同步更新顺序与 yaml 一致内容符合无害 PoC 政策无破坏性操作、无客户信息、结论可验证本地跑过 scripts/build-skills-index.yak校验零报错。六、常见问题Q1我的技能横跨两个攻击面能登记到两个分类吗不能。构建脚本会对跨分类重复声明做断言。请选择最贴切的一个分类在 SKILL.md 的 Related 段落链接到其他分类的技能即可。Q2为什么分类要同时维护 yaml 和 README 两处因为面向的人和机器不同categories.yaml供构建脚本机器校验README 索引表供人类 grep 对照。文件注释明确要求两者顺序保持一致正是为了人审 机审双保险。Q3tier 选错了会有什么后果只是路由体验问题——deep 技能被过早暴露会稀释主入口的注意力master 被错误暴露则破坏全局路由。不符合规则时在tier_overrides中显式声明即可构建脚本会优先采用覆盖值。 记住一句话目录即身份yaml 即契约。把技能写进skills/、登记进categories.yaml、对齐 README 索引——三处一致你的贡献就通过了 hack-skills 的全部关卡。【免费下载链接】hack-skillsHelping AI Agent become an awesome practical hacker!项目地址: https://gitcode.com/gh_mirrors/ha/hack-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考