直接说结论把安全审计这种“高重复、强规则、容错率低”的活儿交给AI最好的落地方式不是现写一次性提示词而是把它固化成一套可复用的技能包也就是现在社区里常说的Skill。我最近做完的这个security-audit-skill就是专门干这个用的它不只是一个提示词文件而是把审计的流程、规则、检查项、报告模板全部封装成了一个标准化的技能模块能直接挂到Claude Code、Codex这类Agent工具上让AI按同一套标准去执行代码安全审查。这篇就把我整个设计思路、文件结构、核心规则怎么写、踩过哪些坑全部摊开讲一遍。如果你正准备给自己的Agent加技能或者想把手里的安全审计经验沉淀成可复用的东西这篇文章应该能帮你省下不少试错时间。1. 内容整体设计与思路拆解1.1 为什么安全审计最适合做成Skill先说个现象。我见过太多人让AI帮忙审代码要么是扔一段代码问“有没有漏洞”要么是贴一个OWASP Top 10让AI“检查一下”。这两种方式都有个共同问题每一次对话都是一次全新的“即兴发挥”AI这次记得检查SQL注入下次可能就忘了检查硬编码密钥审计结果完全取决于当天的心情和上下文的运气。安全审计这件事本质上是一套非常固定的流程先看依赖清单再扫敏感信息然后查危险函数最后检查权限配置每一步都有明确的检查项和判定规则。这种“流程固定、规则明确、重复执行”的任务正是Skill最擅长处理的场景。Skill这个东西你可以理解成给Agent装了一个“岗位说明书”。它不是简单的提示词而是把一套完整的执行方案——包括角色设定、工作流程、检查规则、输出格式——打包成一个独立目录Agent只要加载这个目录就能按照里面定义的规范去执行任务。这和“临时说一嘴”的本质区别在于Skill有结构、有边界、有固定的输出格式结果可预期。1.2 安全审计Skill应该覆盖哪些核心场景在设计security-audit-skill的时候我把审计目标分成了四类这也是目前绝大多数项目最迫切的需求第一类是依赖安全。现在一个项目动辄几十上百个第三方包任何一个包存在已知漏洞整个系统就可能是裸奔状态。Skill需要自动化检查依赖清单文件比对漏洞库输出风险等级。第二类是敏感信息泄露。这是我在实际项目中遇到最多的问题私钥传到Git仓库、数据库密码写死在配置文件里、API Token硬编码在前端代码中这类问题几乎每个代码库都能翻出来几个。Skill需要识别各种格式的密钥、Token、连接串。第三类是危险函数与不安全编码。比如直接把用户输入拼进SQL、用eval执行不可信字符串、反序列化没做过滤这些属于代码层面的“硬伤”规则非常明确非常适合做成自动化检查项。第四类是权限与配置安全。包括不安全的CORS配置、缺失的认证鉴权、过于宽松的文件权限、调试模式未关闭等。这类问题往往藏在配置文件里容易被忽略但危害极大。这四个场景不是拍脑袋定的而是我梳理了过去一年里实际接触到的几十个安全事件和漏洞报告后归纳出来的高频问题。Skill的覆盖范围不求大而全先把最高频、最规则化的场景做好后面再逐步扩展。1.3 从“临时提示词”到“可复用技能”的演进路径我在做这个Skill之前其实已经积累了大量安全审计的提示词片段但它们散落在各个笔记和聊天记录里用的是时候要翻半天而且每次用的效果都不稳定。后来我意识到真正需要的不是更多的提示词而是一个把这些经验“结构化”的容器。Skill恰好提供了这个容器把检查规则写成一个文件把执行步骤写在另一个文件把输出模板单独放一份再把使用说明和示例也放进去。这样整个技能就成了一个可以独立分发、版本管理的“知识包”。更关键的是Skill的目录结构天然支持“渐进式积累”。刚开始可以把最基本的检查项放进去运行一段时间后根据实际项目里发现的新问题不断往规则文件里追加内容。我现在的security-audit-skill已经迭代到第三个大版本最初的版本只有依赖安全和敏感信息两个模块后来才逐步加入了危险函数、权限配置、报告生成等能力。这种演进路径也符合我对Skill这件事的理解它不只是一个技术文件更是一套个人经验的沉淀系统。每一次审计发现问题都是对Skill的一次“训练”让下一次审计变得更准。2. 核心细节解析与实操要点2.1 Skill目录结构的设计思路一个规范的Skill目录本质上是在告诉Agent三件事你是谁、你要做什么、你该怎么做。我的security-audit-skill目录结构如下security-audit-skill/ ├── SKILL.md # 技能主文件定义角色、职责、工作流程 ├── rules/ │ ├── dependency-audit.md # 依赖安全检查规则 │ ├── secret-detection.md # 敏感信息检测规则 │ └── dangerous-code.md # 危险函数与编码问题规则 ├── templates/ │ └── report-template.md # 审计报告输出模板 ├── examples/ │ ├── sample-vulnerable.py # 示例漏洞代码 │ └── sample-report.md # 示例审计报告 └── references/ └── known-vuln-db.md # 常见漏洞速查表这个结构看起来简单但每个目录的作用都很明确。SKILL.md是入口文件Agent加载Skill时首先读取这个文件所以它必须包含“何时使用该技能”的触发条件说明以及整个工作流程的概览。rules目录放的是核心规则每个规则文件聚焦一个领域这样做有几个好处单个文件不会过长导致Agent“迷失重点”规则可以按需增删不影响其他模块文件粒度小方便用diff进行版本管理哪条规则改了清清楚楚。templates和examples目录是很多人容易忽略的部分。没有模板Agent输出的报告格式就会随心所欲没有示例Agent对“好的审计结果”就没有参照物。这两个目录是保证输出质量的关键。references目录则是给Agent准备的“背景知识库”一些不适合写进规则、但审计时又必须参考的漏洞特征和风险评级标准都存在这里。2.2 SKILL.md主文件的编写要点SKILL.md是整个技能的“大脑”它的质量直接决定了Agent的行为表现。我写这个文件的时候重点把握了四个关键部分。第一部分是“技能定位声明”用一两句话说明这个技能是做什么的。这里要注意不是写“你是安全专家”而是写“你负责对目标代码库执行结构化安全审计”而且要明确说明技能的使用边界比如“不负责修复漏洞只负责发现并报告问题”。边界清晰Agent才不会跑偏。第二部分是“触发条件”告诉Agent什么情况下应该启用这个技能。我写了这样一段话当用户要求对代码库、项目目录、Git仓库或单个源文件进行安全审查、 漏洞检测、风险评估时自动启用本技能。 涉及关键词包括但不限于安全审计、security audit、漏洞扫描、 代码安全审查、依赖风险检查等。触发条件写清楚Agent就不会在用户问“帮我重构这个函数”的时候莫名其妙地启动安全审计流程。第三部分是“工作流程定义”这是核心中的核心。我把审计流程拆成了五个固定步骤先扫描项目结构创建文件清单再检查依赖清单文件比对已知漏洞库然后扫描源码中的敏感信息接着审查危险函数和编码规范最后生成结构化审计报告。每一步都配了详细的操作说明和“必须遵守”的约束条件。第四部分是“输出要求”。明确规定了报告必须包含哪些章节、用什么格式组织、漏洞等级怎么标注。这部分和templates目录下的报告模板遥相呼应确保每次输出都有稳定的格式。写SKILL.md的时候有一个容易犯的错把检查规则也写进主文件。我最初也这么干过结果发现AI在长上下文中执行时后面的规则很容易被“遗忘”。后来把规则拆到rules目录主文件只做流程编排问题就消失了。Agent在需要的时候再去读取对应规则文件记忆负担小得多。2.3 规则文件怎么写才能让AI真正执行写完SKILL.md只是第一步真正决定审计质量的是rules目录下的规则文件。这些文件是所有检查项的“执行标准”写法上和写开发规范完全不同。规则不是“建议”而是“判定条件”。以secret-detection.md为例我写了这样一条规则检测目标 - 私钥文件匹配BEGIN RSA PRIVATE KEY、BEGIN OPENSSH PRIVATE KEY等头部 - 云服务密钥AWS Access Key ID格式AKIA[0-9A-Z]{16}、 阿里云AccessKey ID格式LTAI[0-9A-Z]{12,20} - 通用API Token长度为32-64的base64字符串且出现在 api_key、token、secret等变量名附近 报告要求 - 每条匹配结果必须标注文件路径、行号、匹配内容脱敏处理、 泄露类型、风险等级 - 风险等级判定规则 P0私钥、口令、高权限凭证泄露如AWS Root Key P1低权限API密钥、内部系统Token P2疑似Token但无法确认如普通长度的随机字符串 - 所有报告内容必须对敏感信息进行脱敏处理严禁输出完整密钥这种写法有个关键点把判定条件写得非常具体甚至直接给正则表达式。为什么因为规则文件不是给人看的文档而是给AI执行的操作手册。规则写得太模糊比如“检查是否存在敏感信息泄露”AI只能凭感觉做事结果无法复现。规则写得足够具体AI才能像执行代码一样照着做。另一个经验是每个规则文件都要带上“负面清单”。我会明确告诉AI“不需要检查什么”防止它把注意力浪费在不重要的事情上。比如dangerous-code.md里我就注明纯前端页面、文档目录、测试夹具目录不纳入危险函数检查范围。这样既节省了Token和时间也避免了误报。还有一点必须强调规则文件不要追求“一篇顶十篇”。与其写一个超长的综合规则不如拆成多个短小聚焦的文件。短文件Agent容易完整读取规则之间的干扰也少。我现在每个规则文件控制在150行以内如果某个领域规则特别多就再拆成更细的子文件。3. 实操过程与核心环节实现3.1 从零搭建Skill的完整步骤说了这么多设计思路直接进入实操环节。从零开始搭建一个security-audit-skill我习惯按下面的顺序操作。第一步是本地建目录。先创建一个空目录按前面说的结构把子目录建好。这个阶段不用想太多先把“骨架”立起来后面再填肉。第二步是写SKILL.md。我会先写技能定位、触发条件和输出要求这三部分工作流程部分先写下五个大步骤的框架具体细节留到后面再补。为什么先写主文件因为主文件是整个技能的“锚点”后续写规则文件和模板时要反复对照主文件的流程设计确保整体不跑偏。第三步是逐个写规则文件。写规则的顺序建议和审计流程保持一致先从依赖安全开始因为这是规则最明确、最容易量化的然后写敏感信息检测这个模块见效最快测试的时候能立刻发现问题最后写危险函数和权限配置这两块对代码理解能力要求高规则需要反复调优。第四步是写报告模板。报告模板要和SKILL.md里的输出要求一一对应我习惯把模板设计成“填空题”而不是“自由发挥题”这样AI生成的报告不需要二次加工就能直接用。第五步是准备示例。我从自己的项目里抽了几个典型文件一个包含硬编码密钥的Python脚本一个依赖清单里有已知漏洞的package.json还有一个CORS配置错误的Spring Boot配置类。有这些真实例子测试的时候才能验证规则是否真的能命中问题。最后一步是测试与迭代。我会用几个不同的测试项目跑一遍Skill每次跑完检查两件事有没有漏报有没有误报。漏报说明规则不够误报说明规则过宽两边都需要不断校准。3.2 SKILL.md完整示例解析下面是我的SKILL.md文件的核心内容已脱敏整理你可以直接参考这个结构去写自己的版本# Security Audit Skill ## 技能定位 本技能用于对指定代码库执行结构化安全审计。审计范围包括 依赖安全、敏感信息泄露、危险函数、权限与配置安全。 ## 触发条件 当用户要求对代码库、项目目录、Git仓库或单个源文件进行安全审查、 漏洞检测、风险评估时自动启用本技能。 涉及关键词安全审计、security audit、漏洞扫描、代码安全审查等。 ## 工作流程 执行审计时必须严格按以下步骤操作 1. 扫描项目结构识别语言、框架、包管理工具 生成项目文件清单跳过node_modules、vendor、.git等目录。 2. 检查依赖清单文件package.json、requirements.txt、pom.xml等 读取 rules/dependency-audit.md 对照漏洞规则执行检查。 3. 扫描源码中的敏感信息读取 rules/secret-detection.md 执行检查。 4. 审查危险函数与不安全编码模式读取 rules/dangerous-code.md 执行检查。 5. 检查配置文件中的权限与安全设置CORS、鉴权、调试模式等 读取 rules/config-security.md 执行检查。 6. 汇总所有发现按 templates/report-template.md 生成审计报告。 ## 执行约束 - 严禁输出完整密钥或敏感信息报告中所有敏感内容必须脱敏。 - 审计只负责发现问题并给出修复建议不负责直接修改代码。 - 无法确认的问题标记为“待人工复核”不得武断判定。 - 每项发现必须标注文件路径、行号、风险等级与修复建议。需要注意几个细节。第一“执行约束”这个部分必须单独写它相当于给AI划定行为边界。第二每步操作都写了“读取某个规则文件”这是在告诉AI这些文件是这一步的操作手册你要去读。很多Skill写得不好就是因为没有这一步显式的“文件关联”导致AI根本不知道还有规则文件这回事。第三流程顺序是严格递增的审计必须按顺序执行不能跳步。3.3 规则文件实例敏感信息检测规则接下来看一个具体的规则文件示例这是我迭代了多个版本之后的secret-detection.md# 敏感信息检测规则 ## 检测范围 扫描目标目录下的所有文本文件排除以下目录和文件 - 二进制文件图片、压缩包、可执行文件 - lock文件package-lock.json、yarn.lock等 - 测试夹具和mock数据目录 ## 检测规则 ### 规则1私钥与证书 - 匹配特征PEM格式私钥头部 - BEGIN RSA PRIVATE KEY - BEGIN EC PRIVATE KEY - BEGIN OPENSSH PRIVATE KEY - 风险等级P0致命 - 修复建议立即撤销该密钥检查Git历史中所有包含该密钥的提交 ### 规则2云服务厂商密钥 - 匹配特征 - AWS Access Key IDAKIA[0-9A-Z]{16} - 阿里云 AccessKey IDLTAI[0-9A-Z]{12,20} - 腾讯云 SecretIdAKID[0-9A-Za-z]{13,32} - 风险等级P0致命 - 修复建议在云控制台禁用对应密钥轮换新密钥并配置密钥管理服务 ### 规则3数据库与中间件连接串 - 匹配特征 - mongodb:// 或 mongodbsrv:// 开头的连接串 - jdbc:mysql:// 开头的连接串 - postgres:// 开头的连接串 - 连接串中包含用户名和密码如 :passwordhost - 风险等级P1高危 - 修复建议连接信息迁移到环境变量或密钥管理系统数据库口令立即变更 ### 规则4常见API Token - 匹配特征 - 变量名为 token、api_key、apikey、secret_key、access_token 值为长度16以上的字母数字混合字符串 - GitHub Tokenghp_[0-9A-Za-z]{36} - Slack Tokenxox[baprs]-[0-9A-Za-z-]{10,} - 风险等级P1高危 - 修复建议在对应平台撤销Token并重新生成代码中使用环境变量引用 ## 报告要求 - 每条命中必须记录文件路径、行号、规则编号、风险等级、推荐修复方案 - 所有匹配到的敏感值在报告中只保留前4位和后4位中间用****代替这个文件看着简单但里面的门道不少。风险等级划分是必须的没有等级的报告评审方很难排优先级。每条规则都带修复建议这能让AI在报告中直接给出可操作的方案而不是只说“发现了一个问题”。匹配特征写得具体但不是无脑堆正则有时候“变量名值特征”的组合比纯正则更准能明显减少误报。3.4 报告模板设计与输出效果报告模板是很多人最后才想起来的东西但它的重要性不亚于规则文件。没有模板时AI生成的报告可能是段话、可能是个列表看心情来。有了模板报告格式稳定可以直接归档或者转发给团队。我的报告模板结构如下# 安全审计报告 ## 审计概览 - 审计目标 - 审计时间 - 扫描文件总数 - 发现总数 - 风险分布P0 / P1 / P2 / 待复核 ## 风险统计 | 风险等级 | 数量 | 占比 | |---------|------|------| | P0 | | | | P1 | | | | P2 | | | ## 详细发现 ### [P0] 发现项标题 - 文件路径/文件名:行号 - 问题类型 - 详细描述 - 风险影响 - 修复建议 每个发现项按上述结构重复 ## 修复优先级建议 - 优先处理项 - 短期计划项 - 长期改进项 ## 附注 - 本报告由 security-audit-skill 生成需人工复核确认 - 审查人员/ 复核日期这个模板有几个设计巧思。概览部分让读者第一眼就能看到整体风险状况“风险统计”表格让报告可量化方便领导或客户理解“详细发现”部分每项都按固定结构展开既让AI输出有约束也方便阅读者快速定位信息“修复优先级建议”则把审计结果转化为行动项让报告不只是“发现问题”还能“推动整改”。实际使用下来有了这个模板AI生成的报告几乎不需要人工润色就能直接发给技术团队。对比之前用临时提示词得到的“自由发挥”版本效率提升非常明显。3.5 挂载到Agent工具的配置方式Skill做完了最后一步是把它挂载到Agent工具上。目前主流的Agent工具比如Claude Code、Codex、opencode基本都支持通过目录引用的方式加载Skill。以我在Claude Code中的配置为例它会在项目根目录下创建一个.claude/skills目录你把Skill文件夹放进去Agent就能在对话中自动识别并启用。其他工具的原理也类似核心思想都是“把你的技能目录放到Agent约定的位置”。配置完成后可以在对话里输入“对当前项目执行安全审计”来验证。如果Agent正确加载了Skill它会按照SKILL.md里的流程开始执行而不是即兴发挥。这个验证过程非常关键如果你发现Agent输出的内容明显没有按照定义好的流程走那就要检查是不是Skill文件没有放对位置或者SKILL.md里的触发条件没有生效。4. 常见问题与排查技巧实录4.1 高频问题速查表实际使用中我整理了一份问题清单都是自己和身边朋友反复遇到过的情况直接列成表格方便你对照排查问题现象根本原因解决方案Agent没有启用Skill像普通对话一样回答问题SKILL.md中的触发条件不明确或Skill目录不在Agent扫描路径下检查触发关键词覆盖范围确认Skill目录放在.claude/skills等约定位置Skill被加载了但执行流程乱序、跳步SKILL.md中的流程步骤写了但不够显式Agent当作“参考”而非“指令”使用“必须严格按以下步骤操作”等强约束句式步骤编号要清晰每步增加“读取规则文件”指令审计结果漏报严重明明有硬编码密钥却没发现规则文件中的匹配模式过窄或规则文件未被正确读取检查规则文件是否放在rules目录下扩充匹配特征用真实泄露样例测试误报率太高报告里全是无关紧要的“疑似问题”规则写得过于宽泛比如把所有长度为32的字符串都当成Token收紧判定条件增加“变量名值特征”的组合规则使用负面清单排除正常内容报告里出现了完整的密钥内容规则文件没有强调脱敏要求或没有在SKILL.md执行约束中声明在输出要求和规则文件里双重复申“严禁输出完整敏感信息”并在报告模板中写死脱敏格式处理大项目时Token消耗过高规则文件过多导致AI反复读取扫描范围过大压缩规则文件数量在SKILL.md中明确跳过目录node_modules、.git等必要时允许分批扫描Skill在不同项目上表现差异大规则文件依赖特定语言或框架的检查项换项目后不匹配规则文件按语言/框架拆分子目录在SKILL.md中增加“按项目类型选择规则集”的指令4.2 容易被忽略的细节坑除了上面的表格还有几个我踩过坑的细节值得单独拿出来说。第一个坑是正则表达式的“过度匹配”。初版规则里我用了很多宽泛的正则比如把[A-Za-z0-9]{32}当成潜在Token结果在JavaScript项目里疯狂误报因为ESLint生成的hash文件名全是这种格式。后来我改成了“变量名特征值特征”的组合规则误报率直接降了一个数量级。写规则的时候宁可匹配得窄一点也不要为了“不漏”而大量误报。误报太多会让人对报告失去信任比漏报更致命。第二个坑是“示例代码”质量太差。最初我用的是人工编造的测试文件结果AI审计时表现很好一上真实项目就拉胯。后来我才意识到人工编造的例子太“干净”了真实项目里的漏洞往往藏在几百行业务代码中间周围全是无关变量和复杂逻辑。正确的做法是从自己的真实项目里找几个老代码当测试样例哪怕丑一点、乱一点那才代表真实水平。第三个坑是规则文件里写“自然语言描述”而不是“判定条件”。最开始写比如“检查是否存在不安全的反序列化”这类话AI执行的时候完全靠猜。后来改成“查找pickle.loads、yaml.load未指定Loader、ObjectInputStream.readObject等调用点检查传入参数是否来自用户输入或网络数据”效果立刻不一样。规则的描述必须是可执行的AI不是一个隐世高手你给它的规则就是它的全部能力边界。第四个坑是版本管理混乱。Skill文件更新频繁特别是规则文件可能一周要改好几次。如果不做版本管理改出问题很难回滚。我现在用Git管理Skill目录每轮规则调整都单独提交提交信息里注明“调整了哪条规则、为什么调整、测试结果如何”。4.3 我的调试流程与效果优化心得最后分享一下我的完整调试流程这是从多个项目中总结出来的。第一轮是“玩具测试”。拿一个自制的简单测试项目跑一遍目的只有一个验证基本流程是否打通Agent是否真的按SKILL.md的顺序执行了。这轮不看结果准不准只看流程对不对。第二轮是“真实项目测试”。找一个真实的历史项目最好是那种知道里面有问题但还没修的老代码跑一遍重点看规则的命中率和误报率。这轮是关键通常能发现一半以上的规则问题。第三轮是“对照人工审计”。把Skill的审计结果和人工安全审计的结果逐条对比找差距。这个环节最花时间但价值最大。人工审计发现但Skill遗漏的就是规则的补充方向Skill报告了但人工认为不重要的就是规则需要调窄的地方。关于效果优化我的体会是“逐步缩小规则范围”比“一次写完美”更实际。刚写完的规则通常过宽需要在实际项目里不断“修剪”。每次跑完审计我最关心的不是发现了多少个问题而是误报和漏报各占多少比例。我给自己定的目标是P0级别的问题不允许漏报P1级别漏报率控制在10%以内整体误报率控制在30%以内。达不到这个标准就继续调规则。5. 从安全审计Skill延伸到通用技能封装做完了security-audit-skill之后我对“Skill化”这件事有了更深的理解。它不止是给安全审计用的任何一个“流程固定、重复执行、依赖经验积累”的任务都值得封装成Skill。我现在已经用同样的模式封装了另外两个技能一个是代码重构技能把“识别坏味道、拆分函数、整理模块依赖”这些流程固化下来另一个是技术方案评审技能把评审的维度架构合理性、性能风险、可维护性和打分标准做成规则文件。都是沿用同一套目录结构主文件管流程、规则文件管标准、模板管输出。这套方法的本质是把隐性经验显性化再把显性经验结构化。安全审计这件事资深工程师一眼能看出的问题新手可能翻半天代码也没感觉。Skill的作用就是把这“一眼”背后的判断逻辑拆解成可执行的规则让AI也能做出接近资深水平的判断。这大概也是为什么现在社区里Skill这么火从codex skill到opencode skill大家都在做同一件事把不可言说的经验变成可复制、可分发、可迭代的东西。如果你也想给自己常用的Agent加技能我的建议是先别贪大从自己最熟悉、重复最多、判定标准最明确的任务开始。用这篇里的方法搭出第一个粗糙的版本然后在真实场景里一点点打磨。坚持迭代半年你会发现自己的Skill库不知不觉就成了一个“数字分身”很多以前需要亲力亲为的重复工作现在扔给Agent就能得到靠谱的产出。就我个人来说现在跑完一次完整的安全审计从让Agent开始扫描到拿到结构化报告通常不到十分钟。同样的工作量纯靠人工大概需要大半天。省下来的时间我拿来研究新出现的漏洞类型再转化成新的规则让Skill越来越聪明。这大概就是我看到的方向人负责判断和总结AI负责执行和输出Skill就是连接两者的那座桥。
