Security Best Practices ：这个 Skill把安全左移做到了 Prompt 层

安全工具这个品类有个通病：它们都在代码写完之后才介入。SonarQube 扫一遍，Snyk 扫一遍，GitHub CodeQL 再扫一遍，每个工具都在你写完代码之后告诉你哪里有问题。问题是，等你看到报告的时候，那行有漏洞的代码已经在仓库里躺了好几天了。

OpenAI 的 Security Best Practices Skill 走了另一条路。它不扫代码，它扫你的 Prompt。准确地说，它把自己植入到 AI 编码 Agent 的决策链路里，让 Agent 在写代码的那一刻就知道什么是不安全的写法。这不是一个扫描器，这是一个安全意识的注入机制。

我第一次读它的 SKILL.md 时，觉得这思路有点过于简单了。就一个几百行的 Markdown 文件，加上一堆语言特定的参考文档，能有多大用？但仔细看完它的工作流设计之后，我意识到我搞错了问题的焦点。关键不在于它自身有多复杂，而在于它把复杂度放在了正确的位置，放在了 Agent 每一次代码生成的决策点上。

说真的，这篇文章不打算给你列一堆安全最佳实践清单。我就是想拆开这个 Skill 的设计，看看它到底怎么把一个”安全意识”塞进 AI 编码流程里，以及这种思路对 AI Skill 这个品类意味着什么。

环境准备

这个 Skill 跑在 Codex CLI 或任何兼容 Agent Skills 标准的 Agent 上。目前看 Smithery 上的兼容列表，主流 AI 编码工具基本全覆盖：

• Claude Code
• Cursor
• Windsurf
• Gemini CLI

你不用单独部署什么服务，它本质上就是一个装了参考文档的文件夹。

安装只有一行命令：

npx skills add openai/security-best-practices

或者直接去 GitHub 上把 openai/skills 仓库里的 .curated/security-best-practices 目录拖到你的 Agent skills 文件夹。两种方式本质上是一回事，都是让 Agent 在工作时能加载到这个 SKILL.md 和 references/ 下的安全参考文件。

安装完之后验证也很简单。随便在一个 Python 项目里跟 Agent 说”帮我写一个用户登录接口”，然后观察 Agent 的行为。如果它在写密码处理逻辑时主动避开了明文存储、主动用了参数化查询，那说明 Skill 已经生效了。如果它还是傻傻地写 password = request.form['password'] 然后直接存数据库，那大概率是 Skill 没加载上或者项目里没被正确识别语言栈。

最常见的卡点是 Agent 没有重新加载 skills 目录。大部分 Agent 在安装 Skill 后需要重启才能识别新技能。别像我一样装完就急着试，结果折腾了十分钟发现只是没重启。

操作流程

这个 Skill 的工作流不是线性的，它是一个决策树。Agent 接到任务后的第一步不是上来就翻安全规则，而是先搞清楚当前项目用了什么语言、什么框架。这步很容易被忽视，但实际上决定了后面所有参考文件的匹配精度。

Agent 会扫描项目里的 package.json、requirements.txt、go.mod 这类依赖声明文件，确认技术栈。然后去 Skill 的 references/ 目录里找对应的安全指南文件。文件的命名规则很直白：<语言>-<框架>-<栈>-security.md。比如你用的是 Python + Django + Web 后端，它就会去找 python-django-web-security.md。如果精确匹配不到框架级别的文件，它会降级到通用语言安全指南，比如 python-general-web-security.md。

关键的设计在这里：如果 Agent 在 references 里找不到任何匹配的安全文档，它不会直接放弃。SKILL.md 里明确写了，这时候 Agent 应该基于自己对这门语言安全实践的了解来工作，只是跟用户说一句”我这边的参考库里没有这门语言的专项指南，我只能基于通用知识来做”。这个 fallback 设计很聪明，既诚实地告知了信息精度可能下降，又没有让整个流程断掉。

从识别完技术栈之后，Skill 进入三种工作模式之一。

默认是”安全默认模式”，Agent 从这一刻开始写的每一行代码都自动对齐安全最佳实践。

第二种是”被动检测模式”，Agent 在正常写代码的过程中，如果发现了严重的安全问题就主动提醒用户。

第三种是”全量审查模式”，用户明确要求做安全审查时，Agent 会生成一份结构化的安全报告并写入文件。

关键设计

这个 Skill 最聪明的设计不是它的安全规则有多全，而是它把”override”这个概念当成了核心功能。SKILL.md 专门有一段讲：客户可能有需要绕过安全实践的情况，Agent 不应该跟用户较劲，而是建议用户把为什么要绕过这条规则写进项目文档。

这事说起来小，但在 AI Agent 的语境下是个大问题。大多数 AI 安全工具的设计哲学是”安全第一，其他靠边”，用户想跳过某个检查要么做不到，要么得绕一大圈。Security Best Practices Skill 的选择是：我知道什么是对的，但我更知道现实项目里可能有合理的理由不走”对”的路。把决策权还给用户，同时要求用户留下记录。这种设计透着一股子工程务实主义，不像是一个安全团队拍脑袋想出来的方案。

参考文件的组织方式也值得说说。它不是一个大而全的安全知识库，而是按语言、框架、部署栈三个维度做了交叉索引。Python + Django + Web 有一套指南，Python + FastAPI + Web 有另一套。这种细粒度意味着每个参考文件都很短，Agent 加载时不会因为上下文太长而丢失注意力。同时，文件命名本身就是路由规则，Agent 不需要额外的配置就能匹配到正确的那份。

