最近在整理自己的AI编程工作流时我把一个反复用了很久的security-audit-skill正式沉淀成了独立模块不再靠每次临时复制粘贴一段提示词来碰运气。这个过程让我意识到安全审计这份工作天然适合被做成Skill它有固定的检查项、有相对稳定的判断标准、也有标准化的报告输出要求。如果只是随口问大模型“帮我看看这段代码有没有问题”每次得到的结论深浅不一、格式混乱、严重性判断也飘忽不定。但把这些检查标准固化成security-audit-skill之后AI编程助手就像换了一个有安全审查经验的人拿到代码会按同样的流程走完检查然后给出结构一致的结论。这篇文章就围绕我实际搭建和使用安全审计Skill的完整过程来写包括边界设计、目录结构、规则编写、Agent接入方式和真实调优记录。适合正在使用Codex、Claude Code、OpenCode这类AI编程工具又想给代码库加一道自动化安全检查的开发者也适合想搞清楚Skill和普通提示词、和Agent到底有什么区别的读者。1. 为什么我不再用临时提示词做代码安全审计1.1 安全审计的“标准动作”非常适合被固化代码安全审计和一般代码评审不太一样。普通代码评审关注的可读性、性能、架构不同项目标准差异很大但安全审计里最常查的那批问题其实高度标准化比如SQL注入、硬编码密码、路径穿越、反序列化风险、敏感信息泄露。这些问题在一些安全指南和漏洞库里有相对明确的模式一个经验丰富的工程师不会因为项目是Java还是Python就改变对“密码不能写死在代码里”的判断。既然判断标准稳定那就说明这部分经验可以被固化成一套可复用的工作流。我最早的做法是把一长串安全检查要求写进系统提示词里每次要审计时复制粘贴进去。问题是提示词一长模型容易在中间部分丢失注意力前面强调了SQL注入后面查硬编码凭据时就漏了而且每次调整某条规则旧的会话里还留着上一版逻辑结果自己都搞不清当前用的是哪套标准。所以我把检查项、严重级定义、输出格式全部拆到独立的skill目录里用一套固定的机制去加载。这样每次调用security-audit-skill时模型拿到的审计标准始终是最新版本不依赖我这次怎么组织语言。这正是Skill存在的价值把容易碎片化的专家知识变成可版本管理、可复用、可修改的模块。1.2 Skill、Agent和普通提示词的本质区别很多人在热词里搜“skill和agent的区别”这个话题确实容易绕晕。我用一个类比来说清楚Agent像一个执行者它拥有推理能力、工具调用权限和完成任务的目标循环而Skill是这个执行者可以随时抽出来使用的“专业手册”加“检查清单”。Agent决定什么时候用Skill、怎么编排多个SkillSkill本身不决策它只负责在某个特定任务里告诉Agent应该按什么标准做什么事。普通提示词和Skill最大的区别在于组织方式。提示词是一次性对话里的临时指令Skill则是一组有结构、有示例、有静态检查规则的目录集合。Skill能在Agent被唤醒时自动加载到上下文里并且在多次对话之间保持一致的执行逻辑。这样安全审计这个任务就可以被标准化成“每次都能重复执行”的能力而不是依赖运气。我自己体会最明显的一点是临时提示词适合“问一下”比如“这段代码有没有问题”Skill适合“跑一个流程”比如“把整个services目录扫一遍按标准输出报告”。security-audit-skill属于后者它目标明确不需要Agent去猜测该用什么标准。1.3 security-audit-skill的设计目标我对这个Skill的设计目标只有一句话让AI助手像初级安全审计员一样按固定检查单逐项扫描代码并输出可执行的修复建议。初级安全审计员的特点是守规矩但经验不够这恰好是语言模型擅长的场景——只要规则清晰、示例充分它能稳定执行而高级安全审计员的经验判断则需要靠规则库的持续迭代来弥补。所以在设计时我不追求让这个Skill覆盖所有安全领域而是先保证中高风险问题能被稳定识别、误报率可控、输出报告合格。后面所有的目录结构和规则文件都围绕这三个目标展开宁可漏报也不要满屏废话。2. security-audit-skill的扫描范围与输出规范2.1 我圈定的审计范围清单Skill的第一件事是明确自己审什么。我把扫描范围限定在静态源码检查API接口输入校验、SQL与命令拼接、文件路径处理、反序列化入口、硬编码凭证、加密算法使用、日志中的敏感数据、越权相关的直接对象引用。这八类问题在多数Web项目和微服务代码里最常见而且适合用静态方式检查。每个范围都配了更具体的问题特征描述比如“SQL拼接”不是让模型去理解业务逻辑而是找字符串拼接进数据库查询的地方“硬编码凭证”包括明文密码、AccessKey、Token、私钥、连接字符串等。范围越具体模型越清楚自己该找什么不会把时间浪费在架构层面的讨论上。2.2 明确不做的事反而更重要任何Skill都得有自己的边界security-audit-skill也一样。我在规则文件开头就写明它不负责动态运行时测试不做渗透测试不做依赖版本漏洞库比对也不做容器和云基础设施的配置审计。这个边界很重要。如果不写清楚模型很容易在审计过程中突然跑去分析Dockerfile、K8s配置或者云权限策略结果看起来内容很全实际每一块都不深入。把不做的事讲明白以后模型会把全部注意力放在源码层的漏洞模式上输出质量明显提升。2.3 输出格式带严重级和证据链的报告我要求Skill的输出严格遵循固定结构。每一条发现必须包含问题文件与行号、问题类型标签、严重级Critical、High、Medium、Low、证据片段、问题解释、修复建议。其中“证据片段”最关键它要求模型先引用原始代码然后再下结论避免空口说“存在风险”。严重级的判断规则也在Skill里写死可被外部输入直接触发的注入类问题标记为Critical写死在源码里的云端密钥标记为High使用弱哈希算法、过时加密库之类标记为Medium日志里打印敏感个人信息标记为Low。这样报告出来以后我和团队同事不需要再逐条讨论等级直接按Critical到Low的顺序排期修复就行。3. 目录结构与SKILL.md落地细节3.1 一套兼容多个编程Agent的目录布局security-audit-skill的目录结构我是这样设计的security-audit-skill/ ├── SKILL.md ├── rules/ │ ├── injection.md │ ├── credentials.md │ ├── path-traversal.md │ ├── deserialization.md │ └── crypto-guidelines.md ├── examples/ │ ├── sql-injection-good.py │ ├── sql-injection-bad.py │ ├── hardcoded-secret-good.py │ ├── hardcoded-secret-bad.py │ └── ... ├── templates/ │ └── audit-report-template.md └── checklist.md这个结构参考了当前主流AI编程助手对Skill的通用约定目录下至少有一个SKILL.md作为入口模型会优先读取这个文件来确定当前任务的工作流程。rules目录放审计规则examples目录放正反例代码templates目录放报告模板checklist.md放快速检查单方便模型在长任务中复核。这样的布局放在Codex的~/.codex/skills/下或者Claude Code的.claude/skills/下都能被识别。OpenCode这类工具也支持类似的自定义指令目录适配成本很低。3.2 编写SKILL.md时的关键结构SKILL.md是整个Skill的灵魂我推荐用YAML frontmatter开头接着写工作流程。frontmatter里至少要包含name和descriptiondescription尤其重要它决定了Agent在什么时机自动唤起这个Skill。我写的description是“Perform a static security audit on source code, identify vulnerabilities, and output a structured report”。正文部分我按下述顺序组织角色设定你是一名有5年应用安全经验的代码审计员输入要求需要被审计的代码路径、语言类型、关注范围执行流程先读取checklist再遍历目标代码逐项检查rules目录中的规则最后用templates中的模板生成报告输出要求严格遵守报告格式和严重级定义禁止事项不修改源码、不执行代码、不讨论无关话题执行流程写清楚以后模型不会拿到代码就立刻开始判断而是先按流程加载规则和示例再扫描代码。这个“先加载后分析”的顺序很关键否则规则和示例文件就失去了被参考的机会。3.3 配套的审计规则文件与样例库rules目录下的每个文件对应一类漏洞主题。以injection.md为例我会写清楚该查什么语言里的哪些高危API比如Python里要注意eval、exec、os.system、subprocess、字符串拼接的SQL查询Java里要注意Runtime.exec、Statement.execute等等。examples目录提供正反例。反例要足够直白让人一眼看出问题正例要展示安全的替代写法。示例不用追求覆盖所有边界情况目的是给模型提供“像与不像”的参照物。实测下来正反例数量不需要多每类两三组就足够让模型掌握判断标准。checklist.md则是给模型的最后一道保险。它是一份极简清单比如“是否检查了所有用户输入入口”“是否搜索了密钥赋值模式”“是否复查了反序列化调用点”让模型提交报告前逐一比对避免遗漏。4. 内置审计规则覆盖高频漏洞但守住可解释性4.1 注入类从SQL拼接到命令执行注入类问题是我在规则文件里写得最重的一部分。以Python为例我会让模型重点查找cursor.execute(fSELECT * FROM users WHERE id {user_input})、os.system(frm -rf {filename})、subprocess.call(command, shellTrue)这类模式。关键不是让模型背API而是理解“外部输入未经过滤或参数化直接进入解释器”这个本质。我在规则里会要求模型判断三个要素数据是否来自外部输入、是否有过滤或校验、最终是否到达了危险函数。只有三个条件同时满足才标记为Critical注入风险。这样做能显著减少误报比如配置文件中写死的常量SQL不会因为包含拼接字符串就被误判。4.2 硬编码凭据与密钥文件的识别硬编码凭据的识别要点在于“看起来像密钥”。规则文件里明确列了一组匹配模式password、passwd、api_key、access_key、secret、token等关键词后面直接跟上字符串字面量Base64解码后仍然像密钥的字符串长度超过32位的随机字符串存有私钥内容的变量。要注意的是正则匹配容易误报所以我会要求模型区分“测试环境默认密码”和“生产环境真实密钥”区分“环境变量读取代码”和“直接写死的字面量”。规则文件里写了判断逻辑如果代码里有从环境变量读取的逻辑则不标记为High如果密钥直接出现在源码里并且被外部服务引用才标记为High或Critical。4.3 路径穿越、反序列化与不安全的文件操作路径穿越主要是查用户可控参数是否直接拼接进文件路径比如open(os.path.join(UPLOAD_DIR, filename), wb)里的filename如果来自HTTP请求就可能越权读写文件。规则里强调要先看是否用了os.path.abspath后做前缀校验如果没有就需要标记Medium以上。反序列化更复杂。Python里shelve、pickle、yaml.unsafe_load都存在风险Java里ObjectInputStream.readObject结合resolveClass时若没做白名单也要标记。为了让模型不误报我在规则文件里写明了“不要因为看到pickle就把所有代码都标成Critical要确认数据源是否可控”。4.4 为什么每条规则都要配正反例这是我在调优中体会最深的一点。只写“注意SQL注入”没有任何用模型对这句话的理解会和你的期望有偏差。一旦配了正反例模型就能把抽象的规则映射到具体代码形态上。举个例子规则里配一对Python代码# bad直接拼接用户输入 query SELECT * FROM users WHERE email request.args.get(email) cursor.execute(query) # good使用参数化查询 cursor.execute(SELECT * FROM users WHERE email %s, (request.args.get(email),))模型看到bad版会在扫描时关注同类拼接模式看到good版会对“正确的写法应该长什么样”有直观认知。这比让它从原理层面推导靠谱得多也明显减少了把安全写法误判为风险的概率。5. 接入主流编程Agent与自动化流水线5.1 按平台放置SkillCodex、Claude Code、OpenCode通用思路接入方式本质上就是让Agent知道哪里能找到这个Skill。Codex用户把security-audit-skill目录放到~/.codex/skills/security-audit-skill/下Claude Code用户放到项目根目录.claude/skills/security-audit-skill/或用户级目录OpenCode用户放到.opencode/skills/下。大体框架一致具体路径以各工具文档为准。放置完成后还需要在AGENTS.md或项目的agent配置里加一句说明当执行安全审计、代码漏洞扫描、安全评审类任务时必须加载security-audit-skill。这句话是触发机制的关键没有它Agent即使能在目录里找到Skill也不会在合适场景主动使用。5.2 与静态扫描工具的互补当模型遇上Semgrep我在实际使用中并没有让security-audit-skill完全替代Semgrep、gosec这类传统静态扫描工具而是让它们配合着做两道关卡。Semgrep的反应快、规则精确、误报相对可预测模型的语义理解能力更强能在复杂上下文里发现跨函数的数据流问题。具体配合方式是先跑Semgrep拿到一批传统规则命中再让security-audit-skill对告警做一次分流——哪些是真正需要人工排查的哪些是测试代码或误报同时让它补充Semgrep难以发现的逻辑性问题。Skill在报告里会引用Semgrep的结果并做出解释这比我人工逐条看省了非常多时间。5.3 控制成本和上下文的几条铁律AI编程助手的上下文窗口不是无限的调用时越长的代码、越多的规则token消费越高。我在实践里总结了几条铁律单次审计的文件控制在30个以内按目录分批跑不要一个会话里塞进整个大仓库rules目录中的规则默认全部加载没问题但examples里只保留最常见的两组正反例不要堆太多示例报告模板固定避免模型重复列出大段解释。另外我要求Skill在审计大文件时先输出文件清单和处理顺序确认后再逐文件分析。这个步骤看似多余实际能避免模型在一个会话里因为上下文过长而中途“忘记”前面的规则也方便我在它跑偏时及时中断。6. 真实用例里踩过的坑和调优记录6.1 第一次实测时输出得很“全面”但毫无重点我第一版security-audit-skill跑在项目上输出了一份看起来很“全面”的报告列了二十几条发现覆盖SQL注入、日志泄露、依赖版本……但仔细看全是废话。“此处使用了请求参数建议进行校验”这种结论说了等于没说没有指明究竟是哪一行代码有问题也没有给出可执行的修复建议。问题出在规则文件里缺少“证据链”要求。模型习惯了直接给结论如果没有强制约束它不会主动引用具体代码。于是我在SKILL.md中增加了一条硬性规定每条发现必须先引用证据片段再写解释和修复建议没有证据引用的内容一律不算有效发现。改完之后输出质量立刻提升了一大截。6.2 误报率怎么降下来的第二版的问题是误报太多。最典型的是把普通字典里名为password的键当成硬编码凭据报了出来还有把subprocess.run只要使用了shellTrue就一律标Critical没考虑输入其实是配置文件中不可变常量。为了让误报降下来我在规则文件里加入了“污染源判定”概念先确认数据是否来自request、用户输入、外部API、文件上传等源头如果来源不可信再往下追如果来自常量或配置文件则最多标记Low或直接忽略。另外我要求模型在报告里给每个发现标注置信度低置信度的单列一档不进入主要问题清单。现在误报率大概下降了六成剩下的误报大多集中在模型对业务逻辑的误解上只能靠白名单机制处理。6.3 忽略清单与持续迭代任何一个代码审计工具都需要维护忽略清单。我在Skill里增加了一个exceptions.md用来记录经过人工复核确认不构成风险的代码位置和理由。模型加载Skill时会同步读取这个文件在扫描时自动跳过这些位置。忽略清单不是简单的固定名单我还会记录当时放过的原因比如“此处的用户输入已在上游进行严格校验”“该Service是内部调用不对外暴露”。这样下次模型在做类似判断时就有了参照不再因为同一个原因反复误报。这个机制本质上是在把人工评审的经验逐步沉淀回Skill里用得越久模型越贴合自己项目的实际情况。7. 自己编写审计Skill时最容易被忽略的四件事7.1 规则要窄而准不要贪大求全一开始我尝试让Skill同时覆盖OWASP Top 10、CWE TOP 25、供应链安全、容器安全等所有内容结果模型根本忙不过来输出质量很差。后来我砍掉大部分范围只保留最核心的八类源码审计问题效果反而明显改善。安全审计Skill不需要装下整个安全知识体系它只需要在你的项目和Agent之间搭建一条标准、可重复执行的规定动作流水线覆盖面可以后续逐步扩。7.2 强调“我先看证据再下结论”反复训练模型引用代码模型在宽松指令下会倾向于“概况式”回答所以我后来在规则描述里反复使用这样的表述在报告每个发现之前先摘录触发该结论的代码块包括文件名和行号如果无法定位到具体代码位置则不要报告该发现。这样一方面提高了结论的可验证性也让修复的人能直接跳到代码位置不用自己再找一遍。这是我做这个Skill后收获最大的一条经验。7.3 修复建议必须能落到具体代码上不少模型审完代码会给出“请加强输入校验”这种泛泛建议。我在Skill里加了约束修复建议必须是一个可操作的代码示例或伪代码。如果模型给出的是建议它需要同时给出修改后的代码片段。这样团队成员拿到报告可以直接进行代码变更不用再想办法“翻译”结论。这个约束也减少了模型输出正确但没用的话。7.4 版本管理与定期更新Skill本身也是代码也需要版本管理。我把它放进Git仓库每次规则调整都单独提交记录原因。项目里如果有真实的线上安全问题也会在复盘后把相关特征补充进规则文件。这样security-audit-skill就不再是一个一次性做出来的工具而是跟着项目安全水位一起进化的能力。当我更新规则后跑一次历史项目还能顺便验证新规则的有效性避免改了输出格式把旧功能弄坏。就我目前的实践来看把安全审计做成Skill最大的价值不是让AI变得更聪明而是让每一次审计都站在同一条起跑线上、执行同一个标准。它把过去依赖个人经验的“偶然安全”变成了可以被复制和改善的“固定流程”。如果你也在用AI编程助手做代码评审我建议你先别急着堆功能先把你最常做的那类安全检查整理成一个最简Skill跑起来跑顺了再慢慢加规则。