完整指南如何向 ctf-skills 贡献一个 CTF 解题技巧SKILL.md 规范与 CI 测试全流程【免费下载链接】ctf-skillsAgent skills for solving CTF challenges - web exploitation, binary pwn, crypto, reverse engineering, forensics, OSINT, and more项目地址: https://gitcode.com/gh_mirrors/ct/ctf-skillsctf-skills是一个为 AI Agent 提供 CTF 解题技能的开源仓库覆盖 Web 渗透、二进制 PWN、密码学、逆向工程、数字取证和 OSINT 等赛道。本指南带你走完从选题、编写技巧、校验 SKILL.md Frontmatter 到通过全部 CI 测试的完整贡献流程让你的第一个 PR 一次合入。1 分钟看懂仓库结构 ️ctf-skills 的组织方式非常清晰仓库根目录下有 10 余个技能分类目录每个目录就是一个独立的技能包每个目录必须包含一个 SKILL.md 作为技能入口内含 YAML Frontmatter 元信息同目录下的若干.md文件是该分类的技巧文件如ctf-web/下的sql-injection.md、client-side.md等solve-challenge/ 是总调度技能负责把题目分发给对应分类分类定位示例ctf-webWeb 渗透SQLi、XSS、JWTctf-pwn二进制漏洞利用栈溢出、堆、ROPctf-crypto密码学RSA、格密码ctf-reverse逆向工程反调试、自定义 VMctf-forensics数字取证磁盘恢复、隐写ctf-osint开源情报地理定位、社交挖掘 最常见的贡献就是往现有分类里加一个技巧这也是下文的主线。一键搭建贡献环境开始写代码前先装好本地工具链要求 Python 3.12克隆仓库git clone https://gitcode.com/gh_mirrors/ct/ctf-skills安装 pre-commit 钩子pip install pre-commit pre-commit install安装测试依赖pip install pytestpre-commit 配置见 .pre-commit-config.yaml它会在你每次 commit 时自动执行 6 类检查行尾空白清理、YAML 校验、大文件拦截、Python 代码风格ruff、Shell 脚本静态分析shellcheck以及全部.md文件的 Markdown Lint。相当于把 CI 搬到了本地能帮你提前发现 90% 的格式问题。四步写一个新 CTF 解题技巧 ✍️第 1 步选对文件。浏览目标分类目录把技巧加进主题最接近的现有文件找不到合适的再新建一个.md文件。第 2 步按统一格式写技巧。项目对技巧格式有明确约定每个技巧以二级标题开头## 技巧名称 (CTF赛事/年份)附一段何时使用、为什么有效的简短说明给出可运行的代码示例放在带语言标签的代码块里主机名一律用占位符example.com、attacker.com严禁出现真实基础设施风格是快速参考卡不是长篇教程——保持简洁第 3 步更新父级 SKILL.md。如果新建了技巧文件必须在SKILL.md的Additional Resources列表中新增一条带相对链接的条目如果修改的是现有文件也要同步补充描述。第 4 步更新 README.md 的技能表格。新增了文件就 1 文件数并在 Description 列追加技巧名称。⚠️ 这三处技巧文件、SKILL.md、README缺一不可tests/里的交叉引用测试会检查它们是否一致。SKILL.md Frontmatter 规范一张表看懂 7 条硬规则如果你新建分类或修改任何SKILL.mdFrontmatter 必须严格满足以下规则。这些规则由 tests/test_skill_frontmatter.py 逐条强制校验字段要求name必须与目录名完全一致最常见的翻车点description超过 20 个字符且以第三人称动词开头Provides、Solves、Analyzes…license固定为MITcompatibility必填自由文本allowed-tools空格分隔只能从Bash Read Write Edit Glob Grep Task WebFetch WebSearch Skill里选metadata.user-invocable只能是字符串true或false注意带引号metadata.argument-hint当user-invocable为true时必填一个合格的示例长这样可参考 ctf-web/SKILL.md 的写法--- name: ctf-newcategory description: - Provides [category] techniques for CTF challenges. Use when [trigger conditions]. license: MIT compatibility: Requires filesystem-based agent with bash, Python 3. allowed-tools: Bash Read Write Edit Glob Grep Task WebFetch WebSearch metadata: user-invocable: false ---还有一个隐藏考点tests/test_skill_discoverability.py 会模拟真实题目的路由过程——它只读description字段判断 Agent 能否根据用户描述准确找到你的技能。所以 description 别写成Provides techniques这种空话要写清触发条件例如 ctf-web 就明确写了目标是 HTTP 应用、API、浏览器客户端时使用。本地跑测试3 条命令覆盖全部校验 ✅提交前在本地执行以下命令模拟完整 CI# 1. 跑全部测试Frontmatter、交叉引用、技能可发现性 python -m pytest tests/ -v # 2. 全量 pre-commit 检查 pre-commit run --all-files # 3. 对改动的技能跑安全审计 python3 scripts/skill_security_auditor.py ctf-web --strict --json测试套件包含三块核心逻辑Frontmatter 校验— tests/test_skill_frontmatter.py上文 7 条规则的逐条断言交叉引用校验— tests/test_cross_references.py检查技巧文件都被 SKILL.md 引用、/ctf-*跨技能链接有效、所有内部 Markdown 链接和锚点能解析技能可发现性— tests/test_skill_discoverability.py防止你的 description 和别的技能撞车导致路由混乱CI 测试全流程你的 PR 要过哪 5 道关 提交 PR 后5 个 CI 工作流全部绿灯才能合入定义在.github/workflows/目录CI 工作流作用Tests在 Python 3.14 环境运行pytest tests/见 .github/workflows/tests.ymlMarkdown Lint对全部.md文件跑 markdownlint-cli2Skill Security Audit自动检测被改动的技能目录运行安全审计扫描Link Checkerlychee 校验所有 URL 有效性Lint Scriptsruff shellcheck 检查scripts/目录其中安全审计最值得了解scripts/skill_security_auditor.py 会扫描危险命令模式如rm -rf /、curl 管道 shell、硬编码密钥AWS Key、私钥、PAT、以及高风险写法eval、禁用 SSL 校验等。Critical 级别发现会直接让构建失败。对于 CTF 攻击演示文档的正常误报脚本内置了白名单比如 AngularJS$eval逃逸 payload、/tmp/的 chmod你也可以在对应行加!-- audit-ok --注释显式压制告警。PR 提交清单与审核要点 提交前对照 PR 模板 自查勾选 5 项pytest全部通过目标技能的安全审计干净--strict模式Markdown Lint 无告警pre-commit 钩子成功运行内容中没有泄露的凭据、真实 IP 或非 example 域名审核者额外关注的 4 点代码可运行且只使用占位主机名分类正确——放对了技能目录和技巧文件三处文档同步——技巧文件、SKILL.md、README 一致来源可溯——已知来源时在技巧标题中标注 CTF 赛事和年份另外如果你只有技巧的 writeup 链接还不确定怎么整理仓库提供了 New Technique 问题模板先提 Issue 讨论分类和格式再动手写 PR能大幅提高合入效率。避坑 FAQ新手最常踩的 4 个坑 ️Q1测试报错name doesnt match directorySKILL.md的name字段和目录名必须逐字符一致比如目录是ctf-forensicsname 就不能写成ctf-forensics-2。Q2审计报了 Critical但我只是引用了一个危险命令做讲解这类文档型误报用行内!-- audit-ok --注释压制并在 PR 描述里说明理由。Q3加了技巧为什么 cross-references 测试挂了大概率是 SKILL.md 的 Additional Resources 漏登记了新文件或者 Markdown 相对链接路径写错。Q4description 写得很详细但 discoverability 测试失败说明你的描述和某个核心技能ctf-web/ctf-pwn/ctf-reverse/ctf-misc语义重叠了。加一句Do not use it for …式的排他说明参考 ctf-web 的写法通常能解决。负责任的贡献边界 ️最后但同样重要本仓库仅面向授权的 CTF 比赛、安全研究与教育场景。贡献内容必须遵守 SECURITY.md 的负责任使用政策——绝不提交真实凭据、个人隐私信息或指向在野恶意基础设施的链接。你的第一个技巧可能就是下一个参赛者翻到救命稻草的那一页。动手试试吧【免费下载链接】ctf-skillsAgent skills for solving CTF challenges - web exploitation, binary pwn, crypto, reverse engineering, forensics, OSINT, and more项目地址: https://gitcode.com/gh_mirrors/ct/ctf-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考