🚀 30+款热门AI模型一站整合,DeepSeek/GLM/Qwen 随心用,限时 5 折。 👉 点击领海量免费额度
你装好了 Codex,看着它强大的代码生成能力,却总觉得差点意思。让它写个函数,它写得又快又好;但当你需要它帮你完成一个完整的、多步骤的自动化任务时,比如“分析这个项目的依赖,生成一份安全报告,并自动创建一个待办事项”,它要么卡壳,要么跑偏。问题出在哪?你缺的不是一个更聪明的模型,而是一套能让 Codex 稳定执行复杂任务的“操作手册”——这就是Skills(智能体技能)。
很多人把 Codex 当作一个加强版的代码补全工具,这大大低估了它的潜力。它的核心价值在于扮演一个能理解你意图、并自主执行工作流的“智能体”。而 Skills,就是定义这些工作流的蓝图。没有 Skills,Codex 就像一台没有安装任何软件的电脑,空有强大的硬件,却无法完成特定任务。掌握 Skills,你才能真正解锁 Codex 的“进阶玩法”,将零散的指令串联成可预测、可复用、可协作的自动化流程。
本文将带你从零开始,彻底吃透 Codex Skills。我们不会停留在概念介绍,而是直接切入实战:从 Skills 的核心原理讲起,手把手教你创建第一个技能,再到如何组织、分发、管理你的技能库。你将学会如何让 Codex 从一个“代码助手”进化为一个能处理代码审查、自动化部署、数据分析等复杂任务的“工程伙伴”。无论你是想提升个人效率,还是为团队构建标准化的开发流程,这篇文章都将为你提供清晰的路径和可落地的方案。
1. 这篇文章真正要解决的问题
你是否遇到过这些情况?
- 重复劳动:每次开始新项目,都要手动设置相同的
.gitignore、README.md和基础 CI/CD 配置。 - 流程混乱:团队里每个人执行代码审查、运行测试、部署的步骤都不一致,导致结果不可预测。
- 智能体“失忆”:你告诉 Codex 一个复杂的多步任务,它执行到一半就忘了前面的上下文,或者开始自由发挥。
- 能力孤岛:你精心调教出一个好用的提示词(Prompt),却无法方便地分享给同事或在其他项目中复用。
这些问题背后,本质上是缺乏一种将“知识”和“流程”固化、标准化并分发给 AI 智能体的机制。Codex Skills 正是为了解决这些问题而生。它不是一个花哨的功能,而是 Codex 从“玩具”走向“生产力工具”的关键桥梁。
本文要解决的核心问题是:如何系统性地为 Codex 构建、管理和应用 Skills,从而将一次性的、脆弱的对话提示,转变为稳定、可靠、可复用的自动化工作流。
我们将重点关注:
- 理解 Skills 与普通 Prompt 的本质区别:为什么简单的聊天指令无法胜任复杂工作流?
- 掌握 Skills 的完整生命周期:从创建、测试、优化到分发和团队协作。
- 避开常见陷阱:例如技能描述(description)写得不好导致无法触发,或者技能之间相互冲突。
- 构建实用的技能库:我们将创建几个真实场景的技能示例,如“初始化项目脚手架”、“运行安全扫描并生成报告”。
读完本文,你将能清晰地判断一个任务是否适合封装为 Skill,并具备独立开发和部署一套技能体系的能力。
2. 基础概念与核心原理
在深入实操之前,我们必须厘清几个关键概念,这能帮助你理解 Skills 为何如此设计,以及如何更有效地使用它。
2.1 什么是 Codex Skills?
简单来说,一个 Skill 就是一个打包好的“任务执行包”。它不仅仅是一段提示词,而是包含:
- 指令(Instructions):告诉 Codex 这个技能要做什么、分几步做、输入输出是什么。这是技能的核心。
- 元数据(Metadata):主要是
name和description,用于技能的识别和匹配。 - 参考资料(References):可选的文档、API 说明、规范文件等,为 Codex 提供执行任务所需的背景知识。
- 脚本(Scripts):可执行的外部脚本(如 Bash、Python),用于处理那些需要确定性或复杂计算的任务。
Skills 与普通 Prompt 的核心区别:
| 特性 | 普通 Prompt (聊天/单次指令) | Codex Skill |
|---|---|---|
| 结构化 | 非结构化,自由文本 | 高度结构化,包含元数据、指令、可选资源 |
| 可复用性 | 低,每次需重新输入或复制粘贴 | 高,一次创建,随处调用 |
| 上下文管理 | 依赖对话历史,易丢失 | 技能被调用时,其完整指令会按需加载到上下文,确保完整性 |
| 触发方式 | 手动输入 | 显式调用(如$skill-name)或隐式调用(Codex 根据描述自动匹配) |
| 分发与协作 | 困难,通过文本分享 | 容易,可通过文件、Git 仓库或插件形式分发 |
2.2 Skills 的核心工作原理:“按需展开”上下文
这是 Skills 设计中非常精妙的一点,也是其高效的关键。Codex 启动时,不会把所有已安装技能的详细指令都加载到内存或上下文中。这样做会迅速耗尽有限的大模型上下文窗口。
它的工作流程是:
- 扫描与索引:Codex 启动后,会从多个预设路径(后文详述)扫描所有技能目录,但只读取每个技能的
SKILL.md文件中的name和description这两个元数据字段。 - 生成技能列表:Codex 将这些简化的技能信息(名称和简短描述)汇总成一个列表,放入初始上下文。这个列表的大小被严格限制(通常不超过上下文窗口的2%或8000字符),以确保不会挤占主要的任务提示词空间。如果技能太多,Codex 会自动缩短描述。
- 智能匹配与触发:当你提出一个任务时,Codex 会基于这个简化的技能列表,判断是否有技能的
description与当前任务匹配(隐式调用),或者你直接通过$skill-name指定了技能(显式调用)。 - 按需加载:只有当 Codex 决定要使用某个技能时,它才会去读取该技能
SKILL.md中的完整指令、以及相关的参考资料和脚本,并将其加载到当前上下文中。这就像一本厚厚的操作手册,Codex 平时只记得目录,用到哪一章才去翻看具体内容。
这种“按需展开”机制,在技能数量庞大时,能极大地提升资源利用效率和响应速度。
2.3 Skill 与 Plugin 的关系
这是另一个容易混淆的概念。根据官方材料:
- Skill(技能):是“可复用工作流”的创作格式。它关注的是工作流本身的设计和定义。你首先应该思考的是如何把一项任务流程化。
- Plugin(插件):是“可安装分发单元”。它关注的是如何将一个或多个技能(以及可能的其他资源,如 MCP 服务器配置、应用映射)打包,以便于分发、安装和集成。
简单类比:Skill 像是你写的一个 Python 脚本(.py文件),而 Plugin 像是你将这个脚本打包成的 Pip 安装包(.whl文件),后者更容易分享和安装。
最佳路径:先专注于在本地创建和测试好你的 Skill。当你需要与团队共享,或希望将其作为产品的一部分交付时,再考虑将其打包成 Plugin。
3. 环境准备与前置条件
在开始创建 Skills 之前,请确保你的 Codex 环境已就绪。
- 已安装 Codex:你需要已经成功安装并配置好 OpenAI Codex。这通常包括 Codex CLI、IDE 扩展(如 VS Code)或 Codex App。本文的示例将主要基于 CLI 环境,但原理通用。
- 基础命令行操作:需要熟悉在终端(Terminal)中进行基本的目录和文件操作。
- 文本编辑器:用于编辑
SKILL.md和 YAML 配置文件。 - (可选)Git:如果你计划在团队中通过 Git 仓库管理技能,需要基本的 Git 知识。
验证安装:打开终端,运行以下命令,确认 Codex CLI 可用。
codex --version如果看到版本号输出,说明安装成功。如果提示命令未找到,请参考官方文档完成 Codex CLI 的安装和配置。
4. 核心流程拆解:创建你的第一个 Skill
让我们从一个最实用的场景开始:创建一个用于“初始化 Python 项目脚手架”的 Skill。这个技能将指导 Codex 自动创建标准的项目目录结构、README.md、requirements.txt、.gitignore等文件。
4.1 规划技能内容
在动手写代码之前,先明确技能的目标:
- 名称(name):
init-python-project - 描述(description): 当用户想要创建一个新的 Python 项目,或初始化一个空目录为 Python 项目结构时触发。技能将创建基础文件和目录。
- 指令(instructions): 详细列出创建步骤、文件内容模板以及注意事项。
- 触发方式: 我们希望通过隐式调用,例如用户说“帮我把这个文件夹初始化为一个 Python 项目”,Codex 就能自动匹配并执行此技能。
4.2 选择技能的保存位置
Codex 从多个层级读取技能,我们需要决定把技能放在哪里。对于个人常用技能,放在用户目录下是最方便的。
根据材料,用户级技能的路径是:$HOME/.agents/skills
- Linux/macOS:
~/.agents/skills - Windows:
%USERPROFILE%\.agents\skills
我们在此路径下为我们的技能创建一个目录。
# 进入用户技能目录 cd ~/.agents/skills # 为我们第一个技能创建目录 mkdir init-python-project # 进入技能目录 cd init-python-project4.3 创建核心文件:SKILL.md
这是技能的灵魂。在init-python-project目录下,创建SKILL.md文件。
--- name: init-python-project description: Initialize a standard Python project scaffold with README, .gitignore, requirements.txt, and a src/ directory structure. Trigger when the user asks to set up, create, or initialize a new Python project in the current or a specified directory. --- # Python Project Initialization Skill ## Goal Create a standard, well-organized Python project structure in the current working directory (or a specified path). ## Workflow Steps 1. **确认目标目录**: 询问用户是否在当前目录初始化,或指定其他路径。如果未指定,默认使用当前目录。 2. **创建核心目录**: * `src/`: 用于存放项目源代码包。 * `tests/`: 用于存放单元测试。 * `docs/`: 用于存放项目文档。 3. **创建基础文件**: * `README.md`: 包含项目名称、简介、安装和用法示例。 * `requirements.txt`: 初始为空,用于记录项目依赖。 * `.gitignore`: 包含针对 Python 和常见 IDE 的忽略规则。 * `setup.py` 或 `pyproject.toml`: 基础的打包配置(可选,根据用户需求)。 * `src/__init__.py`: 使 `src` 成为一个 Python 包。 4. **填充文件内容**: 为每个文件生成合理、通用的初始内容。 5. **输出总结**: 列出所有创建的文件和目录,并给出下一步建议(如:安装虚拟环境,添加第一个模块)。 ## Detailed Instructions for Codex 当你执行此技能时,请严格遵循以下步骤: ### 1. 交互确认 向用户提问:“您希望在哪一个目录初始化 Python 项目?(默认: 当前目录 `$(pwd)`)”。等待用户输入或确认。 ### 2. 目录创建 在目标目录中,依次创建以下目录(如果不存在): - `src/` - `tests/` - `docs/` ### 3. 文件创建与内容生成 在目标目录中创建以下文件并填充内容: **a. README.md** ```markdown # Project Title Brief description of your Python project. ## Installation ```bash # Clone the repository git clone <repository-url> cd <project-folder> # (Optional) Create a virtual environment python -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate` # Install dependencies pip install -r requirements.txtUsage
from src import main # Example usage if __name__ == "__main__": main.run()Project Structure
. ├── src/ # Source code ├── tests/ # Test files ├── docs/ # Documentation ├── README.md └── requirements.txtLicense
[Specify your license, e.g., MIT]
**b. .gitignore** ```gitignore # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # Virtual environments venv/ env/ .venv/ # IDE .vscode/ .idea/ *.swp *.swo # Distribution / packaging dist/ build/ *.egg-info/ # Logs and databases *.log *.sqlite3 # OS generated files .DS_Store Thumbs.dbc. requirements.txt(初始留空,或添加常见开发依赖)
# Add your project dependencies here # e.g., requests>=2.28.0d. src/init.py(创建一个空文件,使其成为一个包)
4. 最终输出
完成所有操作后,向用户报告: “✅ Python 项目脚手架初始化完成! 已创建目录:src/, tests/, docs/ 已创建文件:README.md, .gitignore, requirements.txt, src/init.py 建议下一步:1. 创建虚拟环境 (python -m venv venv)。2. 激活虚拟环境。3. 开始在你的src/目录下编写代码。”
Boundaries
- 如果目标目录已存在同名文件,应询问用户是否覆盖,或跳过。
- 本技能仅创建基础结构,不涉及安装特定框架(如 Django, Flask)或复杂的配置。
- 如果用户的需求明显是其他语言(如 JavaScript, Go)的项目,不应触发此技能。
**关键点解析**: 1. **Front Matter**: 开头的 `---` 之间是 YAML 格式的元数据,`name` 和 `description` 是必需的。`description` 写得非常具体,包含了触发词(“set up, create, initialize”)和场景(“new Python project”),这有助于 Codex 进行准确的隐式匹配。 2. **结构化指令**: 指令部分被清晰地分为 Goal、Steps、Detailed Instructions 和 Boundaries。使用祈使句和明确的步骤,让 Codex 易于遵循。 3. **包含示例代码**: 在指令中直接包含了文件内容的模板,Codex 可以直接使用或微调,这比让它“凭空想象”要可靠得多。 4. **明确边界(Boundaries)**: 定义了技能“不该做什么”,防止 Codex 在不合适的场景下被触发或执行错误操作。 ### 4.4 测试技能 保存 `SKILL.md` 后,Codex 会自动检测到新技能。如果没有立即出现,重启你的 Codex 应用或 CLI 会话。 现在,打开 Codex(CLI 或 IDE),在目标目录下尝试触发它。 **方式一:隐式调用** 在 Codex 聊天界面或 CLI 中输入:帮我在这个文件夹里创建一个新的Python项目。
观察 Codex 的响应。它应该能识别到 `init-python-project` 技能,并开始执行你定义的步骤:询问目录、创建文件夹和文件。 **方式二:显式调用** 你也可以直接使用技能名称调用:$init-python-project
如果技能被成功触发并执行,你会看到目录下生成了相应的文件和文件夹。如果未触发,请检查: 1. 技能目录是否放在了正确的路径(`~/.agents/skills/`)。 2. `SKILL.md` 的格式是否正确,特别是 `name` 和 `description` 字段。 3. `description` 是否足够清晰地描述了触发场景。 ## 5. 进阶技能开发:集成脚本与参考资料 纯指令型技能适用于大多数流程化任务。但对于需要执行确定性操作、调用外部工具或进行复杂计算的任务,我们需要为技能添加**脚本(Scripts)**。 ### 5.1 创建带脚本的技能:自动化代码安全检查 假设我们想创建一个技能,用于对当前 Git 仓库的代码进行简单的安全检查(例如,使用 `grep` 搜索可能存在的硬编码密码、密钥模式)。 1. **创建技能目录和核心文件** ```bash cd ~/.agents/skills mkdir code-security-scan cd code-security-scan touch SKILL.md mkdir scripts ``` 2. **编写脚本** 在 `scripts/` 目录下创建一个 Bash 脚本 `scan_secrets.sh`。 ```bash #!/bin/bash # scripts/scan_secrets.sh # A simple script to scan for potential hardcoded secrets in the current git repository. set -euo pipefail echo "🔍 Starting security scan for potential secrets..." # Define patterns to search for (simplified examples) PATTERNS=( "password\s*=" "api_key\s*=" "secret\s*=" "token\s*=" "BEGIN RSA PRIVATE KEY" "-----BEGIN PRIVATE KEY-----" ) SCAN_RESULTS_FILE=".codex_scan_results.txt" > "$SCAN_RESULTS_FILE" # Clear previous results FOUND_ISSUES=0 for pattern in "${PATTERNS[@]}"; do echo "Scanning for pattern: $pattern" # Use git grep to search only tracked files, ignoring binary files if git grep -n -I -i "$pattern" -- './*' 2>/dev/null | head -20 >> "$SCAN_RESULTS_FILE"; then FOUND_ISSUES=1 fi done if [[ $FOUND_ISSUES -eq 0 ]]; then echo "✅ No obvious hardcoded secrets patterns found in tracked files." rm -f "$SCAN_RESULTS_FILE" else echo "⚠️ Potential secrets found. Review the following matches in $SCAN_RESULTS_FILE:" cat "$SCAN_RESULTS_FILE" echo "" echo "**Important:** This is a basic scan. Manual review is essential. Consider using dedicated secret scanning tools." fi ``` 给脚本添加执行权限: ```bash chmod +x scripts/scan_secrets.sh ``` 3. **编写 SKILL.md** ```markdown --- name: code-security-scan description: Perform a basic security scan on the current Git repository to detect potential hardcoded secrets (like passwords, API keys). Trigger when user asks for a security check, secret scan, or code audit. --- # Code Security Scan Skill ## Goal Run a lightweight, automated scan against the tracked files in the current Git repository to identify patterns commonly associated with hardcoded secrets. Provide a summary report. ## Workflow 1. Ensure the current directory is within a Git repository. 2. Execute the `scripts/scan_secrets.sh` script. 3. Capture and present the script's output to the user. 4. Provide recommendations based on the findings. ## Detailed Instructions for Codex When this skill is invoked, follow these steps: 1. **Check Context**: Confirm with the user that they want to run a security scan in the current repository. If not in a Git repo, inform the user and stop. 2. **Execute Script**: Run the provided Bash script: `./scripts/scan_secrets.sh` - The script uses `git grep` to search for predefined secret patterns. - It outputs results to the terminal and saves them to a temporary file (`.codex_scan_results.txt`). 3. **Interpret Results**: - If the script outputs "No obvious hardcoded secrets patterns found", convey this as a positive check. - If potential issues are found, display the findings from the output file and **strongly advise** the user to manually review each flagged line. 4. **Advise Next Steps**: - Recommend using dedicated secret management solutions (e.g., environment variables, vaults). - Suggest integrating more robust secret scanning tools (like `gitleaks`, `truffleHog`) into CI/CD pipelines. - Remind the user to remove any accidentally committed secrets from history using `git filter-repo` if necessary. ## Boundaries & Notes - This is a **basic** heuristic scan. It will have false positives and false negatives. - It only scans files tracked by Git. Untracked or ignored files are not checked. - The skill is read-only and does not modify any code. - The script is provided as part of the skill. Codex should not attempt to rewrite the scanning logic unless explicitly asked to improve the skill itself. ``` **这个技能的关键在于**:我们将确定性的、复杂的文件扫描逻辑封装在了外部脚本中。Codex 的角色是**编排者**——它负责确认上下文、执行脚本、解释结果并提供建议。这比让 Codex 自己生成并执行 `grep` 命令更可靠、更安全。 ### 5.2 使用参考资料(References) 对于一些需要特定领域知识的技能,你可以提供参考资料。例如,为一个“编写 AWS CloudFormation 模板”的技能添加 AWS 资源类型文档。 在技能目录下创建 `references/` 文件夹,将相关的 `aws_cf_guide.md` 等文档放入。在 `SKILL.md` 的指令中,可以提示 Codex:“关于 EC2 实例属性的详细说明,请参考 `references/aws_ec2_properties.md`”。Codex 在加载技能时,会将这些参考资料一并读入上下文。 ## 6. 技能的组织、管理与高级配置 ### 6.1 技能的多层级存储 Codex 支持从不同层级加载技能,这为技能的管理提供了灵活性。理解这些层级对团队协作至关重要。 | 技能范围 | 路径示例 | 推荐用途 | | :--- | :--- | :--- | | **REPO (仓库)** | `./.agents/skills/` | **项目/模块特定技能**。如:该项目独有的构建脚本、部署流程。 | | **REPO (仓库根)** | `$REPO_ROOT/.agents/skills/` | **团队共享技能**。如:团队统一的代码审查标准、提交信息规范。 | | **USER (用户)** | `~/.agents/skills/` | **个人全局技能**。如:你为自己定制的常用工具链、笔记模板。 | | **ADMIN (系统)** | `/etc/codex/skills/` | **系统级技能**。由管理员部署,如:公司内网服务调用、统一审计日志。 | | **SYSTEM (内置)** | (随 Codex 安装) | **Codex 官方内置技能**。如:`skill-creator`, `skill-installer`。 | **冲突解决**:如果不同层级存在同名技能,Codex **不会**合并它们,而是会同时出现在可选列表中。这允许你在个人层级覆盖或扩展系统/团队层级的技能。 ### 6.2 启用、停用与配置技能 你不需要通过删除文件来禁用技能。可以通过编辑 Codex 的用户配置文件 `~/.codex/config.toml` 来管理。 ```toml # ~/.codex/config.toml [[skills.config]] path = "/home/your_username/.agents/skills/experimental-skill/SKILL.md" enabled = false # 禁用此技能 [[skills.config]] path = "/home/your_username/.agents/skills/code-security-scan/SKILL.md" enabled = true # 确保启用(默认就是true) # 可以在这里添加其他配置,如调用优先级等(如果未来支持)修改配置后,需要重启 Codex 以使更改生效。
6.3 添加可选元数据 (agents/openai.yaml)
为了在 Codex App 等图形界面中获得更好的体验,你可以为技能添加元数据文件。
在技能目录下创建agents/openai.yaml:
# agents/openai.yaml interface: display_name: "Python 项目初始化器" # 在UI中显示的名称 short_description: "快速创建标准Python项目结构" # UI中的简短描述 icon_small: "./assets/python-icon-small.svg" # 图标路径(可选) icon_large: "./assets/python-icon-large.png" brand_color: "#3776AB" # Python 标志性的蓝色 default_prompt: "请使用Python项目初始化技能。" # 使用技能时的默认环绕提示词 policy: allow_implicit_invocation: true # 是否允许隐式调用,默认为true。设为false则只能显式调用。 dependencies: tools: - type: "mcp" value: "github" description: "Access to GitHub API for repository operations" transport: "stdio" # url or command would be defined in MCP server config这个文件不是必须的,但它能提升技能在集成环境中的可发现性和易用性。
7. 技能的分发:从 Skill 到 Plugin
当你开发了一个非常有用的技能,并希望与团队或社区分享时,就应该考虑将其打包为Plugin。
根据材料,在以下情况应考虑使用 Plugin:
- 分发可复用技能:让其他人能通过简单的命令安装你的技能。
- 组合多个技能:将一组相关的技能打包在一起分发。
- 与应用集成交付:将技能作为某个桌面应用或 CLI 工具的一部分。
创建 Plugin 是一个更高级的主题,通常涉及定义plugin.yaml清单文件,指定包含的技能、依赖的 MCP 服务器、所需的权限等。官方文档的“插件”部分提供了详细指南。简单来说,Plugin 是一个包含技能和其他资源的标准化包。
对于个人和团队内部共享,一个更轻量级的方法是使用Git 仓库。你可以将你的技能目录推送到 Git 仓库(如 GitHub),团队成员通过克隆仓库到本地~/.agents/skills/或使用符号链接的方式来安装。
8. 最佳实践与工程建议
根据官方指南和实战经验,以下是创建高质量 Skills 的关键建议:
- 单一职责,聚焦明确:一个技能只做一件事,并把它做好。不要创建“瑞士军刀”式的巨型技能。例如,将“代码审查”和“安全扫描”拆分为两个独立的技能。
- 指令优先于脚本:除非需要绝对的确定性、调用外部工具或执行复杂计算,否则尽量用清晰的指令(Instructions)来指导 Codex。这保持了灵活性,并能利用大模型的推理能力。脚本应作为指令的补充。
- 编写清晰的描述(Description):这是隐式调用的关键。用简练的语言说明技能在什么场景下触发,并包含关键的触发词。同时,也要说明什么情况下不应触发。例如:“当用户请求生成数据库迁移脚本或修改现有表结构时触发。不适用于普通的数据查询操作。”
- 测试、测试、再测试:用各种相关的、不相关的提示词去测试你的技能。确保它在该出现的时候出现,不该出现的时候保持沉默。检查其执行结果是否符合预期。
- 版本控制你的技能:将
.agents/skills/目录纳入 Git 管理。这便于回溯更改、团队协作和回滚。 - 建立团队技能库:在团队项目的根目录创建
.agents/skills/文件夹,存放团队共享的技能(如项目规范的代码生成器、团队特定的部署脚本)。这能极大提升团队协作的一致性和效率。 - 注意安全边界:对于能执行脚本或访问外部资源的技能,务必在指令中明确其操作范围和权限。避免创建具有破坏性(如
rm -rf)或高权限操作的技能,除非在绝对受控的环境下。 - 从模仿开始:参考官方和社区的技能示例(如
openai/skills仓库)是快速学习的最佳途径。看看别人是如何设计指令结构和描述语句的。
9. 常见问题与排查思路
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 技能未在列表中显示 | 1. 技能目录位置错误。 2. SKILL.md格式错误(如缺少name/description)。3. Codex 未重启。 | 1. 检查技能路径是否在 Codex 扫描范围内。 2. 检查 SKILL.md的 YAML front matter 语法。3. 重启 Codex CLI/App。 | 1. 将技能移到~/.agents/skills/等标准路径。2. 修正 SKILL.md文件。3. 重启后重试。 |
| 技能描述匹配失败(隐式调用不触发) | 1. 描述 (description) 不够准确或关键词不匹配。2. 技能太多,描述被截断。 | 1. 用你的测试提示词与技能描述对比。 2. 查看 Codex 启动日志(如果有),看是否有技能被省略的警告。 | 1. 优化description,将核心触发词放在开头。2. 减少不必要技能,或使用显式调用 $skill-name。 |
| 技能执行结果不符合预期 | 1. 指令 (instructions) 不够清晰或有歧义。2. 技能依赖的上下文或环境不存在。 | 1. 逐步检查技能指令,模拟 Codex 的执行过程。 2. 检查技能是否需要特定目录、文件或工具。 | 1. 将指令拆解为更小、更明确的步骤。 2. 在指令开头添加“前置条件检查”步骤。 3. 在技能中集成必要的检查脚本。 |
显式调用$skill-name报错 | 1. 技能名称拼写错误。 2. 技能被配置文件禁用。 | 1. 确认技能名称与SKILL.md中的name完全一致。2. 检查 ~/.codex/config.toml中该技能是否被设为enabled: false。 | 1. 使用正确的技能名称。 2. 在配置文件中启用技能或删除相关配置行。 |
| 技能执行缓慢或卡住 | 1. 技能指令过于复杂,或包含大量参考资料,导致上下文过长。 2. 技能中的脚本执行超时或出错。 | 1. 简化指令,将部分参考资料移至外部链接或摘要。 2. 单独在终端运行技能中的脚本,检查其性能。 | 1. 遵循“按需展开”原则,不要在技能中放入整本手册。 2. 优化脚本逻辑,增加超时和错误处理。 |
掌握 Codex Skills 的本质,是学会如何将人类的工作流“翻译”成 AI 智能体能够稳定、重复执行的“程序”。它不再是你和模型之间一次性的、充满不确定性的对话,而是一份可版本化、可测试、可共享的自动化契约。
从今天起,尝试将你日常开发中那些重复的、有固定模式的“套路”封装成 Skills。无论是初始化项目、生成样板代码、运行测试套件,还是执行代码审查清单,每一次封装都是对你工作流的一次提炼和优化。当你积累起自己的技能库时,Codex 将真正从一个被动的助手,转变为你项目中一个主动的、可靠的自动化引擎。
🚀 30+款热门AI模型一站整合,DeepSeek/GLM/Qwen 随心用,限时 5 折。 👉 点击领海量免费额度