VulnClaw Skill加载机制深度解析：索引暴露 + load_skill

VulnClaw Skill加载机制深度解析：索引暴露 + load_skill_reference按需读取完整指南

【免费下载链接】VulnClaw基于 AI Agent + MCP 工具链 + 渗透 Skill 编排，配合大语言模型，自然语言输入 → 自动完成「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。项目地址: https://gitcode.com/GitHub_Trending/vu/VulnClaw

🕷️VulnClaw是一款基于 AI Agent + MCP 工具链 + 渗透 Skill 编排的 AI 渗透测试工具：你只需自然语言输入，它就能自动完成「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。它内置了 40+ 个渗透 Skill（Web 注入、内网渗透、CTF、密码学、客户端逆向……），总计数百 KB 的专业知识库。问题来了：这些知识全塞进大模型上下文，Token 费用会爆炸、模型还会"读不完"。VulnClaw 的答案是一套「索引暴露 + 按需读取」的 Skill 加载机制——本文带你完整搞懂它。

一、先搞懂痛点：为什么 AI 不能"把书全读了"

大模型上下文是有限且昂贵的。如果每次任务都把全部 Skill 正文灌进提示词：

方案	问题
全量注入	Token 成本指数级上升，无关知识干扰判断
全不加载	模型缺少专业方法论，输出泛泛而谈
索引暴露 + 按需读取✅	平时只给"目录"，需要时再读"正文"

核心思路一句话：把 Skill 当成一本参考书，平时只给模型看目录页，模型自己决定翻哪一页。

二、Skill 三层目录：core / specialized / custom

VulnClaw 的 Skill 存放在三个层级，加载优先级依次回退（见 vulnclaw/skills/loader.py）：

核心层 core：7 个通用方法论，如 recon.md、pentest-flow.md
专项层 specialized：40+ 个目录型 Skill，如 client-reverse、intranet-pentest-advanced，每个都带references/参考文档目录
自定义层 custom：用户自己放到配置目录的 Skill，优先级最高

每个 Skill 支持两种格式：目录格式（SKILL.md+references/，可挂多份参考文档）和扁平格式（单个.md文件）。SKILL.md开头有一段 YAML frontmatter，声明名称、描述和路由元数据，例如客户端逆向 Skill 的头部：

--- name: client-reverse description: 客户端逆向与Burp重放 — 复杂客户端签名恢复、加密还原、请求链追踪 routing: target_types: [client, android, mobile] task_types: [reverse] tooling: [frida, jadx, burp, scrcpy] ---

💡 关键点：列出 Skill（list_core_skills()等函数）只扫描目录名和 frontmatter，绝不读取正文——这就是"索引"。

三、确定性路由：SkillResolver 如何选出"最合适的一本"

拿到你的输入后，vulnclaw/skills/resolver.py 中的SkillResolver会在完全不经过大模型的情况下做确定性打分，产出一个"1 个主 Skill + 最多 2 个辅助 Skill"的精选包：

显式调用永远优先：输入/ctf-web或 "Use VulnClaw skill ctf-web" 直接命中，置信度 1.0
类型化信号打分：目标类型、渗透阶段、漏洞类别等（词表定义在 vulnclaw/skills/routing.py），"SQL 注入"会被规范化成sqli再匹配
关键词别名兜底：vulnclaw/skills/dispatcher.py 里维护了中英双语关键词表，如"渗透测试"→pentest-flow、"内网渗透|横向移动|提权"→intranet-pentest-advanced
宽泛知识库永不压过精准 Skill：同分时broad标记的通用型知识库自动让位
无匹配不硬塞：非安全类输入不注入任何 Skill；疑似渗透任务才回退到pentest-flow（置信度仅 0.2）

每一步决策都是纯函数，可测试、可审计（对应测试见 tests/skills/test_skill_resolver.py）。

四、索引暴露：给模型看"目录"，不看"正文"

这是整个机制最精妙的一环，实现在 vulnclaw/agent/skill_context.py。每轮对话，apply_skill_selection()只做三件事：

解析出本轮的 Skill 精选包
把选择依据（选了什么、为什么、置信度）记入provenance 溯源链
向模型渲染一段紧凑的参考索引——只有 Skill 名称、一句话描述、路由理由和可用参考文档的文件名清单

模型收到的提示词长这样（示意）：

These skills are optional reference material only...
primary reference: ctf-web — CTF Web 攻击知识库
supporting reference: rapid-checklist — 速查与 payload 清单 Available reference files, load only if useful withload_skill_reference: php-code-audit-checklist.md, ssti-injection-chains.md, ...

注意：正文一个字都没有注入。模型只知道自己"可以读什么"，而不是"被塞了什么"。

五、load_skill_reference：模型自主翻页

当模型判断需要某份文档时，它会主动调用内置工具load_skill_reference（schema 定义在 vulnclaw/agent/tool_schemas.py）：

参数	说明	示例
`skill_name`	Skill 名称	`ctf-web`
`reference_name`	参考文档文件名	`ssti-injection-chains.md`

工具执行链路：builtin_tools.py 收到调用 → 转交 load_skill_reference() 定位references/目录下的对应文件 → 只读取那一个文件的内容返回。更妙的是，每次成功加载都会调用state.record_loaded_reference()登记——最终报告里能追溯"哪些参考文档真正被读过"，形成完整证据链。

用户输入 "帮我看看这个 PHP 站有没有 SSTI 漏洞" │ ▼ ① 索引层：list_*_skills() 扫描目录名 + frontmatter（不读正文） ▼ ② 路由层：SkillResolver 打分 → 主选 ctf-web，附送 rapid-checklist ▼ ③ 暴露层：skill_context 只渲染"参考索引"给模型 ▼ ④ 读取层：模型判断需要 → 调 load_skill_reference 读单份文档 ▼ ⑤ 溯源层：record_loaded_reference 登记，报告可审计

🎯 这套「先给目录、再按需翻书」的设计，把上下文占用从"全量 KB"压到"一屏目录 + 几份精读文档"，既省 Token 又让模型保持策略主动权。

六、动手实践：如何为自己的 Skill 接入这套机制

只需两步即可享受同样的按需加载能力：

建目录：<你的Skill名>/SKILL.md+ 可选的references/*.md，frontmatter 里写清description和routing（词表参考 routing.py）
放位置：核心/专项 Skill 在 vulnclaw/skills/ 下；自定义 Skill 放入配置目录skills/即可被list_custom_skills()发现

写作建议：SKILL.md正文保持精简（它决定索引描述），把长内容拆进references/——因为 references 才是按需读取的主角，正文太长反而挤占索引描述的空间。