1. 先搞清楚 Codex 和 Skills 到底能帮你做什么如果你已经装好了 Codex但感觉它除了聊天和写代码好像没比普通 AI 助手强多少那问题大概率出在Skills技能上。Codex 本身是一个强大的智能体平台而 Skills 是让它从“聊天机器人”变成“自动化工程师”的关键插件。简单来说一个 Skill 就是一个打包好的工作流指令集。它把复杂的、多步骤的任务比如“帮我分析这个代码库的依赖”、“自动生成 API 文档”、“按规范格式化提交信息”固化下来变成一个 Codex 能稳定、重复执行的“技能”。你不再需要每次都对 AI 重复描述一长串操作步骤只需要告诉它“用那个技能”它就能按既定流程走完。这解决了几个核心痛点工作流不稳定AI 自由发挥时每次的步骤和输出格式可能都不一样。操作复杂涉及多个工具、命令和判断的任务口头描述容易遗漏。知识复用难你调教好的一个复杂流程很难完整地分享给团队或下次使用。所以这篇文章不是教你怎么安装 Codex这步网上教程很多而是聚焦在“装好之后如何用 Skills 搭建可复用的自动化工作流”。无论你是想提升个人开发效率还是为团队建立标准化的 AI 辅助流程吃透 Skills 都是下一步的关键。2. 理解 Skills 的核心机制它如何被触发和执行在动手创建或安装 Skills 之前必须理解 Codex 是如何发现和使用它们的。这能帮你避免“技能装了没反应”或者“AI 乱用技能”的问题。2.1 Skills 的两种触发方式显式与隐式Codex 调用技能有两种模式理解这点至关重要显式调用你明确告诉 Codex 使用某个技能。在 CLI 或 App 中使用/skills命令然后从列表中选择。在对话中直接在提示词里写上$skill-name例如“$code-review请检查这段代码”。特点确定性高你完全掌控。适合你明确知道该用哪个技能的场景。隐式调用Codex 根据你对话的上下文自动判断并建议使用某个技能。原理Codex 会读取所有已安装技能的description描述字段与你的问题匹配。特点更智能、更流畅但依赖技能描述的准确性。如果描述写得太泛或太窄可能导致“该用时不用”或“不该用时乱用”。注意隐式匹配依赖description。所以给你的技能写描述时要把最关键的触发场景和边界放在最前面。因为当技能很多时Codex 可能会截短描述来节省上下文窗口前面的词决定了它能否被正确匹配。2.2 Skills 的加载机制“按需展开”与上下文预算这是 Codex 设计得很巧妙的一点直接影响了技能库的规模和管理。启动时Codex 不会把所有技能的完整内容都读进内存。它只读取每个技能的name、description和文件路径。这些信息被压缩成一个初始技能列表。上下文预算这个初始列表最多只占用模型上下文窗口的2%如果未知则上限为 8000 字符。如果你的技能库很大Codex 会先尝试缩短技能描述如果还超限甚至会省略部分技能并给出警告。使用时加载只有当 Codex 决定要使用某个技能无论是显式还是隐式时它才会去读取该技能目录下的完整SKILL.md文件内容。这意味着什么你可以安装很多技能而不用担心它们一启动就“撑爆”上下文。但你必须确保技能的name和description足够清晰、独特以便 Codex 在有限的初始信息中做出正确选择。2.3 Skills 的目录结构与核心文件一个技能就是一个标准的目录结构如下my-git-commit-skill/ # 技能目录名 ├── SKILL.md # 【必需】技能指令与元数据文件 ├── scripts/ # 【可选】可执行的脚本文件如 .sh, .py, .js ├── references/ # 【可选】参考文档、规范文件 ├── assets/ # 【可选】模板、图片等静态资源 └── agents/ └── openai.yaml # 【可选】用于 App 界面展示和依赖声明的配置文件SKILL.md是灵魂。它是一个 Markdown 文件但必须包含一个 YAML Front Matter 块来声明元数据后面跟着给 Codex 看的详细指令。--- name: generate-api-docs # 技能名称用于 $name 调用 description: # 技能描述用于隐式匹配 当用户要求为 Python/Go/JavaScript 函数或模块生成 API 文档 或询问“这个函数怎么用”时触发。仅针对代码文件内容操作。 --- # 生成 API 文档 技能指令 1. 首先请用户提供目标代码文件或直接粘贴代码内容。 2. 分析代码中的公开函数、类、方法及其参数、返回值。 3. 使用 Google 风格或 JSDoc 风格为每个元素生成详细的注释文档。 4. 输出格式应为 Markdown包含模块概述和每个元素的详细说明。 5. 最后询问用户是否满意或是否需要调整格式。3. 从零开始创建你的第一个 Skill一个实用的 Git 提交规范助手理论懂了我们立刻动手创建一个能解决实际问题的技能。假设我们团队约定使用 Conventional Commits 规范但总有人记不住格式。我们来创建一个 Skill让 Codex 帮助生成规范的提交信息。3.1 规划技能明确输入、处理和输出在创建文件之前先想清楚触发场景当用户提到“提交”、“commit”、“写提交信息”时。输入用户提供的本次变动的简短描述。处理引导用户选择变更类型feat, fix, docs等填写影响范围生成规范信息。输出一条符合 Conventional Commits 规范的提交信息字符串。3.2 手动创建技能目录和文件打开终端进入你希望存放技能的位置。通常从用户级目录开始是个好选择这样所有项目都能用。# 进入用户级的技能目录Codex 会自动扫描这里 mkdir -p ~/.agents/skills cd ~/.agents/skills # 创建我们的技能目录 mkdir conventional-commit-helper cd conventional-commit-helper现在创建核心文件SKILL.md--- name: conventional-commit description: 当用户需要编写 Git 提交信息、询问提交格式规范或提及“conventional commit”时触发。 此技能将引导用户生成符合 Conventional Commits 规范的提交信息。 --- # Conventional Commits 提交信息助手 我将帮助你生成一条规范的 Git 提交信息。请按照以下步骤操作 ## 步骤 1选择变更类型 请从以下列表中选择最符合本次变动的类型 - feat: 新功能 - fix: 错误修复 - docs: 仅文档更改 - style: 不影响代码含义的更改空格、格式化等 - refactor: 既不是修复错误也不是添加功能的代码更改 - perf: 性能改进 - test: 添加或修正测试 - chore: 对构建过程或辅助工具的更改 请告诉我你的选择例如feat。 ## 步骤 2确定影响范围可选 影响范围通常是修改的模块、组件或文件名。例如auth, user-api, README。 如果变动影响广泛或难以界定可以留空或输入none。 请告诉我影响范围 ## 步骤 3描述变动 用一句简洁的祈使句描述变动。不要以大写字母开头不要使用句号。 例如“添加用户登录验证中间件” 请描述你的变动 ## 步骤 4填写详细说明可选 如果需要可以提供更详细的解释。这将成为提交信息的主体部分。 ## 步骤 5是否包含破坏性变更 如果你的改动包含了不向后兼容的 API 变更请在此说明。否则请说“无”。 --- 当我收集完所有信息后我会生成如下格式的提交信息 类型[可选 范围]: 简短描述 [空一行] [可选 详细描述] [空一行] [可选 脚注如 BREAKING CHANGE: ...]保存这个文件。一个最简单的“纯指令”技能就创建好了。3.3 测试你的技能重启你的 Codex CLI 或 App让它重新扫描技能目录。在 Codex 对话中尝试输入“我要提交代码帮帮我。”理想情况下Codex 会识别到description中的关键词并自动应用$conventional-commit技能开始引导你一步步输入。你也可以显式调用直接输入“$conventional-commit”。第一次测试的要点看触发是否准确你说“写提交信息”它触发了吗你说“怎么写文档”它误触发了吗根据测试结果回头调整SKILL.md中的description。看流程是否顺畅AI 是否严格遵循了你写的步骤用户会不会被卡住根据体验优化指令的措辞和引导逻辑。3.4 进阶为技能添加脚本可选上面的技能只完成了“引导和生成文本”。如果我们想让它更强大比如自动分析git diff来建议变更类型就需要脚本。在技能目录下创建scripts/目录和一个脚本文件mkdir scripts创建scripts/suggest_type.py:#!/usr/bin/env python3 import subprocess import sys import re def run_git_diff(): 执行 git diff --staged 获取暂存区变更 try: result subprocess.run([git, diff, --staged, --name-only], capture_outputTrue, textTrue, checkTrue) return result.stdout.strip().split(\n) except subprocess.CalledProcessError: return [] except FileNotFoundError: print(Git 未安装或当前目录不是 Git 仓库。) return [] def analyze_files(file_list): 简单分析文件列表给出变更类型建议 if not file_list: return chore, 无暂存文件可能是配置或工具变更。 suggestions [] for file in file_list: if file.endswith(.md) or file README: suggestions.append((docs, 修改了文档文件)) elif re.search(rtest|spec, file, re.IGNORECASE): suggestions.append((test, 修改了测试文件)) elif re.search(r\.(py|js|java|go|cpp|ts)$, file): suggestions.append((refactor, 修改了源代码文件)) # 更精确的分析需要看diff内容 # 简单的投票逻辑 if suggestions: # 这里简化处理返回第一个建议 return suggestions[0] return chore, 基于文件路径无法明确判断请手动选择。 if __name__ __main__: files run_git_diff() rec_type, reason analyze_files(files) print(f建议类型: {rec_type}) print(f理由: {reason}) if files: print(f涉及文件: {, .join(files[:5])}) # 只显示前5个然后更新你的SKILL.md在开头或合适位置加入对脚本的调用说明--- name: conventional-commit description: ...同上... --- # Conventional Commits 提交信息助手 **可选前置步骤**如果你已经在 Git 仓库中并暂存了文件我可以先帮你分析变更建议变更类型。 你可以对我说“分析一下暂存区的改动”。 --- 原有的步骤引导保持不变...现在你的技能具备了交互式引导和调用外部脚本分析的能力。Codex 在执行技能时可以运行这个 Python 脚本并将结果作为参考信息融入对话。4. 技能的管理、安装与团队共享创建个人技能只是开始如何高效地管理一堆技能以及如何与团队共享是让 Skills 发挥最大价值的关键。4.1 Skills 的搜索路径与优先级Codex 从多个位置查找技能理解优先级可以避免冲突技能范围路径示例推荐用途REPO (仓库)./.agents/skills/当前项目专属技能。比如某个微服务特有的部署脚本。REPO (仓库)../.agents/skills/当你在子目录启动 Codex 时使用父目录的共享技能。REPO (仓库)$REPO_ROOT/.agents/skills/团队项目级共享技能。整个代码库通用的规范、工具链技能。USER (用户)~/.agents/skills/个人全局技能。你自己在任何项目都用的工具比如我们刚创建的提交助手。ADMIN (系统)/etc/codex/skills/系统级共享技能。运维或管理员统一配置的技能如公司内部 SDK 自动化脚本。SYSTEM (内置)OpenAI 随 Codex 内置Codex 自带的通用技能如skill-creator。优先级与冲突Codex 会扫描所有路径。如果不同路径下有同名技能它们会同时出现在技能列表中不会相互覆盖。这允许你在全局有一个基础版本在特定项目覆盖一个定制版本。但在使用时需要手动选择可能造成混淆。因此团队内最好约定命名规范。4.2 安装社区精选技能你不需要所有技能都自己写。社区有很多现成的优秀技能。官方提供了$skill-installer这个内置技能来帮助你安装。例如你想安装一个用于与 Linear项目管理工具集成的技能在 Codex 对话中输入$skill-installer。按照引导输入技能名如linear或技能仓库的 URL。安装器会从 GitHub 等仓库下载技能文件到你的用户技能目录 (~/.agents/skills/)。重启 Codex 或等待其自动扫描新技能即可用。注意$skill-installer适合个人尝鲜。对于团队和生产环境更推荐使用“插件”方式或直接管理 Git 子模块来分发技能。4.3 启用、停用与配置技能有时你可能想临时关闭某个技能而不是删除它。你可以通过编辑 Codex 的配置文件~/.codex/config.toml来实现# 在 ~/.codex/config.toml 中添加 [[skills.config]] path /full/path/to/your/skill/SKILL.md # 技能文件的绝对路径 enabled false # 设置为 false 以停用修改配置后需要重启 Codex 生效。这对于调试或管理大量技能非常有用。4.4 通过插件分发技能团队共享最佳实践如果你开发的技能希望被团队复用或者想和应用打包在一起“插件”是比直接复制技能目录更规范的分发方式。插件Plugin可以包含一个或多个技能应用配置映射MCP 服务器配置展示用的图标和元数据对于团队场景我强烈建议将技能放在项目的 Git 仓库中作为插件或直接放在.agents/skills/目录下。这样版本可控技能的迭代和代码迭代同步。一键获取新成员克隆仓库后技能自然就位。环境一致确保所有开发者使用同一套 AI 辅助工作流。例如在项目根目录创建.agents/skills/team/目录存放团队技能然后在项目 README 中说明。Codex 会在项目内自动发现它们。5. 设计高质量 Skills 的最佳实践与避坑指南创建技能不难但创建出稳定、好用、不添乱的技能需要一些技巧。以下是我从实际使用中总结出的关键点。5.1 技能设计原则单一职责聚焦明确一个技能只做好一件事。不要创建“代码处理全能王”而是拆分成“代码审查”、“生成文档”、“重构建议”等多个独立技能。这能让 Codex 更准确地匹配也便于你维护。指令优先脚本为辅能用自然语言指令让 Codex 完成的任务就不要写脚本。脚本适用于需要确定性操作如执行特定命令、调用固定 API或复杂计算的场景。指令更灵活更能利用 AI 的理解能力。描述清晰界定边界技能的description字段是隐式调用的生命线。要用简练的语言说清楚在什么情况下触发关键词、场景。技能的边界是什么不处理什么。例如“当用户请求对 Python/JavaScript 代码进行安全漏洞扫描时触发。仅进行代码模式分析不执行动态渗透测试。”步骤化与结构化在SKILL.md的指令部分使用清晰的步骤、列表和标题。明确告诉 Codex 每一步该做什么、询问用户什么、输出什么格式。这能极大提高工作流的稳定性。包含示例在指令中提供输入输出的例子。这能帮助 Codex 更好地理解你的意图和期望的格式。5.2 常见问题排查当你发现技能不工作时按这个顺序检查技能是否被加载在 Codex 中输入/skills列表看看你的技能在不在里面。如果不在检查技能目录是否放在了正确的扫描路径下见 4.1。检查SKILL.md的 YAML Front Matter 格式是否正确name和description字段是否存在。技能是否被触发隐式调用失败首先检查你的问题是否匹配技能的description。尝试使用description中的关键词提问。尝试显式调用$skill-name。如果显式调用成功但隐式不行问题就在description上需要调整得更精准。检查是否有多个同名技能造成混淆。技能执行结果不符合预期检查指令清晰度你的指令是否有歧义步骤是否足够具体让同事看看指令看是否能理解你期望的流程。检查上下文Codex 在执行技能时是否包含了无关的对话历史干扰了判断尝试开启一个新会话单独测试技能。检查脚本权限如果技能包含脚本确保脚本文件有可执行权限 (chmod x scripts/your_script.sh)并且 Codex 有权限运行它。性能或响应慢检查技能目录下是否有非常大的文件如图片、视频被意外包含。Codex 虽然按需加载但扫描目录时可能会受影响。过于复杂的脚本或需要网络请求的脚本可能会阻塞响应。5.3 从“玩具”到“生产”的升级思路个人使用的技能可以随意些但用于团队协作时需要考虑更多版本管理将技能目录纳入 Git。对SKILL.md的修改也要提交和 Review就像对待代码一样。文档化在团队 Wiki 或 README 中维护一个技能清单说明每个技能的用途、触发方式和维护者。参数化考虑将技能中的某些固定值如 API 端点、文件路径提取为可配置项。可以通过在技能目录下放置一个config.json并在指令中告诉 Codex 去读取它。错误处理在指令中预设一些错误处理逻辑例如“如果步骤 X 失败则询问用户 Y 信息”。与 CI/CD 集成可以创建一些用于自动化部署、回滚、检查的 Skills并通过 Codex CLI 在 CI 流水线中非交互式地调用它们实现 AI 驱动的运维。最后记住 Skills 的核心价值是“固化优秀工作流”。不要追求一次性创建完美的技能。最好的方法是先为一个具体、高频的小任务创建一个最小可用的技能然后在实际使用中不断迭代优化它的指令和逻辑。当你和你的团队逐渐积累起一个精心打磨的技能库时Codex 才能真正成为你们得力的自动化伙伴。