如果你最近在折腾AI编程助手一定绕不开一个词skill。GitHub上各类skill仓库一夜之间多了起来有人做会议纪要有人做PPT生成有人把论文检索流程也塞进去。但真正面向安全审计场景的skill翻来覆去就那么几个而且大多只是把一份安全清单丢给模型让它“照着检查”结果模型吐出来的报告又空又泛落到实际项目里基本没法用。我花了一段时间把代码安全审计、依赖风险核查、敏感信息扫描和配置基线检查这几件事拆开重新整理成了一个可复用的security-audit-skill今天把它的设计思路、实现细节和踩坑记录完整写下来。先给一个基本判断安全审计是一个天生适合Skill化的工作。它的流程高度固定结果要求可验证而且同一个项目的不同模块、不同项目的同类框架之间审计规则可以大量复用。只要把规则拆清楚让模型按固定路径执行产出就能稳定很多。这篇文章适合正在做Agent Skill开发的人也适合想把AI用进代码审计、又不想只会写“请检查安全漏洞”这种无效提示词的工程师。1. 为什么需要一个专门的安全审计 Skill1.1 从“会写代码”到“会审代码”的距离很多团队对AI编程助手的期待是“写完功能顺便把安全也查了”但现实是模型写代码和审代码是两个完全不同的能力。写代码时模型倾向于“生成看起来合理的实现”而安全审计要求的是“带着怀疑去读每一行代码”这两种思维模式在一个对话里很容易互相干扰。你让模型“检查这个项目有没有安全问题”它常常会顺着功能逻辑走最后给你几条不痛不痒的建议比如“建议使用参数化查询”却说不清楚具体哪个文件、哪一行存在注入风险。所以我需要的不是一个“会聊安全的模型”而是一个“按安全审计流程执行任务的技能包”。security-audit-skill的出现就是想把“人工审计经验”转成模型能稳定执行的步骤先看什么文件、按什么规则匹配、证据怎么定位、报告怎么分级。这个思路和把某个领域的专家经验做成SOP是同一个道理只是在AI场景里这份SOP需要写得更精确因为模型不会像人一样自动理解“模糊的经验”。1.2 Skill 到底是什么和 Agent 有什么区别最近“agent skill”这个词被反复提到搜“skill和agent的区别”的人也不少。我在做这个项目之前也反复确认过边界。我的理解是Agent 是调度器它负责理解用户目标、拆解任务、调用工具、循环执行Skill 是操作手册它告诉模型“在某个特定领域里应该用什么方法、按什么步骤、输出什么格式”。两者不是替代关系而是配合关系。一个Agent可以在同一个任务里调用多个Skill先用“代码检索Skill”定位文件再用“security-audit-skill”做审计最后用“报告生成Skill”整理结果。Skill本身不负责决策只负责把特定领域的方法论固化下来。如果你把Agent比作一个项目经理Skill就是项目经理手里那一沓标准作业流程卡。一个人可以带一沓卡也可以随时换卡但卡本身替代不了项目经理的判断。对比项SkillAgent核心职责固化和复用某个领域的操作方法理解目标、规划步骤、调度资源和工具是否自主运行不自主等Agent或用户调用能自主执行任务循环输出形式通常是一组指令、规则、模板、脚本是最终任务结果或交互过程典型例子安全审计技能、PPT制作技能、论文检索技能一个能接管整个“代码评审”任务的智能体很多新手容易把“写一个skill”当成“做一个agent”其实skill做得再好也需要一个合适的Agent/模型框架去加载它。反过来Agent如果没有对应领域的skill处理专业任务时只能依赖通用推理效果会明显差一截。security-audit-skill的目标就是在“安全审计”这个专业领域里把通用模型补成“懂流程、有规则、会取证”的审计员。1.3 我把安全审计拆成了哪些能力单元做skill最容易犯的错是一上来就写一堆规则然后等模型自己消化。我在这个项目里做的第一件事是拆解安全审计的最小能力单元。目前拆成六块每一块对应一个独立的规则文件输入校验重点关注SQL注入、命令注入、路径穿越、反序列化入口。认证与授权重点看登录逻辑、会话管理、越权访问、硬编码凭据。密码学实践重点看加密算法选择、密钥存储、随机数使用是否安全。依赖风险基于构建文件检查已知漏洞版本、过期依赖和许可证风险。配置基线检查默认密码、调试开关、敏感端口、云存储权限、数据库配置。敏感信息泄露在全项目中扫描密钥、token、证书、内网地址。这六块的顺序也有讲究。每次审计先做敏感信息扫描再做输入校验再做认证授权最后看配置和依赖。原因是前两类问题在代码静态特征上最容易定位模型给出高置信度结论的概率更高能够快速建立“这个skill确实有效”的正反馈而认证授权和配置基线更依赖业务上下文适合放到后面结合具体代码结构分析。拆完之后每个规则文件只负责一个领域模型在审计时按顺序读取规则而不是一次性吞下一大段混杂的文本这样上下文更干净误报率也低很多。2. 安全审计 Skill 的整体设计思路2.1 输入设计只给模型看该看的东西安全审计最大的敌人是上下文杂乱。很多人在使用AI审计时喜欢把整个项目目录都抛给模型觉得“看得越多越安全”但实际上模型在长上下文里的注意力会明显衰减很容易把核心漏洞淹没在大量无关代码里。我在设计security-audit-skill时第一步就是限定输入范围。输入阶段要求先做两件事识别项目类型和构建文件再圈定审计范围。比如Java项目优先看pom.xml、src/main/java下的Controller、Service、Utils和配置文件Python项目优先看requirements.txt、pyproject.toml、入口文件和所有涉及外部输入的函数。生成代码、依赖缓存目录、构建产物目录默认跳过不是不审而是不值得在首轮审计中占用上下文。如果一轮审不完就按模块分批继续。同时我会要求模型先输出“本次审计范围内的文件清单”再开始逐项分析。这一步看起来多余但它有两个实际作用一是让模型明确任务边界避免跑到无关文件里浪费时间二是给使用者一个确认机制如果发现该审的文件没被纳入可以及时补充而不是等报告出来才发现漏了核心模块。2.2 规则分层把人工经验转成可执行步骤安全审计规则不能是“一句建议”而应该是“一组可执行的动作”。我在项目里把规则分成三层模型和脚本分别处理不同粒度的问题。第一层是通用基础规则适用于任何语言和项目比如“硬编码密钥”“使用过时的加密算法”“未使用参数化查询”这类跨语言通病。第二层是框架特定规则比如Spring Boot项目的权限注解是否齐全Express项目的helmet中间件是否引入Django项目的SECRET_KEY是否暴露在版本库中。第三层是环境基线规则比如是否开启了DEBUG模式、数据库连接串是否有弱口令特征、对象存储桶是否配置了公共读写。这三层规则不是一起灌给模型的而是先通过脚本做初筛再交给模型做语义判断。比如“扫描硬编码密钥”这类特征明确的检查用正则脚本扫一遍比模型逐个文件读Token准确得多而“越权风险是否真实存在”这种只能靠业务语义判断的问题脚本做不了就交给模型处理。这样设计的好处是把模型从低价值的重复劳动里解放出来让它把注意力集中在真正需要推理的地方。2.3 输出设计不只是报告还要给修复建议审计报告如果只列“存在哪些问题”对团队来说价值有限。真正可执行的报告必须包含四个部分问题定位、风险等级、证据片段、修复建议。缺任何一个环节都会增加使用者的确认成本。我在SKILL.md里规定报告必须使用统一模板每个问题都必须带上“文件路径行号代码片段问题类型风险等级修复建议”。风险等级分为Critical、High、Medium、Low四档Critical表示可直接利用且暴露面大例如数据库连接串硬编码在公网仓库中High表示大概率可被利用例如用户输入直接拼接到SQL语句Medium表示需要特定条件才能利用Low表示代码风格或潜在隐患建议人工确认。等级判断标准也写进规则文件里避免同一个问题在不同模型版本里输出不同结论。输出模板还被要求包含一个“已检查项清单”。这一步很重要模型在被要求逐条列出已检查规则时会自然更严格地执行规则而不是跳步直接给结论。这算是我在调试过程中发现的一个很实用的技巧你越要求模型展示过程它越不容易敷衍。3. 核心实现SKILL.md 和配套脚本3.1 仓库目录结构整个security-audit-skill的仓库结构非常简单核心是SKILL.md加rules、scripts、templates三个目录。目录结构如下security-audit-skill/ ├── SKILL.md ├── rules/ │ ├── 01-input-validation.md │ ├── 02-auth.md │ ├── 03-crypto.md │ ├── 04-dependency.md │ ├── 05-config.md │ └── 06-secret.md ├── scripts/ │ ├── secret_scan.py │ ├── dep_check.py │ └── file_index.py ├── templates/ │ └── audit_report.md ├── examples/ │ ├── spring-boot-audit.md │ └── node-express-audit.md └── README.mdrules目录里的每个文件都只解决一个问题域文件名前面的数字决定了模型读取规则的顺序。scripts目录里放着轻量辅助脚本用来完成文件索引、敏感信息初筛、依赖版本对比这类机械性工作。templates目录是报告模板所有审计结果都按这个模板输出。examples目录是示例报告模型可以参考示例来对齐自己的输出风格。这个结构并不复杂但它刻意保持了一种“开放约定”SKILL.md被Agent框架加载后框架会按约定去读rules目录里的文件而scripts目录里的脚本既可以被模型通过命令行调用也可以被其他自动化流水线独立使用。这样一来skill本身不依赖特定框架谁都能拿过去用。3.2 SKILL.md 该怎么写SKILL.md是整个skill的入口文件几乎所有主流的skill加载方式都要求这个文件存在。它通常包含两部分YAML元信息和执行指令。我目前使用的模板大致是这样的--- name: security-audit description: 当用户要求对代码项目进行安全审计、漏洞扫描、依赖风险检查、敏感信息泄露排查或配置安全检查时使用此技能。 --- # security-audit ## 目标 对指定项目进行系统化安全审计输出包含证据、风险等级和修复建议的可执行报告。 ## 输入要求 1. 先识别项目类型与构建文件确认审计范围。 2. 使用 scripts/file_index.py 生成待审计文件清单。 3. 默认跳过生成目录、依赖缓存目录、构建产物目录。 ## 执行步骤 1. 读取 rules/ 目录下的规则文件按照编号顺序加载。 2. 对每个规则先使用脚本或关键词初筛再结合代码上下文判断是否命中。 3. 每个问题必须记录文件路径、行号、关键代码片段。 4. 按 templates/audit_report.md 输出审计报告。 ## 输出格式 必须包含风险等级、问题描述、证据定位、修复建议、已检查项清单。 ## 注意事项 - 不要只给结论必须给证据。 - 无法确认的风险统一标记为“待人工确认”。 - 不要建议关闭安全机制来修复问题。这里最值得注意的细节是description字段。它不是给人看的而是给Agent的匹配器看的它决定了模型在什么情况下会触发这个skill。写得太笼统比如“安全相关”会导致很多无关任务误触发写得太具体比如“只处理Spring Boot项目”又会漏掉其他语言项目。好的写法是列出用户可能的多种表达方式包括“安全审计”“漏洞扫描”“依赖风险”“敏感信息泄露”等让匹配器的召回率更高。3.3 规则文件与脚本配合每个rules目录下的文件都有固定结构我以02-auth.md为例拆解一下。它开头是一段简短的目的说明中间是具体检查项最后是记录格式。检查项不是一句废话而是尽量写成“可判断的命题”比如“是否使用框架自带的登录认证机制而不是自研登录逻辑”“是否将密钥存储在环境变量或密钥管理系统中而不是写在代码中”“是否存在未加权限校验的管理接口”。每个检查项后面还会标注“匹配方法”比如“关键词搜索”“调用链分析”“人工确认”这样模型知道自己该用什么手段取证。脚本和规则配合的关键点在于脚本只做“初筛”不直接判定漏洞。比如secret_scan.py会用正则扫出疑似硬编码的密钥但它输出的只是“可疑位置”最终是否确认为泄露需要模型结合上下文判断。我在脚本里专门加了置信度字段正则匹配到明文密码字符时标记为“高”匹配到变量名暗示密钥但值不明确时标记为“低”这个设计大大降低了模型的误报率。依赖检查脚本的核心逻辑也比较简单先用parsers解析构建文件里的依赖列表再去本地或在线漏洞库比对版本。考虑到不同项目环境差异很大这个脚本支持离线模式可以预先导入一份漏洞版本表避免要求用户每次审计都联网更新。这样即使内网环境也能正常跑。3.4 通用适配别绑死某个Agent做skill时最容易踩的坑是把自己绑定到某一个Agent框架上。现在流行的Codex、Claude、各类支持skill的开源框架加载skill的方式都不完全一样。有的要求把SKILL.md放在特定目录有的要求通过插件市场安装有的直接用文件夹名作为技能名。我写这个skill时尽量只依赖SKILL.md和通用脚本不做任何框架专属配置这样无论是手动放入项目目录还是通过第三方skill市场导入都能正常运行。如果你也想让自己的skill有更强的适配性有几点可以参考不要使用某个框架独有的模板语法不要在YAML头里写只对某个平台生效的字段脚本用shell或Python这类通用语言控制在单文件内尽量不引入需要额外安装的依赖。这样别人拿到你的skill后只需复制目录、导入规则就能在自己的Agent环境里跑起来而不是被迫跟着你用的框架走。4. 实操从代码到审计报告4.1 准备与加载拿到一个项目后我会先把它放到本地目录再把security-audit-skill复制到Agent能够加载的位置。以命令行工具为例可以在项目根目录执行cd /path/to/your-project # 把skill目录放到当前Agent约定的skills目录下 # 例如~/.config/agent/skills/security-audit/ cp -r security-audit-skill ~/.config/agent/skills/security-audit加载完成后直接给Agent一句话任务“请使用security-audit技能审计当前项目重点看认证和依赖风险。”这里的关键是明确表达“使用这个技能”而不是简单说“帮我看看安全”。显式触发会让Agent优先读取SKILL.md而不是凭感觉自由发挥。系统会先运行file_index.py扫描出项目中需要审计的文件清单。正常情况下一个中等规模的Java项目会在几秒内生成一份列表格式类似下面这样$ python3 scripts/file_index.py --project . --skip target,node_modules,.git [INFO] Found 126 Java files, 3 pom.xml, 41 config files. [INFO] Audit scope generated: src/main/java, pom.xml看到这个结果我会再和阿特确认一下比如“先审Controller和Service层工具类和DTO先跳过”。这一步能有效控制上下文长度让模型把精力放在风险最集中的逻辑代码上。4.2 执行一次完整审计我拿一个模拟的Spring Boot项目跑了完整流程项目不大有60多个Java文件、2个pom.xml。初步审计后模型按模板输出了一段报告其中一个关键问题被定位在用户登录接口// UserController.java:42 String sql SELECT * FROM users WHERE username username AND password password ;对应报告片段写得很清楚风险等级Critical问题类型SQL注入证据定位src/main/java/com/example/controller/UserController.java:42-44问题描述用户输入name直接拼接进SQL查询语句攻击者可通过构造单引号闭合语法获取未授权数据。修复建议改用JPA参数绑定或MyBatis的#{}占位符不要用字符串拼接同时为数据库账号设置最小权限降低注入后的影响范围。这个例子里模型不是光说“建议使用参数化查询”而是先给出了精确到行的证据再给修复建议。这个效果就是SKILL.md里规定“证据定位”和“风险等级”带来的。如果没有这两条硬性要求模型很容易泛泛而谈。除了代码漏洞脚本还扫描出pom.xml里有三个依赖版本低于当前安全版本线其中spring-webmvc的版本存在已知的反序列化风险被标为High。依赖检查脚本直接给出“推荐升级到5.3.39”这样的建议省去了我去查漏洞库的时间。4.3 结果解读与修复闭环拿到报告后我最关心的不是“有多少个问题”而是“Critical和High有几个能不能复现修复后有没有回归”。这个skill输出的报告自带优先级排序我一般按等级逐个处理先把Critical级别的问题修完再处理HighMedium和Low人工快速过一遍。修复后我会重新跑一次审计重点看两个地方一是有没有新增问题二是原问题的“证据定位”是否消失。很多团队修完漏洞后不做回归结果同一个位置换了一种写法又引入了类似问题。这个问题用AI审计倒是很好解决因为模型是重新扫描整个项目只要规则没变它不会因为“上次已经报告过”就降低标准。我在实际使用中还会把修复后的commit记录保存下来便于以后回溯。整个流程走下来从准备到出报告大概十来分钟。如果完全靠人工审同样的范围至少需要半天。效率提升是很明显的但前提是你要接受“AI审计的结果需要人工复核”这件事。5. 常见问题与排查技巧实录5.1 模型不按规则走怎么办这是我在调试过程中遇到最多的一个问题。第一次写完SKILL.md时模型经常跳过读取规则文件的步骤直接凭常识给结论。后来我在执行步骤里加了一条强制要求“必须先输出正在读取的规则编号和规则名称再输出该规则的检查结果。”一旦模型需要“展示过程”它就很难跳过规则文件因为不读取规则就写不出过程说明。另一个有效手段是在输出模板里加“已检查项清单”。每次审计报告最后必须列出“本次覆盖了哪些规则、哪些规则因为范围限制未覆盖”。这一条会让模型主动确认自己还有哪些没做出现漏检的概率下降很多。如果模型还是没有执行规则优先检查是不是description写得太含糊导致Agent根本没有触发这个skill或者加载时把skill目录结构放错了位置。5.2 误报率太高怎么压误报率高通常不是模型的错而是规则本身写得不够精准。早期我在规则里写“检查是否使用弱加密算法”模型就会把所有用到对称加密的地方标成Medium哪怕是AES-256-GCM这种目前还合理的算法也被误伤。后来我把规则改成“优先关注硬编码密钥、固定IV、ECB模式、MD5/SHA1用于密码存储”这类具体特征误报率立刻降下来一大截。同时脚本初筛的置信度标注也很有用。secret_scan.py对结果分为“高置信度”和“低置信度”高置信度结果才会进入审计报告低置信度结果放在“待确认”附件里供人工参考。这样既不会漏报也不会让报告被疑似项刷屏。如果你发现误报还高建议把规则里的“是否”式问句全部改成更具体的“匹配什么特征”式命题越具体越不容易误判。5.3 上下文太长导致审计变形大型项目的上下文控制是逃不掉的问题。有一次我试过对一个大仓库做全量审计结果模型到后半段开始“失忆”前文定义的规则名都记不住明明扫描到的漏洞也漏报。后来我把审计策略改成了分批模式先按目录拆分成多个模块每个模块单独审计再汇总所有模块的报告。模块大小控制在“100个文件以内、核心逻辑文件不超过60个”比较稳。另一个更轻量的方案是先用脚本把“文件摘要”生成好再把摘要和关键代码片段一起喂给模型。比如用file_index.py输出每个文件的功能摘要和风险关键词模型不需要读全部文件内容就能先判断哪些文件值得深入审。这种方式对超大型项目特别有效可以把上下文占用压缩到原来的三分之一以下。5.4 多语言项目怎么处理一个项目里同时存在Java、Python、JavaScript很常见。我的做法是始终先跑“通用规则”再按语言加载对应规则。通用规则覆盖硬编码密钥、硬编码密码、过时加密算法、反序列化入口等跨语言问题语言特定规则再处理各自框架的常见坑。比如Java看Spring Security配置有没有生效Python看Django的DEBUG和ALLOWED_HOSTS前端看是否把API密钥打包进静态资源。scripts/file_index.py会识别项目里的构建文件和源码后缀自动生成“按语言分类的可审计文件清单”。模型收到这个清单后会按语言分组执行审计最后报告里分类呈现。这个方案避免了在同一个上下文里反复切换语法规则导致的混乱也方便团队里的不同语言owner按模块认领问题。6. 一点个人经验总结最后分享几个实际做下来真正有效的体会。第一skill的规则一定不要贪多少而精才是关键。一个能稳定执行五条规则、每条都出证据的skill远比一个列了一百条规则、但模型只能走马观花的skill有用。我早期把规则加到接近四十条结果报告质量反而下降最后精简到六类核心规则效果稳定很多。第二AI安全审计最适合的定位是“第一道安检”不是“最终法官”。它能帮你快速定位可疑代码、缩小人工审查范围但高危漏洞是否真实可利用、修复方案是否影响业务仍然需要人来做最终判断。把这个定位想清楚你就不会对模型产生不切实际的期待。第三skill的价值会在长期使用中持续累积。每次审计完把误报和漏报的案例整理成新的规则项或示例不断迭代规则文件这个skill会越来越贴合你团队的代码风格和业务场景。我现在的建议是单独建一个runtime_notes.md专门记录哪些规则在本项目里误报高、哪些高风险点值得追加检查。经过几轮迭代后审计准确率会有非常明显的提升。如果你也想动手写自己的skill不妨就从安全审计这个方向切入它足够专业、规则清晰、结果可验证比做一个泛泛的“通用助手skill”更能锻炼你对Agent和模型行为边界的理解。后面我还会把SBOM生成、容器镜像扫描这些能力逐步并入这个skill让审计覆盖面更完整。