Agent Skills实战：从Claude Code到Codex的可复用技能体系

这次我们来看一个直接把两个词串起来的方向：Claude Code 和 Agent Skills。最近几乎所有讨论 AI 编程、AI 自动化、Agent 开发的地方，都会反复出现这两个概念。网上相关的教程很多，但大多要么只讲“怎么用 Claude 聊天”，要么只讲“某个命令怎么敲”，很少把“从会用 AI 到会开发 Agent”这条完整链路讲清楚。这篇文章就用 Agent Skills 为核心，把 Claude Code 和 Codex 串起来，讲一套可落地、可复用、可扩展的智能体技能体系。

Agent Skills 并不是一个新模型，也不是一套全新框架。它更像是一种给 Agent “装技能”的组织方式：以 SKILL.md 为入口，把提示词、脚本、示例、参考资料打包成一个目录，让 Agent 在遇到特定任务时，自动加载对应能力。它的好处非常直接——你不需要每次重复写几百字的提示词，团队里也能把一套成熟技能直接复制复用。换个角度理解，它就是 AI 世界里的“函数封装”，把固定逻辑抽出来，一次定义，到处调用。

这篇文章会完整走一遍：Agent Skills 到底怎么构成、Claude Code 怎么安装启动、Codex CLI 怎么配置、第一个自定义技能怎么创建、技能怎么在对话中触发、怎么把技能接入 API 做批量任务，最后再给一份高频报错排查表。整篇以“能跑通、能复用、能排错”为目标，不绕概念，不堆术语。

如果你已经在用 AI 写代码、整理文档、跑数据处理，但觉得每次都要重新描述需求、重复交代规则很麻烦，这篇文章就是给你准备的。它适合想从“AI 用户”变成“AI 开发者”的人，也适合想在团队里沉淀一套标准 Agent 能力的人。读完之后，你可以直接照着搭出自己的第一套技能库。

1. Agent Skills 核心能力速览

先给一张速览表，方便你快速判断这套东西值不值得花时间研究。

这里要单独说明一点：Agent Skills 的具体文件格式和调用命令，在不同工具版本之间会有差异。文章里给出的是通用结构和示例，落地时以你本机的版本提示和官方文档为准。这一点在后面排查章节会再强调。

2. 适用场景与使用边界

2.1 适合解决什么问题

Agent Skills 最适合的场景是“同一类任务反复出现，且每次都需要 AI 保持固定操作方式”。典型例子包括代码审查、单元测试生成、提交信息规范化、日志分析、文档转换、日报周报整理。把这类任务做成技能之后，你在 Agent 对话里只需要说“帮我审查一下这个 PR”，它就自动套用你预先定义好的审查流程。

另一个典型场景是团队标准化。把技能目录放进 Git 仓库，团队成员 clone 下来就能共享同一套 Agent 工作方式。新人不需要再去读十几条操作规范，只需要让 Agent 加载对应技能，输出格式和检查维度就能保持统一。

2.2 不适合什么场景

• 一次性、探索性的临时对话，没必要做成技能。
• 对响应质量要求极高、完全不能接受随机性的场景，Agent 仍然有不确定性。
• 没有明确触发条件的模糊任务，技能也只是提示词变长，并不能保证输出。
• 需要实时联网获取最新信息的任务，要看工具本身是否支持，技能本身不解决联网问题。

2.3 版权、隐私与安全边界

使用 Claude Code 或 Codex 时，会把代码、文档、配置等内容发送给云端模型服务商处理，涉及公司内部敏感代码前必须确认合规政策。生成代码要注意许可证和第三方版权，如果 Agent 会处理用户画像、人脸、声音、隐私文本，需要获得合法授权。不能用 Agent 绕过系统安全限制、窃取账号或违反平台规则。把 API 密钥写在提示词或技能目录里，是绝对要避免的低级错误。

3. 环境准备与前置条件

3.1 操作系统与依赖

Claude Code 和 Codex CLI 都是以终端为主的工具，官方优先支持 macOS 和 Linux，Windows 上更推荐通过 WSL 或原生终端环境运行。无论哪一条路线，先确认本机有可用的 Node.js 运行环境和包管理器。Node 版本建议使用当前官方维护中的 LTS 版本，具体以工具安装提示为准。