三种工作模式的分层也体现了一种”渐进式安全”的思路。默认模式不打扰用户，Agent 安安静静地写安全代码。被动模式只在大事上提醒，不拿小问题烦人。全量审查模式是用户主动触发时才启动的重武器。这三种模式对应的其实是三个不同阶段的安全需求：开发期、提交前、上线前。一个 Skill 覆盖了整个 SDLC 的安全节点，而且用的都是同一套知识库。

不过有个地方我觉得可以做得更好。目前它只覆盖了三门语言：Python、JavaScript 和 Go。这就漏掉了 Rust 这种在安全敏感场景下越来越主流的选择，更不用说 Java 和 C# 在企业级应用里的体量了。Agent 当然可以靠通用知识兜底，但参考文件的精度和一致性优势就没了。

使用场景

最能体现这个 Skill 价值的场景是新项目启动。你准备用 FastAPI 搭一个后端服务，Agent 开始帮你写第一个 API 端点。正常情况下，AI 生成的代码在好几个关键点上容易翻车：参数校验不到位，SQL 查询没做注入防护，密钥直接硬编码。但 Skill 介入后就不一样了。生成的代码从第一行就带上了安全基线，参数化查询是默认的，输入自动清洗，密钥从环境变量读取。这些最佳实践变成了不需要刻意提醒的肌肉记忆。

这个差异不是”更好”，是”从源头就不一样”。传统的安全扫描是在你写了 500 行代码之后告诉你第 37 行和第 208 行有问题，然后你得翻回去改。Skill 的方案是你根本不会写出第 37 行和第 208 行那种有问题代码。这个效率差距在项目规模上去之后会被放大得很夸张。

另一个容易被忽视的场景是遗留代码维护。你接手一个三年前的 Django 项目，里面可能有几十处不安全的写法，但你不可能一次性停下来做全面安全审查。这时候用被动检测模式，Agent 在帮你修 bug、加功能的过程中，顺带把路过的不安全代码标记出来。你不会被打断，但你会知道哪些地方需要关注。积累到一定数量后，跑一次全量审查，一次性修掉。

反过来说，这个 Skill 不适合的场景也很明确。如果你的团队已经有完整的 SAST 管线，CI 里跑着 CodeQL 和 Snyk，那这个 Skill 的增量价值更多体现在开发体验层面，而不是安全覆盖层面。它不是来替代现有安全工具的，是来填补”写代码”和”扫描代码”之间的空白的。

洞察与反思

看完这个 Skill 的设计之后，我最大的感受不是它有多强，而是它终于搞清楚了一个 AI Skill 应该长什么样。不是把一堆指令和规则塞进一个 Markdown 文件，而是设计一个让 Agent 能动态加载上下文、根据场景做决策的轻量级运行环境。参考文件按需加载，决策树在 SKILL.md 里用自然语言描述，fallback 逻辑有明确出口。这比大多数”把 Prompt 写长一点”的 Skill 高了一个维度。

另一个让我想得比较多的地方是，安全知识被”文档化”之后的维护成本。三门语言，每门语言下面可能有三四个框架，每个框架可能有两三种部署栈。算下来就是几十个参考文件。这些文件谁来维护？OpenAI 维护的话，更新频率能跟上框架的迭代吗？社区维护的话，质量怎么保证？这个问题目前在 install 量只有 37 的规模下不是问题，但如果这个 Skill 的装机量涨到几千，参考文件的覆盖面和时效性就会变成核心瓶颈。

但反过来讲，也许这正是”Skill 作为轻量级分发格式”的优势。你不用等某个安全厂商把对新框架的支持做成产品功能，你只需要有人写一个几十行的参考文件，放到这个 Skill 的 references 目录里，就能让所有用这个 Skill 的 Agent 获得新的安全知识。知识的生产和分发被解耦了，这是开源软件世界的逻辑，不是 SaaS 产品的逻辑。

我个人觉得，Security Best Practices Skill 真正的价值不在于它现在覆盖了多少安全规则，而在于它证明了一种模式可行：把领域知识结构化成 Agent 可消费的参考文件，然后用一个轻量级的决策引擎串联起来。这个模式不只是对安全有效，对任何需要”在编码时注入专业判断”的领域都有效。性能优化、可访问性、合规检查，这些东西都可以用同一套范式来做。

资源地址

总结

Security Best Practices Skill 解决了一个被大多数安全工具忽视的问题：安全建议到达开发者手里的时机。传统的安全工具在”事后”工作，这个 Skill 在”事中”工作。它不生成扫描报告，它生成更安全的代码。

适合谁用？如果你在用一个支持 Agent Skills 的 AI 编码工具，写 Python、JS 或 Go，而且团队里没有强制跑 SAST 的 CI 管线，这个 Skill 的投入产出比很高。一条命令安装，零配置，不需要额外服务。如果你已经有完整的 DevSecOps 流程，它的价值更多在于减少”扫描-修复”循环的次数，让你的开发体验少一些被打断的时刻。

往大了说，这个 Skill 代表的方向比它自身更有意思。AI 编码 Agent 正在从”能写代码”进化到”会写代码”，而”会写”的定义里，安全、性能、可维护性这类专业判断正在从”人教 Agent”变成”Skill 教 Agent”。Security Best Practices 只是先跑了一步，后面会有一批类似的 Skill 跟上来。