30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度很多开发者安装完 Codex 后面对强大的 AI 助手却感觉无从下手只会问一些基础问题无法将其真正融入日常开发工作流。这通常不是 Codex 本身能力不足而是没有掌握其核心的“技能”Skills系统。Skills 是 Codex 从“聊天机器人”进化为“自动化工作流伙伴”的关键。本文将带你从零开始彻底吃透 Codex Skills让你能在 20 分钟内构建出属于自己的、可复用的智能体技能实现代码审查、自动化部署、文档生成等复杂任务的自动化。无论你是刚接触 Codex 的新手还是已经使用过但感觉效率不高的开发者本文都将提供一套从概念理解、环境配置、技能创建到实战部署的完整闭环方案。你将学会如何将零散的、重复性的开发任务封装成稳定的、可一键触发的智能体技能从而极大提升个人与团队的研发效能。1. Codex Skills 核心概念从“聊天”到“工作流”在深入实操之前我们必须先理解 Codex Skills 到底是什么以及它解决了什么问题。这有助于我们建立正确的使用心智模型。1.1 什么是智能体技能Skills简单来说Skills 是给 Codex 注入的“任务级能力包”。你可以把它理解为一个高度定制化的“操作手册”或“工作流模板”。传统聊天模式你向 Codex 描述一个复杂任务如“帮我审查这段代码的安全性”Codex 每次都需要从头理解你的意图、上下文和期望的输出格式。结果可能不稳定每次的审查深度和侧重点都可能不同。技能驱动模式你提前创建一个“代码安全审查”技能。这个技能里明确定义了当用户需要代码审查时应该按什么步骤分析如先检查依赖漏洞、再扫描硬编码密钥、最后评估 SQL 注入风险、参考哪些安全规范、以及最终报告的输出格式。当 Codex 启用这个技能后它就会稳定地遵循这套既定流程执行任务输出高质量且一致的结果。一个完整的 Skill 通常包含以下几个部分指令SKILL.md核心文件用自然语言详细描述技能的目标、触发条件、执行步骤和预期输出。参考资料references/可选的辅助文档如公司编码规范、API 文档、架构图等供 Codex 在执行时查阅。脚本scripts/可选的、可执行的脚本文件如 Python、Shell用于处理那些需要确定性结果或与外部系统交互的环节。资源assets/可选的模板、图片等静态资源。1.2 Skills 与插件Plugins的区别这是两个容易混淆但层级不同的概念技能Skills是“可复用工作流”的创作格式。它关注的是任务本身的逻辑和指令是内容层。你首先应该设计的是技能。插件Plugins是“可安装分发单元”的打包格式。它关注的是如何将一个或多个技能连同其配置、界面元数据等打包成一个便于分发和安装的包。当你需要将技能分享给团队或集成到应用中时才需要将其打包为插件。简单理解先有技能内容后有插件包装。本文主要聚焦于技能的创建与使用这是发挥 Codex 潜力的第一步。1.3 Skills 如何工作“按需展开”的上下文管理Codex 采用了一种高效的“按需展开”机制来管理技能这对性能和使用体验至关重要启动扫描Codex 启动时会从多个预定路径后文详述扫描所有技能目录。但它只读取每个技能SKILL.md文件中的name名称和description描述这两个元数据字段。这个过程非常轻量。构建技能列表Codex 会将扫描到的技能名称和描述摘要组成一个初始技能列表并将其放入模型的上下文窗口中。为了避免占用过多上下文资源这个列表的大小被限制在模型上下文窗口的 2%或最多 8000 个字符。如果技能太多Codex 会智能地缩短描述。隐式/显式调用隐式调用当你提出一个任务请求如“生成这个数据表的 CRUD API”时Codex 会根据初始技能列表中的description字段自动判断是否有匹配的技能可以辅助完成此任务。如果匹配则动态加载该技能完整的SKILL.md指令到上下文中并据此执行。显式调用你可以在对话中直接使用$skill-name的语法例如$code-review来强制调用某个特定技能。执行Codex 加载完整技能指令后就会像一位严格遵循手册的专家一样逐步执行技能中定义的工作流。这种机制保证了 Codex 在拥有大量技能时也能快速启动并且只在需要时才消耗详细的上下文资源。2. 环境准备与技能目录结构在创建第一个技能前我们需要明确 Codex 的运行环境以及技能文件的存放位置。2.1 确认 Codex 运行环境本文假设你已在本地安装了 Codex 的 CLI、IDE 扩展如 VS Code或桌面 App 中的至少一种。你可以通过以下命令验证 CLI 是否可用codex --version如果正常输出版本号说明环境就绪。Skills 功能在 Codex CLI、IDE 扩展和 App 中均受支持核心逻辑一致。2.2 理解技能文件的存放位置Codex 会从四个层级的目录中扫描技能优先级和作用范围不同技能范围默认路径示例推荐用途REPO (仓库)./.agents/skills/最常用。当前项目或仓库特有的技能如项目特定的构建脚本、部署流程。../.agents/skills/在 Git 子目录中工作时使用父目录的共享技能。$REPO_ROOT/.agents/skills/整个 Git 仓库共享的团队技能如统一的代码规范检查、提交信息模板。USER (用户)$HOME/.agents/skills/用户全局技能在任何项目下都可用。适合个人通用工具如日记总结、会议纪要生成。ADMIN (系统)/etc/codex/skills/系统管理员为所有用户部署的技能如公司级安全扫描、内部工具链集成。SYSTEM (内置)Codex 安装包内置OpenAI 官方提供的基础技能如skill-creator技能创建器。最佳实践建议从REPO范围开始将你的第一个技能放在当前项目的.agents/skills/目录下。这是最直接、隔离性最好的方式。创建目录如果项目根目录下没有.agents文件夹请手动创建它。# 在你的项目根目录下执行 mkdir -p .agents/skills这个目录将成为我们所有技能的家。3. 创建你的第一个技能实战“代码审查”理论铺垫完毕现在我们动手创建一个实实在在的技能。我们以一个常见的“Python 代码安全与风格审查”技能为例。3.1 技能规划明确目标与边界在写代码之前先规划技能名称namepython-code-review技能描述description这是隐式调用的关键必须清晰说明何时触发、何时不触发。触发当用户请求审查 Python 代码、检查代码问题、寻找 bug 或优化建议时。不触发当用户请求编写新代码、解释概念或处理非 Python 代码时。技能指令按步骤描述审查流程包括检查项安全性、性能、风格、参考规范PEP 8、输出格式。3.2 手动创建技能目录与文件按照规划创建技能的文件结构# 进入项目技能目录 cd /path/to/your/project/.agents/skills # 创建技能专属目录 mkdir python-code-review cd python-code-review # 创建核心指令文件 touch SKILL.md # 可选创建其他目录 mkdir -p references assets现在用你喜欢的文本编辑器打开SKILL.md文件开始编写技能的核心内容。3.3 编写核心指令文件 SKILL.mdSKILL.md是一个 Markdown 文件其开头必须包含 YAML Front Matter 来定义元数据name和description之后是详细的技能指令。--- name: python-code-review description: | 对用户提供的 Python 代码进行安全和代码风格审查。 当用户要求审查代码、查找 bug、优化代码或检查安全隐患时触发。 不适用于编写新代码或解释通用编程概念。 --- # Python 代码审查技能 ## 目标 为用户提供的 Python 代码片段或文件提供全面的自动化审查聚焦于安全性、常见错误、代码风格和性能隐患。 ## 审查流程 请严格按照以下步骤执行审查 1. **理解代码**首先总结用户提供的代码的核心功能。 2. **安全检查** * **注入攻击**检查是否存在 SQL 注入字符串拼接、命令注入os.system, subprocess 使用不当、模板注入等。 * **敏感信息**检查是否有硬编码的密码、API 密钥、令牌等。建议使用环境变量或安全配置管理。 * **反序列化**检查是否使用了 pickle、yaml.load 等不安全的反序列化方法。 * **输入验证**检查用户输入是否经过适当的验证和清理如类型检查、范围限制、转义。 3. **代码风格与最佳实践**参考 PEP 8 * **命名**变量、函数、类名是否符合蛇形命名法snake_case或驼峰命名法CapWords * **导入**导入是否在文件顶部是否按标准库、第三方库、本地库分组 * **缩进与空格**是否使用 4 个空格缩进运算符周围是否有空格 * **行长度**每行是否尽量不超过 79 个字符 * **异常处理**是否使用了过于宽泛的 except:是否记录了有用的异常信息 4. **常见错误与性能** * **可变默认参数**函数定义中是否使用了可变对象如 def func(a, b[])作为默认参数 * **循环与迭代**是否有可以转化为列表推导式或生成器表达式的简单循环 * **资源管理**文件、网络连接等资源使用后是否确保被正确关闭建议使用 with 语句 5. **提供建议** * 对发现的每个问题**明确指出代码位置**如行号。 * 解释该问题可能导致的风险或不良影响。 * 提供具体的、可操作的修改建议或代码示例。 ## 输出格式 请将审查结果组织成以下结构 ### 代码摘要 [简要描述代码功能] ### 安全问题 - **[问题级别高/中/低]** [问题描述] - **位置**[文件:行号] - **风险**[潜在风险说明] - **建议**[修改建议或代码片段] ### 代码风格与最佳实践问题 - **[问题类型]** [问题描述] - **位置**[文件:行号] - **建议**[修改建议可引用 PEP 8] ### 性能与潜在错误 - **[问题类型]** [问题描述] - **位置**[文件:行号] - **建议**[优化建议] ### 总结与总体建议 [总体评价并给出最重要的 1-3 条改进建议。]关键点解析---之间是 YAML 元数据name和description必须存在。description是隐式匹配的关键务必准确。使用|可以保留多行格式。指令部分使用清晰的标题和编号列表让 Codex 易于遵循。指令中明确了输入用户提供的代码、处理过程分步骤审查和输出结构化报告。3.4 测试你的技能保存SKILL.md后Codex 会自动检测到新技能。如果未立即生效重启你的 Codex 客户端如重启 VS Code 或重新打开 Codex App。测试方式 1隐式调用在 Codex 聊天框中输入请帮我审查下面这段 Python 代码 python import sqlite3 import os def get_user_input(): user_id input(Enter your user ID: ) return user_id def fetch_user_data(user_id): conn sqlite3.connect(database.db) cursor conn.cursor() # 警告存在 SQL 注入风险 query fSELECT * FROM users WHERE id {user_id} cursor.execute(query) data cursor.fetchall() conn.close() return data if __name__ __main__: uid get_user_input() print(fetch_user_data(uid))Codex 识别到你的请求与 python-code-review 技能的 description 匹配便会自动加载该技能并执行输出结构化的审查报告。 **测试方式 2显式调用** 你也可以直接调用技能$python-code-review 请审查上述代码。这能确保 Codex 使用指定的技能不受其他技能干扰。 ## 4. 技能进阶使用脚本、参考资料与元数据 基础技能已经能解决很多问题但要让技能更强大、更易用我们需要了解更多高级特性。 ### 4.1 集成可执行脚本scripts/ 当技能中的某些步骤需要**确定性执行**或**调用外部工具**时就需要用到脚本。例如在代码审查技能中我们想自动运行 pylint 或 bandit安全扫描工具并解析结果。 1. **创建脚本目录和文件** bash cd /path/to/your/project/.agents/skills/python-code-review mkdir -p scripts touch scripts/run_bandit.py 2. **编写脚本** (scripts/run_bandit.py) python #!/usr/bin/env python3 使用 bandit 对指定 Python 文件进行安全扫描的辅助脚本。 供 Codex 技能调用。 import subprocess import sys import json import tempfile import os def scan_code_with_bandit(code_snippet: str) - dict: 将代码片段写入临时文件并用 bandit 扫描。 返回解析后的结果字典。 # 创建临时文件 with tempfile.NamedTemporaryFile(modew, suffix.py, deleteFalse) as f: f.write(code_snippet) temp_file_path f.name try: # 运行 bandit输出 JSON 格式 # 确保 bandit 已安装: pip install bandit result subprocess.run( [bandit, -f, json, -q, temp_file_path], capture_outputTrue, textTrue, timeout30 # 设置超时 ) if result.returncode 0: # 尝试解析 JSON 输出 try: return json.loads(result.stdout) except json.JSONDecodeError: return {error: Failed to parse bandit output, raw: result.stdout} else: return {error: fBandit scan failed: {result.stderr}} except subprocess.TimeoutExpired: return {error: Bandit scan timed out.} except FileNotFoundError: return {error: Bandit is not installed. Please install it via pip install bandit.} finally: # 清理临时文件 os.unlink(temp_file_path) if __name__ __main__: # 简单测试从标准输入读取代码 if not sys.stdin.isatty(): code sys.stdin.read() report scan_code_with_bandit(code) print(json.dumps(report, indent2)) else: print(json.dumps({error: No code provided via stdin.}, indent2)) 3. **在 SKILL.md 中调用脚本** 你可以在技能指令中告诉 Codex 去执行这个脚本并处理其结果。 markdown ## 审查流程 ... 2. **安全检查** * **自动化工具扫描**使用内置的 run_bandit.py 脚本对代码进行初步安全扫描。 bash # Codex请执行以下命令并将代码作为标准输入传入 python3 scripts/run_bandit.py EOF [用户提供的代码将在这里] EOF * 分析脚本返回的 JSON 结果将 high 和 medium 严重级别的问题列入报告。 ... Codex 可以理解并执行这种在指令中嵌入的 shell 命令从而将外部工具的结果整合到审查流程中。 ### 4.2 添加参考资料references/ 参考资料是技能的知识库。例如你可以将公司的《Python 安全开发规范》或《PEP 8 中文摘要》放在这里供 Codex 在审查时参考。 1. **添加参考文件** bash cd /path/to/your/project/.agents/skills/python-code-review echo # 公司安全规范禁止使用 eval() 和 exec() 处理用户输入。 references/security_guidelines.md echo # PEP 8 要点导入应分组顺序为标准库、第三方库、本地库组间用空行分隔。 references/pep8_summary.md 2. **在 SKILL.md 中引用** markdown ## 审查流程 ... 3. **代码风格与最佳实践** * 请参考 references/pep8_summary.md 中的规范进行检查。 4. **安全检查** * 关于危险函数的使用请遵循 references/security_guidelines.md 中的规定。 ... Codex 在执行技能时会去读取这些参考文件的内容确保审查标准与你的团队规范一致。 ### 4.3 配置技能元数据agents/openai.yaml 这个文件用于增强技能在 Codex App 等图形界面中的展示和控制行为。 yaml # 文件路径python-code-review/agents/openai.yaml interface: display_name: Python 代码审查助手 # 在 UI 中显示的名称 short_description: 自动审查 Python 代码的安全漏洞、风格问题和潜在错误。 # UI 中的简短描述 icon_small: ./assets/icon-small.svg # 小图标路径可选 icon_large: ./assets/icon-large.png # 大图标路径可选 brand_color: #3B82F6 # 品牌色可选 default_prompt: 我将使用 Python 代码审查技能来帮你分析这段代码。 # 使用技能时的默认开场白可选 policy: # 是否允许隐式调用。设为 false 则只能通过 $python-code-review 显式调用。 allow_implicit_invocation: true dependencies: tools: # 声明此技能依赖的外部工具可选 - type: mcp value: pythonSecurityTools description: 用于深度安全分析的 Python 工具集 MCP 服务器 # transport 和 url 是 MCP 服务器配置示例 # transport: streamable_http # url: http://localhost:8080通过配置allow_implicit_invocation: false你可以关闭该技能的自动匹配使其成为一个仅可通过命令调用的“私有”技能。5. 技能的安装、管理与分发5.1 安装社区技能skill-installer你无需从头创建所有技能。Codex 社区有许多现成的技能。你可以使用内置的$skill-installer来安装它们。例如安装一个与 Linear项目管理工具集成的技能在 Codex 聊天框中输入$skill-installer linearCodex 会引导你完成安装过程。安装后重启 Codex 即可使用新技能。5.2 启用与停用技能你可以在不删除技能文件的情况下通过配置文件控制技能的启用状态。找到或创建用户配置文件~/.codex/config.toml(Linux/macOS) 或%USERPROFILE%\.codex\config.toml(Windows)。添加配置# ~/.codex/config.toml [[skills.config]] path /full/path/to/your/project/.agents/skills/python-code-review/SKILL.md enabled false # 将此技能禁用重启 Codex使配置生效。5.3 从技能到插件实现分发当你开发了一个优秀的技能并希望分享给团队或发布到社区时就需要将其打包为插件。插件是一个包含plugin.yaml清单文件的目录它可以打包多个技能、资源以及配置。创建插件比单个技能更复杂涉及清单编写和版本管理通常在你需要正式分发时进行。简单来说插件让你能通过codex plugins install repo-url这样的命令来一键安装技能集合。6. 最佳实践与排错指南6.1 技能设计最佳实践单一职责一个技能只做好一件事。不要创建“代码审查与部署”这种混合技能应拆分为code-review和deploy两个技能。指令优先尽量用清晰的指令在SKILL.md中描述工作流而不是依赖复杂脚本。指令更灵活易于 AI 理解和调整。描述精准description字段是你的技能能否被正确调用的生命线。用简短的句子写明触发场景和边界。例如“当用户请求生成 Dockerfile 或容器化应用时触发。不涉及 Kubernetes YAML 配置。”测试驱动用各种边缘案例的提示词测试你的技能确保它在该触发时触发不该触发时保持沉默。迭代优化根据 Codex 执行技能的实际输出不断优化SKILL.md中的指令措辞使其更明确、无歧义。6.2 常见问题与解决方案问题现象可能原因解决方案技能在列表中不显示1. 技能目录未放在正确的扫描路径。2.SKILL.md中name或description格式错误。3. Codex 未重启。1. 确认技能放在.agents/skills/或~/.agents/skills/下。2. 检查SKILL.md开头的 YAML 格式是否正确。3. 重启 Codex 客户端。技能被隐式错误调用description描述过于宽泛或与其他技能重叠。重写description明确限定触发范围增加“不适用于…”的说明。技能指令未被完全遵循指令过于复杂或存在歧义。将复杂步骤拆解使用编号列表明确每个步骤的输入和预期输出。在关键决策点提供示例。脚本执行失败1. 脚本路径错误。2. 脚本没有执行权限。3. 脚本依赖的外部工具未安装。1. 在指令中使用相对路径scripts/xxx.py。2. 为脚本添加执行权限 (chmod x)。3. 在技能描述或openai.yaml中声明依赖或让脚本包含友好的错误提示。技能冲突多个技能有相同的name。Codex 会同时列出它们。建议为技能起唯一的名字或利用不同作用域REPO/USER进行隔离。6.3 高级技巧利用 Record Replay 快速创建技能如果你有一个现成的、可演示的工作流使用Record Replay功能是创建技能原型的捷径。在 Codex 中输入/record开始录制。像平常一样通过对话和指令一步步完成你想要自动化的工作流例如从拉取代码、运行测试到生成报告。输入/stop结束录制。Codex 会分析录制的对话并自动生成一个技能草案SKILL.md。你只需要在此基础上进行微调和润色即可。这特别适合那些“只可意会不可言传”的复杂流程。通过本文的讲解你应该已经掌握了 Codex Skills 从概念到实战的核心要点。关键在于转变思维不要只把 Codex 当作问答机而是将其视为一个可以通过“技能”进行编程和定制的自动化工作流引擎。从创建一个简单的代码审查技能开始逐步将你的日常开发、测试、部署、运维任务封装起来你会发现 Codex 正从一个工具演变为你团队中一位不知疲倦、标准统一的超级助手。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度