3.2 需要准备的账号

• Anthropic 账号：用于 Claude Code 登录，或者准备 Anthropic API Key。
• OpenAI 账号：用于 Codex CLI 登录，或者准备 OpenAI 兼容接口的 API Key。
• 如果使用的是第三方模型网关或代理服务，只要接口兼容，通常也可以配置。

3.3 通用检查清单

在开始安装之前，按下面清单检查一遍：

这一步看起来琐碎，但绝大多数“装不上”“启动失败”的问题，最后都能追溯到 Node 版本或网络设置。

4. 安装部署与启动方式

4.1 安装 Claude Code

Claude Code 最常见的安装方式是通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装完成后，在终端里进入一个项目目录，执行：

claude

首次运行会引导你登录 Anthropic 账号，或者把 API Key 写入环境变量。成功进入对话界面后，说明基础安装完成。

如果你想在 VSCode 里使用，可以安装 Claude Code 的编辑器插件，安装后会在侧边栏或终端面板里多出 AI 会话入口。具体入口位置和界面在不同版本之间略有差异，以插件说明为准。

4.2 安装 Codex CLI

Codex CLI 同样可以通过 npm 安装：

npm install -g @openai/codex

安装后先验证版本：

codex --version

如果提示找不到命令，说明 npm 全局安装目录没有加入 PATH，需要检查 Node 环境变量配置。

首次使用 Codex 时，需要配置 API 凭据。官方通常会引导你登录账号，或者通过配置文件写入 API Key。对于需要接入第三方兼容模型的情况，可以在 Codex 的配置文件中指定模型提供方和端点，具体字段名要以你安装版本的配置模板为准。

4.3 设置环境变量

无论使用哪个工具，都建议把密钥放在环境变量中，而不是写死在技能文件里。示例如下：

export ANTHROPIC_API_KEY="你的Anthropic密钥" export OPENAI_API_KEY="你的OpenAI密钥" export CODEX_CLI_PATH="/usr/local/bin/codex"

CODEX_CLI_PATH这个变量要特别注意。如果在使用某个 Codex 图形客户端或编辑器插件时，遇到“unable to locate the codex cli binary. set codex cli path or ensure the executable is in your PATH”这类报错，基本就是程序找不到 codex 可执行文件。解决办法就是确认 codex 的实际安装路径，然后把它填入环境变量。可以用下面命令确认路径：

which codex

4.4 准备技能目录

技能可以放在用户级目录，这样所有项目都能用；也可以放在项目级目录，跟随项目走。先创建用户级技能目录：

mkdir -p ~/.claude/skills

如果你在项目里使用，可以在项目根目录创建：

mkdir -p .claude/skills

Codex 的自定义指令和技能组织方式不完全等同 Claude Code，但只要遵循“说明文件 + 脚本 + 参考资源”的思想，迁移成本很低。具体目录名和加载规则，建议在安装完成后查看工具的帮助信息。

5. Agent Skills 技能开发实战

5.1 SKILL.md 结构与规范

Agent Skills 的核心文件是 SKILL.md。它用 Markdown 描述一个技能的用途、触发条件和执行步骤。一个最小技能目录大概是这样的：

my-skill/ ├── SKILL.md └── scripts/ └── run.py

SKILL.md 的常见字段包括技能名称、描述、触发关键词和使用说明。下面是一个示例：

--- name: code-reviewer description: 对指定代码进行安全、性能和可读性审查，并输出结构化评审结果。 keywords: [code review, 代码审查, review] --- ## 执行步骤 1. 读取用户指定的文件或代码片段。 2. 按安全、性能、可读性、可维护性四个维度检查。 3. 每个问题标注严重级别：高/中/低。 4. 输出 Markdown 评审报告。 ## 注意事项 - 发现问题时给出具体行号和修改建议。 - 不修改代码，只输出评审结果。 - 涉及密钥、密码时只提示“疑似敏感信息”，不输出完整内容。

注意：不同版本对 SKILL.md 元数据的解析方式可能不同，上面是通用结构。写入后可以先让 Agent 做一个低风险任务，确认它是否真的加载了这个技能。

