这次我们来看一个直接把两个词串起来的方向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以 SKILL.md 为入口的可复用技能包配套工具Claude Code、Codex CLI、VSCode 扩展、API 服务技能组成SKILL.md 脚本 模板 参考资料 配置技能存放用户级技能目录 / 项目级技能目录调用方式对话内指定、斜杠命令、自动关键词触发、API 动态加载是否支持批量任务支持可通过脚本循环调用 Agent 或 API 接口硬件门槛终端工具为主无固定 GPU 要求实际看模型服务端是否需要 API Key需要Claude Code 用 Anthropic 账号Codex 用 OpenAI 账号适合人群开发者、技术负责人、AI 产品工程师、自动化爱好者这里要单独说明一点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 和 LinuxWindows 上更推荐通过 WSL 或原生终端环境运行。无论哪一条路线先确认本机有可用的 Node.js 运行环境和包管理器。Node 版本建议使用当前官方维护中的 LTS 版本具体以工具安装提示为准。3.2 需要准备的账号Anthropic 账号用于 Claude Code 登录或者准备 Anthropic API Key。OpenAI 账号用于 Codex CLI 登录或者准备 OpenAI 兼容接口的 API Key。如果使用的是第三方模型网关或代理服务只要接口兼容通常也可以配置。3.3 通用检查清单在开始安装之前按下面清单检查一遍检查项说明Node.js已安装能执行node -vnpm / pnpm / yarn能正常安装全局包Git便于后续管理技能库终端macOS/Linux 用自带终端Windows 用 WSL 或 PowerShellAPI Key提前创建并保存好不要写进代码仓库网络能正常访问模型服务商的 API 端点这一步看起来琐碎但绝大多数“装不上”“启动失败”的问题最后都能追溯到 Node 版本或网络设置。4. 安装部署与启动方式4.1 安装 Claude CodeClaude Code 最常见的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在终端里进入一个项目目录执行claude首次运行会引导你登录 Anthropic 账号或者把 API Key 写入环境变量。成功进入对话界面后说明基础安装完成。如果你想在 VSCode 里使用可以安装 Claude Code 的编辑器插件安装后会在侧边栏或终端面板里多出 AI 会话入口。具体入口位置和界面在不同版本之间略有差异以插件说明为准。4.2 安装 Codex CLICodex 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/codexCODEX_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 codex4.4 准备技能目录技能可以放在用户级目录这样所有项目都能用也可以放在项目级目录跟随项目走。先创建用户级技能目录mkdir -p ~/.claude/skills如果你在项目里使用可以在项目根目录创建mkdir -p .claude/skillsCodex 的自定义指令和技能组织方式不完全等同 Claude Code但只要遵循“说明文件 脚本 参考资源”的思想迁移成本很低。具体目录名和加载规则建议在安装完成后查看工具的帮助信息。5. Agent Skills 技能开发实战5.1 SKILL.md 结构与规范Agent Skills 的核心文件是 SKILL.md。它用 Markdown 描述一个技能的用途、触发条件和执行步骤。一个最小技能目录大概是这样的my-skill/ ├── SKILL.md └── scripts/ └── run.pySKILL.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 思路移植到 CodexCodex 也有自己的项目级指令文件机制通常是在项目根目录放置一个说明文件让 Agent 在每次任务中都参考它。这个机制和 Agent Skills 的核心思想是相通的把固定规范外置而不是每次重复输入。移植时可以把 SKILL.md 中的“执行步骤”和“注意事项”精简后合并到 Codex 的项目说明文件里把可执行脚本留在 scripts 目录由 Agent 按需调用。这样你在 Claude Code 里积累的技能也能在 Codex 侧得到复用只是文件形态需要按工具的约定调整。6.3 Claude Code 与 Codex 的定位差异对比维度Claude CodeCodex CLI主要生态Anthropic Claude 生态OpenAI 生态及兼容接口技能机制Agent SkillsSKILL.md 为核心项目说明文件 配置自定义指令适合任务深度代码分析、多步骤项目级改造代码生成、自动化脚本、工具链配合社区现象技能库和教程增长快配置灵活兼容生态较广两者不是二选一更像一个组合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, encodingutf-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, headersheaders, jsonpayload, timeout120) 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(parentsTrue, exist_okTrue) api_key os.environ.get(ANTHROPIC_API_KEY) for task_file in sorted(INPUT_DIR.glob(*.txt)): task_text task_file.read_text(encodingutf-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}] }, timeout180 ) response.raise_for_status() result response.json() output_file OUTPUT_DIR / f{task_file.stem}.json output_file.write_text(json.dumps(result, ensure_asciiFalse, indent2), encodingutf-8) status[status] done except Exception as exc: status[status] failed status[error] str(exc) with open(batch-tasks/task_status.json, a, encodingutf-8) as f: f.write(json.dumps(status, ensure_asciiFalse) \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. 常见问题与排查方法下面表格覆盖从安装到调用的高频问题问题现象可能原因排查方式解决方案claude命令找不到npm 全局目录未加入 PATH执行npm ls -g --depth0把 Node 全局 bin 目录加入 PATHcodex命令找不到未安装或 PATH 未配置执行which codex重新安装或配置环境变量提示 unable to locate the codex cli binary图形客户端找不到 CLI 可执行文件执行which codex确认路径设置CODEX_CLI_PATH为 codex 实际路径启动后一直要求登录但登录失败网络或账号问题查看启动日志检查网络设置确认账号可正常登录API 请求返回 401密钥错误或权限不足检查环境变量和账号权限重新创建并配置 API Key技能目录创建后 Agent 不识别目录路径错误或命名不规范检查技能目录位置和命名放到正确目录并重启会话Agent 没有按技能步骤输出技能加载失败或描述不清晰在对话中明确指定技能名优化 SKILL.md 描述明确执行步骤模型版本不识别工具版本与模型名不匹配查看当前工具支持的模型列表更换模型名或升级工具版本批量任务中途卡住单任务超时或速率限制查看状态文件和日志增加重试