很多开发者在使用 Codex 时常常会遇到重复性工作的问题——每次都需要重新描述相同的任务流程效率低下且容易出错。Codex Skill 技能系统正是为了解决这一痛点而设计的它让开发者能够将常用工作流打包成可复用的技能包实现一次编写处处使用的自动化体验。本文将完整介绍 Codex Skill 的安装与使用全流程从基础概念到实战操作涵盖技能查找、安装配置、创建编写等核心环节。无论你是刚接触 Codex 的新手还是希望提升工作效率的资深开发者都能通过本文掌握 Skill 技能系统的完整使用方法。1. Codex Skill 核心概念解析1.1 什么是 Agent SkillsAgent Skills代理技能是 Codex 的任务扩展机制通过将指令、资源和可选脚本打包为标准化技能包让 Codex 能够可靠地执行特定工作流。简单来说Skill 就是给 Codex 编写的标准操作流程说明书。每个 Skill 本质上是一个包含 SKILL.md 文件的目录Codex 读取其中的指令并按步骤执行任务。你可以把 Skill 理解为给 Codex 写的标准操作流程——定义清楚做什么、什么时候做、怎么做Codex 就能在合适的时机自动激活它或者在你明确调用时执行它。1.2 Skill 与 Plugin 的区别理解这两个概念的区别很重要Skills技能是工作流的编写格式适合本地开发和团队内部共享Plugins插件是技能的分发格式用于公开发布和跨项目共享先用 Skills 设计工作流本身需要分发给其他开发者时再打包为 Plugin。Skills 在 Codex CLI、IDE 扩展和 Codex App 中均可使用。1.3 Skill 的基本目录结构一个标准的 Skill 目录结构如下my-skill/ ├── SKILL.md # 必备文件元数据 执行指引 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 ├── assets/ # 可选模板、各类资源文件 └── agents/ └── openai.yaml # 可选UI元数据配置各文件/目录的职责说明文件/目录是否必填说明SKILL.md必填技能的核心指令文件必须包含 name 和 description 字段scripts/可选存放可执行代码用于需要确定性行为或调用外部工具的场景references/可选存放额外的参考文档供 Codex 在执行技能时查阅assets/可选存放模板、图片等静态资源文件agents/openai.yaml可选配置 UI 元数据、调用策略和工具依赖声明2. 环境准备与 Codex 基础配置2.1 Codex 环境要求在开始使用 Skill 之前确保你的开发环境满足以下要求操作系统Windows 10/11, macOS 10.15, 或 Linux Ubuntu 18.04Codex 版本建议使用最新稳定版本存储空间至少 500MB 可用空间用于技能安装网络连接需要互联网连接以下载技能包2.2 检查 Codex 安装状态打开终端或命令行工具输入以下命令检查 Codex 是否正常安装# 检查 Codex CLI 版本 codex --version # 检查技能系统状态 codex skills list如果命令执行成功说明 Codex 环境准备就绪。如果出现命令未找到错误需要先完成 Codex 的安装配置。2.3 基础目录结构初始化Codex 会从多个级别读取技能文件建议先创建个人技能目录# 创建用户级技能目录推荐 mkdir -p ~/.agents/skills # 创建项目级技能目录适用于团队项目 mkdir -p ./.agents/skills技能存储位置的作用范围说明作用范围存储路径适用场景REPO$CWD/.agents/skills当前工作目录下的技能适用于特定模块或微服务的团队共享技能USER$HOME/.agents/skills用户的个人技能集适用于该用户在任何仓库中都能使用的技能ADMIN/etc/codex/skills机器或容器级别的共享技能适用于 SDK 脚本、自动化和管理员默认技能SYSTEM由 OpenAI 内置打包面向广泛受众的内置技能所有用户启动 Codex 即可使用3. Skill 的查找与安装方法3.1 内置技能查看Codex 自带了一些基础技能可以通过以下命令查看# 查看已安装的技能列表 codex skills list # 或者使用简写命令 /skills3.2 使用 skill-installer 安装精选技能skill-installer 是安装内置技能之外精选技能的主要工具# 安装 linear 项目管理技能 $skill-installer linear # 安装其他常用技能示例 $skill-installer github-helper $skill-installer code-reviewer $skill-installer documentation-generator安装过程中skill-installer 会自动处理依赖关系和配置设置。安装完成后Codex 会自动检测新技能如果技能没有立即出现在列表中重启 Codex 即可生效。3.3 从 GitHub 仓库安装技能除了官方精选技能还可以从 GitHub 等代码仓库安装社区贡献的技能# 从特定 GitHub 仓库安装技能 $skill-installer https://github.com/username/repo-name/skill-directory # 安装指定分支的技能 $skill-installer https://github.com/username/repo-name/tree/branch-name/skill-path3.4 技能源管理对于需要频繁安装技能的团队可以设置技能源配置文件# 查看当前技能源配置 codex skills sources list # 添加新的技能源 codex skills sources add company-internal https://internal-git.company.com/skills-registry4. Skill 的激活与使用方式4.1 技能工作原理渐进式加载Codex 采用渐进式信息披露机制来管理上下文窗口避免一次性加载所有技能内容挤占提示词空间。具体流程如下启动时加载Codex 启动时只会加载每个技能的名称、描述和文件路径作为初始列表按需加载只有当 Codex 决定使用某个技能时才会加载完整的 SKILL.md 指令内容空间优化初始技能列表的字符数被限制在模型上下文窗口的约 2%或上下文窗口未知时的 8,000 个字符4.2 显式调用技能显式调用是直接指定使用某个技能的方式Codex 不需要做匹配判断# 在 CLI 中使用 $ 符号调用特定技能 $linear create-issue 修复登录页面样式问题 登录按钮在移动端显示异常 # 在 IDE 扩展中使用 /skills 命令 /skills linear create-issue 任务标题 任务描述显式调用的优点是精准控制适合已知技能名称的场景。4.3 隐式匹配触发隐式匹配是让 Codex 自动选择适合当前任务的技能# 直接描述任务Codex 会自动匹配相关技能 帮我创建一个新的 GitHub issue 来跟踪登录页面的样式问题隐式匹配的成功率取决于技能描述字段的编写质量。编写良好的 description 应该清晰描述使用场景和边界条件。4.4 技能调用优先级管理当多个技能可能匹配同一任务时Codex 会基于以下因素确定优先级描述匹配度任务描述与技能 description 的匹配程度使用频率历史使用频率较高的技能优先最近使用最近使用过的技能有更高优先级技能评分基于用户反馈的技能质量评分5. 自定义 Skill 的创建与编写5.1 使用 skill-creator 快速创建Codex 内置了技能创建器可以交互式生成技能框架# 启动技能创建器 $skill-creator创建器会引导你完成以下步骤定义技能用途这个技能要完成什么任务设置触发条件什么时候应该触发这个技能选择实现方式使用纯指令还是包含脚本5.2 手动创建 Skill 目录结构手动创建可以更精细地控制技能配置# 创建技能目录 mkdir -p ~/.agents/skills/my-custom-skill cd ~/.agents/skills/my-custom-skill # 创建核心配置文件 touch SKILL.md mkdir scripts references assets agents5.3 SKILL.md 文件编写规范SKILL.md 是技能的核心文件必须包含元数据和执行指令--- name: code-review-assistant description: 用于自动化代码审查检查代码质量、安全问题和最佳实践遵循情况。适用于 Pull Request 审查和日常代码质量检查。 --- # 代码审查助手技能 ## 使用场景 - Pull Request 代码审查 - 新功能开发完成后的质量检查 - 代码重构前的现状评估 ## 执行步骤 1. **代码结构分析** - 检查文件组织结构是否符合项目规范 - 验证包导入语句的正确性和必要性 - 分析类和方法的分层设计 2. **代码质量检查** - 检测重复代码块 - 检查方法复杂度圈复杂度 - 验证命名规范一致性 3. **安全问题扫描** - 检查常见安全漏洞模式 - 验证输入验证和过滤逻辑 - 检查敏感信息硬编码 4. **性能优化建议** - 识别性能瓶颈 - 建议更高效的数据结构和算法 - 检查资源释放情况 ## 输出格式 提供详细的审查报告包括 - 关键问题必须修复 - 改进建议推荐优化 - 信息提示注意事项5.4 可选配置详解agents/openai.yaml 配置示例# 文件路径agents/openai.yaml # 界面配置控制技能在 Codex App 中的显示方式 interface: display_name: 代码审查助手 short_description: 自动化代码质量与安全检查 icon_small: ./assets/code-review-small.svg icon_large: ./assets/code-review-large.png brand_color: #3B82F6 default_prompt: 请使用代码审查助手技能分析以下代码 # 策略配置控制技能的调用行为 policy: allow_implicit_invocation: true # 允许隐式匹配 # 依赖配置声明技能所需的工具 dependencies: tools: - type: mcp value: code-analysis-tools description: 代码静态分析工具集 transport: stdioscripts/ 目录使用示例对于需要确定性行为的场景可以添加执行脚本#!/usr/bin/env python3 # 文件路径scripts/code_analyzer.py import ast import complexity_calculator def analyze_code_complexity(code_content): 分析代码复杂度 try: tree ast.parse(code_content) complexity complexity_calculator.calculate(tree) return { cyclomatic_complexity: complexity, maintainability_index: calculate_maintainability(code_content) } except SyntaxError as e: return {error: f语法错误: {e}} if __name__ __main__: # 脚本测试代码 sample_code def example_function(x): if x 0: return x * 2 else: return x - 1 result analyze_code_complexity(sample_code) print(result)6. Skill 的管理与维护6.1 技能状态管理查看和管理已安装技能的状态# 查看所有技能状态 codex skills status # 检查特定技能详情 codex skills info linear # 验证技能完整性 codex skills validate my-custom-skill6.2 技能启用与禁用通过配置文件管理技能的启用状态# 文件路径~/.codex/config.toml [[skills.config]] path /path/to/skill/SKILL.md enabled true # 启用技能 [[skills.config]] path /path/to/another-skill/SKILL.md enabled false # 禁用技能修改配置后需要重启 Codex 使更改生效。6.3 技能更新与升级保持技能的最新状态# 检查可用更新 codex skills check-updates # 更新所有技能 codex skills update --all # 更新特定技能 codex skills update linear6.4 技能备份与迁移对于重要的自定义技能建议定期备份# 备份个人技能集 tar -czf skills-backup-$(date %Y%m%d).tar.gz ~/.agents/skills/ # 恢复技能备份 tar -xzf skills-backup-20231201.tar.gz -C ~/7. 实战案例创建项目管理 Skill7.1 案例背景说明假设我们经常需要管理 GitHub 项目的 issue 和 pull request可以创建一个集成的项目管理 Skill 来简化这些重复性工作。7.2 技能设计与规划技能名称project-management-helper主要功能创建和更新 GitHub issue跟踪任务进度生成项目报告管理 pull request 流程7.3 完整技能实现SKILL.md 文件--- name: project-management-helper description: 项目管理助手用于 GitHub 项目的问题跟踪、进度管理和报告生成。关键词issue, pull request, 项目管理进度跟踪。 --- # 项目管理助手 ## 功能概述 本技能提供完整的 GitHub 项目管理功能包括问题创建、进度跟踪和报告生成。 ## 使用方式 ### 创建新 Issue 当需要报告 bug 或提出新功能时使用 1. 提供清晰的标题和描述 2. 指定标签和里程碑 3. 分配负责人 ### 更新任务进度 定期更新任务状态 1. 标记任务完成情况 2. 更新预计完成时间 3. 记录遇到的问题 ### 生成项目报告 周期性生成项目状态报告 1. 汇总已完成任务 2. 分析未完成任务 3. 识别风险点 ## 输出示例Issue 创建成功 标题修复用户登录验证逻辑 链接https://github.com/username/repo/issues/123 状态open | 分配developeragents/openai.yaml 配置interface: display_name: 项目管理助手 short_description: GitHub 项目问题跟踪与管理 brand_color: #238636 policy: allow_implicit_invocation: true dependencies: tools: - type: github value: issues description: GitHub Issues API 访问scripts/github_helper.py#!/usr/bin/env python3 import requests import os class GitHubHelper: def __init__(self): self.token os.getenv(GITHUB_TOKEN) self.headers { Authorization: ftoken {self.token}, Accept: application/vnd.github.v3json } def create_issue(self, repo, title, body, labelsNone): 创建 GitHub issue url fhttps://api.github.com/repos/{repo}/issues data { title: title, body: body, labels: labels or [] } response requests.post(url, jsondata, headersself.headers) if response.status_code 201: return response.json() else: raise Exception(f创建 Issue 失败: {response.text}) # 使用示例 if __name__ __main__: helper GitHubHelper() issue helper.create_issue( owner/repo, 测试 Issue, 这是一个测试描述, [bug, urgent] ) print(fIssue 创建成功: {issue[html_url]})7.4 技能测试与验证安装并测试新创建的技能# 将技能目录链接到技能文件夹 ln -s /path/to/project-management-helper ~/.agents/skills/ # 重启 Codex 加载新技能 codex restart # 测试技能功能 $project-management-helper create-issue 测试功能 验证技能正常工作8. 常见问题与解决方案8.1 安装类问题问题1技能安装失败现象$skill-installer命令执行失败原因网络连接问题或权限不足解决检查网络连接确保有写入目标目录的权限问题2技能安装后不显示现象安装成功但技能列表中看不到原因Codex 未重启或技能路径配置错误解决重启 Codex检查技能文件路径是否正确8.2 使用类问题问题3隐式匹配不准确现象Codex 没有自动选择正确的技能原因技能描述不够清晰或关键词设置不当解决优化 SKILL.md 中的 description 字段前置核心关键词问题4技能执行出错现象技能被调用但执行过程中报错原因依赖工具未安装或配置错误解决检查技能依赖关系确保所有必要工具可用8.3 性能类问题问题5Codex 启动变慢现象安装多个技能后 Codex 启动时间明显增加原因技能数量过多初始加载耗时增加解决禁用不常用的技能优化技能描述长度问题6技能列表被截断现象部分技能没有出现在初始列表中原因技能描述总长度超出上下文限制解决精简技能描述确保核心信息在前80个字符内8.4 排查命令清单建立系统化的排查流程# 1. 检查 Codex 基础状态 codex --version codex status # 2. 验证技能系统 codex skills list codex skills status # 3. 检查具体技能 codex skills info [skill-name] codex skills validate [skill-name] # 4. 查看日志信息 codex logs --tail50 # 5. 测试技能功能 $[skill-name] test-command9. 最佳实践与工程建议9.1 技能设计原则单一职责原则每个技能应该专注于完成一个特定的任务避免创建万能技能。例如将代码审查、文档生成、测试编写分别设计为不同的技能。指令优先原则尽可能使用自然语言指令而不是脚本。只有在需要确定性行为或调用外部工具时才使用脚本。描述优化原则技能的 description 字段应该前置核心使用场景和触发关键词明确说明技能的适用边界避免模糊或过于宽泛的描述9.2 团队协作规范命名约定建立统一的技能命名规范使用小写字母和连字符code-review-helper避免特殊字符和空格名称应该反映技能的主要功能版本管理对自定义技能实施版本控制# 将技能目录纳入 Git 管理 cd ~/.agents/skills/my-skill git init git add . git commit -m 初始版本文档标准为团队技能建立文档模板确保所有技能都有完整的使用说明输入输出示例依赖要求故障排除指南9.3 性能优化建议技能分类组织根据使用频率对技能进行分类高频技能保持启用状态中频技能按需启用低频技能临时安装使用描述长度控制优化技能描述长度策略核心功能描述前50字符内详细说明控制在200字符内示例和边界条件放在详细文档中依赖管理明确声明技能依赖关系在 agents/openai.yaml 中准确配置dependencies: tools: - type: mcp value: specific-tool description: 明确的功能描述9.4 安全注意事项权限最小化技能脚本应该遵循最小权限原则只请求必要的系统权限避免硬编码敏感信息使用环境变量管理凭证输入验证对所有用户输入进行验证def validate_user_input(input_data): 验证用户输入的安全性 if not isinstance(input_data, str): raise ValueError(输入必须是字符串) if len(input_data) 1000: raise ValueError(输入长度超出限制) # 更多验证逻辑...审计日志重要操作应该记录审计日志import logging logging.basicConfig( levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s ) logger logging.getLogger(skill-audit)通过遵循这些最佳实践你可以建立高效、可靠、易维护的 Codex Skill 生态系统显著提升开发工作效率。技能系统的正确使用不仅能够自动化重复任务还能促进团队知识沉淀和标准化流程建设。