5.2 创建第一个技能：代码审查技能

先在技能目录里创建 code-reviewer 目录：

mkdir -p ~/.claude/skills/code-reviewer/scripts touch ~/.claude/skills/code-reviewer/SKILL.md

把上面示例的 SKILL.md 内容写入文件，然后在任意项目目录中启动 Claude Code，输入类似这样的任务：

请使用代码审查技能，审查当前项目里的 main.py

如果 Agent 正确加载了技能，它应该按 SKILL.md 中定义的四个维度输出评审结果，而不是随意给一个泛泛的代码评价。判断技能是否生效，就看输出格式是否与 SKILL.md 中的执行步骤一致。

5.3 在 Claude Code 中动态加载技能

除了让 Agent 自动决定是否使用技能，也可以更直接地指定。具体命令格式和触发方式在不同版本里有差异，有些版本支持在前缀用@技能名方式，有些版本则是在对话里说明“用 xx 技能做 xx”。更稳妥的做法是查看当前版本的帮助命令：

claude --help

以及查看技能相关命令：

claude skill --help

实际使用时，建议先用一句话任务验证加载，例如“用 code-reviewer 技能审查某个文件”，看输出是否严格遵循技能定义的步骤。如果是，说明技能链路是通的。

5.4 技能开发的三种常见形态

• 纯指令型技能：只有 SKILL.md，不依赖脚本，适合固定流程、固定输出格式的任务。
• 脚本增强型技能：SKILL.md + Python/Shell 脚本，适合需要读文件、调接口、处理数据的任务。
• 资源模板型技能：SKILL.md + references 目录，适合需要给 Agent 提供规范、示例、参考资料的场景。

从“会用 AI 到会开发 Agent”，关键就是学会识别一个任务是否值得被“技能化”。我的建议是：同一个任务出现三次以上，就值得做成技能。

6. Codex 与技能结合实践

6.1 Codex 的配置入口

Codex CLI 的配置文件通常放在用户目录下的.codex目录里，常见文件是config.toml。可以用以下命令确认：

codex --help

配置代码通常包含模型提供方、模型名称、API 鉴权方式等字段。下面是示意模板：

# 模型名称需要替换为你实际可用的模型 model = "your-model-name" model_provider = "openai"

如果你使用 OpenAI 兼容接口的其他模型服务，可以把 model_provider 替换为兼容提供方，并补充 base_url。具体可用字段以你安装版本的配置模板为准，不要直接复制后期望一定生效。

6.2 把 SKILL.md 思路移植到 Codex

Codex 也有自己的项目级指令文件机制，通常是在项目根目录放置一个说明文件，让 Agent 在每次任务中都参考它。这个机制和 Agent Skills 的核心思想是相通的：把固定规范外置，而不是每次重复输入。

移植时，可以把 SKILL.md 中的“执行步骤”和“注意事项”精简后合并到 Codex 的项目说明文件里，把可执行脚本留在 scripts 目录，由 Agent 按需调用。这样你在 Claude Code 里积累的技能，也能在 Codex 侧得到复用，只是文件形态需要按工具的约定调整。

6.3 Claude Code 与 Codex 的定位差异

两者不是二选一，更像一个组合：Claude Code 负责复杂推理和项目级分析，Codex 负责快速生成和脚本自动化。如果你的工作流同时使用两者，建议以同一套技能库为源，分别适配两侧的文件要求。

7. 接口 API 与批量任务设计

7.1 用 API 方式调用技能能力

Agent Skills 概念落地到工程化，最常用的是 API 方式。以 Claude API 为例，可以通过 Messages 接口传入包含系统指令和用户任务的请求。下面是通用 Python 调用框架：

import os import requests api_key = os.environ.get("ANTHROPIC_API_KEY") url = "https://api.anthropic.com/v1/messages" headers = { "x-api-key": api_key, "anthropic-version": "按官方文档填写当前版本", "content-type": "application/json" } # 把SKILL.md中的执行规则拼进system提示里 system_prompt = open("SKILL.md", encoding="utf-8").read() payload = { "model": "your-model-name", "max_tokens": 4096, "system": system_prompt, "messages": [ {"role": "user", "content": "审查这个函数的正确性：\ndef add(a, b):\n return a + b"} ] } response = requests.post(url, headers=headers, json=payload, timeout=120) print(response.json())

这段代码是通用模板，模型名称、接口版本、请求参数都需要按你实际使用的模型和 API 文档调整。它的意义在于演示“技能就是提示词 + 规则的组合”，拿到线上也能复用。

7.2 Codex CLI 的批量执行

Codex CLI 除了交互模式，通常还支持一次性执行模式。类似：

codex exec "为当前项目生成单元测试，按项目说明文件中的规范输出"

具体子命令名称以codex --help为准。如果支持 exec 模式，就可以写 Shell 脚本循环调用，实现批量任务。

7.3 批量任务队列设计

批量任务的关键，不是把一批请求同时打上去，而是让每个任务都独立、可追踪、可重试。推荐用一个输入目录装任务描述文件，跑完后把结果写进输出目录，并记录每个任务的状态。

batch-tasks/ ├── inputs/ │ ├── task-001.txt │ ├── task-002.txt │ └── ... ├── outputs/ ├── logs/ ├── run_batch.py └── task_status.json

下面是批量调用 Claude API 的示意脚本：

import os import json import time import requests from pathlib import Path INPUT_DIR = Path("batch-tasks/inputs") OUTPUT_DIR = Path("batch-tasks/outputs") OUTPUT_DIR.mkdir(parents=True, exist_ok=True) api_key = os.environ.get("ANTHROPIC_API_KEY") for task_file in sorted(INPUT_DIR.glob("*.txt")): task_text = task_file.read_text(encoding="utf-8") status = {"task": task_file.stem, "status": "running"} try: response = requests.post( "https://api.anthropic.com/v1/messages", headers={ "x-api-key": api_key, "anthropic-version": "按官方文档填写当前版本", "content-type": "application/json" }, json={ "model": "your-model-name", "max_tokens": 4096, "messages": [{"role": "user", "content": task_text}] }, timeout=180 ) response.raise_for_status() result = response.json() output_file = OUTPUT_DIR / f"{task_file.stem}.json" output_file.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") status["status"] = "done" except Exception as exc: status["status"] = "failed" status["error"] = str(exc) with open("batch-tasks/task_status.json", "a", encoding="utf-8") as f: f.write(json.dumps(status, ensure_ascii=False) + "\n") time.sleep(1)

这个脚本的核心设计点有三个：每个任务独立写文件、每步都捕获异常、状态随时落盘。即使中途某个任务失败，也不会影响后续任务，而且可以通过日志和状态文件定位失败原因。

7.4 失败重试建议

• 对暂时性网络错误，可使用指数退避重试，间隔从 1 秒、2 秒、4 秒递增。
• 对鉴权错误（401/403），不要盲目重试，先检查密钥和权限。
• 对超时错误，先调大请求超时时间，再考虑拆小任务。
• 批量任务建议先跑 2 到 3 个样本，确认输出格式稳定后再全量执行。

8. 资源占用与性能观察

8.1 本地资源占用

Claude Code 和 Codex CLI 本质上都是终端客户端，本地占用主要是 Node 运行时和会话内存，通常不会有 GPU 显存压力。实际占用受会话长度、插件数量、终端渲染影响，如果发现终端卡顿，先检查是否是会话历史过长或插件过多。

8.2 API 侧的性能指标

这类工具的“性能”主要看模型服务端的耗时和费用。需要重点观察三个指标：

• 响应延迟：从发出请求到拿到首个 token 的时间。
• Token 消耗：每次任务消耗的输入和输出 token 数，这直接决定成本。
• 并发限制：API 账户的速率限制，批量任务需要控制请求频率。

8.3 如何控制成本

• 把技能说明压缩到必要信息，减少输入 token。
• 优先用小模型处理简单任务，只有复杂推理才用大模型。
• 批量任务做样本测试后再全量跑，避免一次性产生大量无效输出。
• 日志里记录每个任务的 token 数，按周汇总，观察成本趋势。

这些和 GPU 显存调优的逻辑不同，但思路一样：先观察，再优化，不要凭感觉拍参数。

9. 常见问题与排查方法

下面表格覆盖从安装到调用的高频问题：