Agent Skills实战：构建跨Claude Code与Codex的可复用技能包

实际接手 Agent 开发后很多人会发现一个转折点会用 AI 写 prompt和能把 AI 变成稳定执行任务的 Agent中间隔着一层能力封装。Agent Skills 正是这一层封装的重要组成部分。简单说Agent Skills 是一套可复用的技能包它把某个场景下的指令、流程、脚本和模板打包起来让 Claude Code、Codex 这类命令行 Agent 在遇到对应任务时不再从空白对话开始而是按预设流程执行。下面所有示例都偏向最小闭环读者可以在自己的项目里按需替换。1. 先理解 Agent 与 Agent Skills 的边界在动手安装工具和写技能之前先把概念边界弄清楚否则很容易把 Agent Skills 做成一个普通的 Markdown 文件既看不出效果也找不到维护价值。1.1 Agent 不是聊天机器人而是有工具使用能力的执行体聊天机器人的核心能力是“生成文本”输入一段问题输出一段回答。Agent 则是在文本生成能力之上增加了“感知环境、拆解任务、调用工具、观察结果、调整计划”的执行循环。一个典型执行循环可以拆成四步收到目标例如“把项目里所有 TODO 按优先级整理成文档”。拆解计划先找出 TODO 出现在哪些文件再判断优先级规则再决定输出格式。调用工具用 grep 搜索文件用 cat 查看上下文用脚本统计数量最后写入文档。观察反馈读取命令执行结果判断是否完成如果没有完整覆盖继续补充处理。关键区别在于“行动 反馈”。聊天机器人只能给出建议Agent 可以直接读取项目文件、执行命令、修改代码。Claude Code 和 Codex 之所以被称为 Agent就是因为它们具备这些工具调用能力而不是简单地在终端里模拟对话。1.2 Agent Skills 是给智能体补充的可复用能力包Agent Skills 是一组“能力文件”的集合通常包括说明文档、示例、脚本和模板。它的作用不是写一段 prompt而是把某个场景下的完整操作手册打包给 Agent。可以把它理解成给新员工的操作手册而不是一句“好好干活”的叮嘱。操作手册里会写明什么情况下使用这个技能。执行这个技能需要哪些前置条件。操作分几步每一步做什么。哪些命令可以复用哪些文件需要修改。输出结果长什么样怎么验证成功。Agent 在对话中遇到匹配任务时会读取这份操作手册再结合当前项目上下文执行。直接给 Agent 写 prompt 也能完成一次任务但缺点非常明显每次都要重复描述流程团队里不同人的写法不一致沉淀不了经验。Skill 把流程固化成文件可以跨项目复用可以用 Git 管理版本可以像代码一样评审和测试。1.3 Claude Code 与 Codex 在技能体系里承担什么角色Claude Code 是 Anthropic 推出的终端开发 Agent能够在代码库中完成多步开发任务。较新的版本会读取项目级或用户级技能目录中的技能文件只要技能目录和说明文件符合约定Claude Code 就能在对话中自动加载。Codex 是 OpenAI 推出的命令行开发 Agent更偏向代码生成、仓库理解和自动化修改。它的项目上下文通常依赖 AGENTS.md 这类指令文件同时可以直接执行外部命令或脚本。在技能体系里这两个工具都扮演“执行器”角色Agent 负责理解用户意图。技能负责定义“遇到什么任务走什么流程”。脚本和模板负责承载具体能力。执行器负责把流程变成实际命令。所以设计技能时尽量不要让技能文件依赖某一个 Agent 的私有能力。技能的核心应该是一段清晰的任务说明和一个可执行的脚本入口。这样同一份技能就能在 Claude Code、Codex甚至其他支持自定义指令的 Agent 工具之间复用。2. 环境准备装好 Claude Code 与 Codex并验证可用要跑通后面的技能示例先把两个命令行 Agent 装好。这部分的坑其实比技能本身更多尤其是路径问题和版本问题经常让技能在一个工具上正常、在另一个工具上报错。2.1 安装 Claude Code 的两种常见方式Claude Code 依赖 Node.js 环境建议先确认本机 Node.js 版本在 18 以上。如果版本过低安装过程可能成功但运行时会出现语法或兼容性错误。常见安装方式是使用 npm 全局安装npm install -g anthropic-ai/claude-code也可以使用官方提供的原生安装脚本或系统包管理器具体命令以官方文档为准因为安装方式会随版本迭代变化。安装完成后先不要急着进入对话先验证一下可执行文件是否在 PATH 中claude --version如果能输出版本号说明安装成功。如果提示command not found通常是 npm 全局目录没有加入 PATH。2.2 安装 Codex 和第一道常见报错Codex 同样可以通过 npm 安装npm install -g openai/codex也可以使用 Homebrew、包管理器或官方二进制包安装。安装完成后再验证codex --version很多人在 IDE 插件里遇到的第一个报错是Unable to locate the codex CLI binary. Set codex CLI path or ensure the executable is in your PATH.这个错误并不是技能问题而是插件无法定位到 codex 可执行文件。常见原因有三个Codex 没有真正安装成功。安装成功但 npm 全局目录不在 PATH。IDE 插件没有被允许读取终端环境变量需要手动配置路径。这一节先记住这个错误第五节会给出完整排查链路。2.3 用版本命令验证两个工具安装完成后建议用一组命令做环境检查claude --version codex --version which claude which codex预期情况如下命令作用正常结果claude --version验证 Claude Code 是否可执行输出版本号codex --version验证 Codex 是否可执行输出版本号which claude查看 claude 可执行文件路径输出绝对路径which codex查看 codex 可执行文件路径输出绝对路径如果which没有输出路径说明可执行文件不在当前 shell 的 PATH 中。此时需要把 Node.js 全局安装目录加入环境变量或者在 IDE 中手动指定路径。2.4 在 IDE 中配置 Codex 路径如果使用 VSCode 或 Cursor 等编辑器里的 Codex 扩展除了命令行的 PATH还要注意 IDE 进程的环境变量不一定和终端一样。常见的做法是在 settings.json 中指定 codex 路径{ codex.cli.path: /usr/local/bin/codex, codex.cliPath: /usr/local/bin/codex }不同版本插件的配置键名可能不同有些使用codex.cli.path有些使用codex.cliPath。另一种更通用的做法是设置环境变量export CODEX_CLI_PATH$(which codex)然后在项目目录启动 IDE让 IDE 继承这个环境变量。环境检查清单Node.js 版本是否满足要求。Claude Code 是否输出版本号。Codex 是否输出版本号。claude 和 codex 的绝对路径是否可见。IDE 扩展是否正确读取到 codex 路径。3. 从零编写第一个可复用 Agent Skill环境准备好之后开始写第一个技能。这个技能选择“changelog-generator”功能是根据 Git 提交历史生成 changelog。它适合演示技能开发的完整链路因为流程清晰、输入输出容易验证而且不依赖外部服务。3.1 技能目录结构与命名规范在常见 Agent 技能体系中技能通常放在项目目录下的.claude/skills/或用户级技能目录中。技能名称建议使用小写字母和连字符例如changelog-generator避免使用空格和中文。一个最小技能目录结构如下.claude/skills/changelog-generator/ ├── SKILL.md ├── scripts/ │ └── generate_changelog.py └── templates/ └── changelog.md各文件职责如下文件作用SKILL.md描述技能名称、触发条件、执行步骤scripts/generate_changelog.py实现核心逻辑把提交记录整理成 changelogtemplates/changelog.md定义输出模板可选技能目录的名称、SKILL.md 中的 name 字段、description 描述要保持一致。Agent 通过 description 判断什么任务能触发这个技能如果 description 写得太模糊Agent 很可能不会调用它。3.2 写一个 SKILL.md 定义触发条件和使用说明SKILL.md 是技能的入口文件。常见结构包含 YAML frontmatter 和 Markdown 正文。frontmatter 提供元信息正文提供执行说明。示例内容如下--- name: changelog-generator description: 根据 Git 提交记录生成标准化的 CHANGELOG.md适合在发版前整理变更记录时使用。 --- # Changelog Generator ## 适用场景 需要把当前分支相对目标分支的提交记录整理成 changelog 时使用。 ## 执行步骤 1. 确定目标分支默认是 main。 2. 运行脚本读取提交记录。 3. 按 Features、Bug Fixes、Documentation、Other 对提交分组。 4. 将结果输出到 stdout由执行者决定是否写入 CHANGELOG.md。 ## 依赖 - git - python3 ## 使用示例 用户说生成当前分支的 changelog。 执行者运行 python .claude/skills/changelog-generator/scripts/generate_changelog.py main这里的关键点是 description。它应该描述“什么任务会用到这个技能”而不是描述技能内部实现。Agent 拿到用户请求后会把请求语义和所有技能的 description 做匹配。描述里最好出现“生成 changelog”“发布说明”“变更记录”等具体场景词。3.3 用 Python 脚本实现核心逻辑技能的核心逻辑放在脚本里而不是全部写进 SKILL.md。这样既方便测试又能让 Agent 通过一次命令拿到结构化结果。示例脚本#!/usr/bin/env python3 Generate a changelog from git commit messages. import subprocess import sys from collections import defaultdict def get_commits(base: str) - list[str]: cmd [git, log, f{base}..HEAD, --prettyformat:%s] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: print(result.stderr, filesys.stderr) sys.exit(1) return result.stdout.splitlines() def group_commits(commits: list[str]) - dict[str, list[str]]: groups defaultdict(list) for commit in commits: lower commit.lower() if lower.startswith((feat, feature, add)): groups[Features].append(commit) elif lower.startswith((fix, bug, patch)): groups[Bug Fixes].append(commit) elif lower.startswith((docs, doc)): groups[Documentation].append(commit) else: groups[Other].append(commit) return groups if __name__ __main__: base sys.argv[1] if len(sys.argv) 1 else main commits get_commits(base) if not commits: print(No commits found.) sys.exit(0) output [# Changelog, ] grouped group_commits(commits) for section in [Features, Bug Fixes, Documentation, Other]: if section in grouped: output.append(f## {section}) output.extend(f- {item} for item in grouped[section]) output.append() print(\n.join(output))脚本把结果打印到 stdout而不是直接修改文件。这个设计是刻意的让 Agent 决定最终如何写入文件而不是脚本擅自覆盖项目内容。本地可以直接验证脚本python3 .claude/skills/changelog-generator/scripts/generate_changelog.py main如果当前分支相对 main 没有提交输出为No commits found.。如果有提交输出就是格式化后的 changelog。3.4 在 Claude Code 中加载并测试技能进入项目目录启动 Claude Codecd /path/to/project claude在对话中输入请使用 changelog-generator 技能比较 main 分支和当前分支生成 changelog 内容。如果技能被正确加载Claude Code 会读取 SKILL.md然后调用脚本并整理结果。不同版本的界面提示不一样有些会显示正在使用的技能名称有些不会显示但最终输出应该符合预期。如果 Claude Code 没有调用技能先检查技能目录是否在正确位置。SKILL.md 文件名是否准确。frontmatter 是否包含 name 和 description。description 是否包含“changelog”等触发词。当前 Claude Code 版本是否已升级到支持技能功能的版本。4. 让同一份技能跑在 Codex 上技能在一个 Agent 上跑通只是第一步。如果希望一份技能在 Claude Code 和 Codex 上都可用需要理解这两个工具读取上下文的方式差异然后做一个“低耦合”的技能设计。4.1 Codex 与 Claude Code 对技能加载机制的不同Claude Code 通过技能目录和 SKILL.md 来组织技能遇到匹配任务时主动加载。Codex 并不完全等价于 Claude Code 的 SKILL.md 机制。Codex 更依赖项目级指令文件典型的是 AGENTS.md。AGENTS.md 会在 Codex 处理项目任务时被当作项目上下文读入里面可以写明项目规范、可用命令和推荐工作流。所以想让一份技能在两个工具上复用不建议只写一套私有格式而是采用下面这种统一思路把“做什么、什么时候做”写进 SKILL.md同时压缩成 AGENTS.md 中的一小段指令。把“具体怎么做”全部封装到脚本里。让 Agent 通过运行脚本来获得技能能力而不是依赖某一种工具内置的技能渲染机制。这种做法牺牲了一点自动化程度但换来了跨工具的一致性和可测试性。4.2 用 AGENTS.md 和入口脚本统一技能调用在项目根目录创建 AGENTS.md# 项目指令 ## Skill: changelog-generator 当用户要求“生成 CHANGELOG”“整理发布说明”或“查看本次变更记录”时使用 changelog-generator 技能。 执行方式运行以下脚本并读取 stdout再把结果整理给用户。 python .claude/skills/changelog-generator/scripts/generate_changelog.py main这样 Codex 在收到相关请求时可以从 AGENTS.md 中读到技能入口然后运行脚本。这里有一个重要的设计原则指令只描述“目标”和“执行命令”不描述“必须用 Codex 的某个内部功能”。这样即使后续切换 Agent 工具技能本身也不需要重写。4.3 通过 CLI 一次性会话运行技能Codex 支持通过命令行启动一次性任务。可以在非交互模式中直接让 Codex 读取 AGENTS.md 并执行技能。示例codex exec 生成当前分支的 CHANGELOG.md使用 changelog-generator 技能并把结果保存到 CHANGELOG.md如果当前 Codex 版本支持交互模式也可以直接运行codex然后在对话中写出同样需求。运行后 Codex 会读取项目上下文找到 AGENTS.md 中关于技能的说明再运行脚本并把 stdout 内容整理成最终输出。4.4 验证 Codex 执行结果技能跑完后不能只看终端输出还要确认实际效果。检查点包括脚本退出码是否为 0。CHANGELOG.md 是否生成。内容是否包含当前分支相对 main 的提交。提交分组是否符合 SKILL.md 中定义的规则。是否出现重复内容或误覆盖已有文件。可以用命令快速确认git status --short cat CHANGELOG.md如果 CHANGELOG.md 没有任何内容可能是脚本运行时没有拿到提交记录。这时先手动运行脚本排除脚本本身的问题再检查 Agent 是否正确执行了命令。5. 常见错误排查安装、路径与执行器问题Agent Skills 的报错往往不在技能本身而在工具链。下面几类问题是社区里最常见的排查时可以按顺序处理。5.1 unable to locate the codex CLI binary路径问题错误现象Unable to locate the codex CLI binary. Set codex CLI path or ensure the executable is in your PATH.这个错误说明某个程序需要调用 codex但找不到可执行文件。检查步骤which codex echo $PATH ls -l $(which codex)如果which codex没有输出说明 codex 不在 PATH 中。先手动安装或重新安装。如果which codex有输出但插件仍然报错可能是 IDE 启动时的环境变量和终端不一致。处理方式export CODEX_CLI_PATH$(which codex)或者在 IDE 设置中手动指定 codex 可执行文件路径。注意修改环境变量后必须重启终端和 IDE而不是只打开一个新的终端标签页。5.2 The agent execution provider did not respond in time执行超时错误现象The agent execution provider did not respond in time. This may indicate the agent took too long to complete.这个错误通常出现在 Agent 执行脚本或等待外部响应超时的时候。常见原因脚本在等待用户输入命令一直挂起。脚本执行时间太长超过执行器限制。外部 API 或网络请求没有设置超时。任务拆得过大Agent 在一次执行里做了太多事。排查第一步是手动运行脚本看是否卡住。例如time python .claude/skills/changelog-generator/scripts/generate_changelog.py main如果脚本本身执行很快问题可能在 Agent 对任务的规划上。可以尝试把任务拆小让 Agent 先读取提交记录再生成文件最后单独验证内容。5.3 model not recognized模型名不匹配错误现象示例deepseek-v4-pro is not a model this version of claude code recognizes这是配置中的模型名没有被当前版本的 Claude Code 识别。可能原因环境变量里指定了错误的模型名。使用了某个上游供应商的模型名但没有同步到 Claude Code 的模型列表中。Claude Code 版本较旧不认识新模型名。检查方式env | grep -i claude env | grep -i anthropic重点检查ANTHROPIC_MODEL、CLAUDE_CODE_MODEL等变量。如果设置了不确定的模型名先取消它恢复默认模型再试。注意模型名是跟随工具版本和提供方能力变化的不要把一个网络教程里的模型名直接复制到生产配置里。落地前先确认当前工具版本支持哪些模型。5.4 技能不生效时的通用排查顺序如果技能文件位于正确位置、脚本也能手动执行但 Agent 就是不调用技能按下面的顺序检查技能目录是否在正确路径。项目级一般在.claude/skills/下用户级则在用户技能目录。SKILL.md 文件名是否正确大小写是否敏感。frontmatter 是否包含 name 和 description。description 中是否包含足够具体的触发词。对话中是否明确提到了技能描述里的场景。技能脚本是否具有可执行权限解释器是否存在。工具版本是否过旧是否支持当前技能格式。是否同时存在多个同名技能导致 Agent 选择冲突。排查时建议先在对话中直接说“请使用 xxx 技能”而不是等待 Agent 自己猜测。如果显式指定后仍不生效问题大概率在技能文件本身而不是触发匹配。问题现象常见原因检查方式处理建议技能不加载目录或文件名错误检查.claude/skills/结构调整目录命名技能不匹配description 太模糊检查 skill 元信息增加场景触发词脚本报错缺少依赖或路径错误手动运行脚本补依赖、用绝对路径工具不识别模型模型名不在列表中查看版本和配置升级工具或修正模型名6. 设计可复用、可扩展的 Agent 技能体系技能如果只是散落在各个项目里时间一长会变成新的“文档债务”。真正有用的是一套能持续维护的技能体系。6.1 三类技能通用技能、项目技能、临时指令不是所有能力都适合做成技能。按照复用频率和维护成本可以把任务分成三类类型特点示例维护方式通用技能跨项目可复用流程稳定changelog-generator、code-review、dependency-audit统一放入技能库按版本管理项目技能只服务于某个项目或团队内部工具internal-api-client、deploy-checklist放在项目目录随仓库维护临时指令一次性任务不具备复用价值“帮我看看这个文件哪里有问题”不用固化直接用 prompt判断标准很简单如果同样的任务下个月还会出现才值得做成技能如果只是一次性调研或探索不要过早抽象。6.2 技能命名、版本、依赖与文档规范技能命名建议使用“动作 对象”的结构例如changelog-generatorcode-review-runnerdependency-auditorapi-doc-builder命名要小写使用连字符避免特殊字符。版本管理可以从两个层面做在技能目录中放一个VERSION文件或README.md中记录版本。把技能库整体纳入 Git用 commit 或 tag 管理变更。依赖信息必须写在 SKILL.md 中包括运行脚本所需的解释器、外部命令和系统要求。否则换一台机器后技能可能静默失败。一个技能库的推荐结构skills/ changelog-generator/ SKILL.md scripts/ tests/ README.md VERSION code-review-runner/ SKILL.md scripts/ tests/ README.md VERSION每个技能都带 tests 和 README可以让其他协作者快速理解技能用途也能在 CI 中自动验证脚本没有跑挂。6.3 从技能库到多人协作目录与审核多人协作时技能库应该像代码库一样管理。推荐做法建立一个中央技能库仓库。每个技能一个目录通过 PR 提交新增或修改。新增技能必须包含 SKILL.md、脚本、测试示例和 README。评审时重点检查命令是否可执行、是否硬编码密钥、是否可能破坏环境、是否跨工具可用。团队成员把技能库 clone 到本地再通过 symlink 或脚本将技能目录同步到技能目录。不要直接让每个人在本地随意新建技能。没有审查的技能可能包含危险命令尤其在 Agent 自动执行脚本的环境里风险会被放大。6.4 哪些任务值得做成 Skill适合做成技能的任务通常具备以下特征流程稳定重复出现。输入输出可定义。结果可以被验证。可以通过脚本或命令自动完成大部分工作。典型适合场景根据提交信息生成 changelog。对变更代码执行静态检查。扫描依赖版本并输出安全报告。根据接口定义生成文档。按团队规范生成代码骨架。不适合做成技能的场景高度依赖实时决策。需要大量人工审美和判断。任务本身只出现一次。无法用明确标准判断成功失败。建议每新增一个技能前先问一个问题如果三个月后这个任务不再出现我还会为它写技能吗如果答案是否定的就不要做。7. 最佳实践与下一步技能体系能跑起来只是第一步能长期稳定运行才是目标。最后一部分整理工程实践、学习路径和学习环境与生产环境的关键差异。7.1 编写 Agent Skill 的工程建议以下建议来自实际项目中使用 CLI Agent 的经验可以直接用到技能开发中。不要在高频技能脚本里硬编码密钥或访问令牌。密钥通过环境变量注入技能库提交时排除.env。技能脚本默认只输出 stdout不要擅自修改文件。这样 Agent 可以先检查结果再由用户确认是否落盘。每个技能都要在 SKILL.md 中写明“预期输出”和“验证方式”。没有验证方式的技能很难排查问题。脚本执行要设置超时避免 Agent 长时间挂起。内部脚本遇到外部请求时显式设置 timeout。SKILL.md 中的指令不要绑定具体 Agent 的私有能力。只描述目标和可执行命令保留跨工具迁移能力。为每个技能准备一个最小测试用例。脚本错误最好在本地直接发现不要等 Agent 执行时才发现。技能库纳入版本控制变更走代码评审避免出现不可追溯的“万能脚本”。7.2 从会用 AI 到会开发 Agent 的练习路径建议按下面的顺序练习而不是一开始就写一个庞大的技能库。先用 Claude Code 在现有项目里完成一个小任务观察它如何读取文件、调用命令、修正错误。写一个最小 SKILL.md让 Agent 根据 Git 提交输出 changelog。把同一个技能迁移到 Codex通过 AGENTS.md 或 CLI 验证执行。把两三个技能放入独立技能库给每个技能补充测试用例。选择团队中重复出现的工作流抽象成技能发布评审后使用。完成第 4 步基本就形成了“遇到任务 - 选择技能 - 执行脚本 - 人工检查”的稳定工作流。这个工作流的价值在于即使换了新的 Agent 工具技能资产仍然可以继续使用。7.3 学习环境与生产环境要分开验证学习环境可以随便创建技能、随意调整脚本但生产环境必须有一套更严格的标准。学习环境使用个人项目权限范围小。技能脚本可以快速迭代。不存在敏感数据共享问题。生产环境技能脚本执行前要评估对文件系统的影响。Agent 生成的代码必须经过 review。密钥通过环境变量或密钥管理服务注入。技能脚本要有日志方便定位失败原因。版本变更要有回滚方案避免新技能把原有工作流破坏。技能库只允许通过审查的 PR 合入禁止个人直接推送脚本。注意Agent 自动执行脚本的能力越强越要约束技能脚本的行为。不要写一个“删除全部未跟踪文件”的技能除非你明确知道它会作用于哪个目录。如果能把“技能定义”和“具体执行”分离再配合版本管理和环境隔离Agent Skills 就会成为一种长期有效的能力资产。下一步最有价值的练习不是收藏更多技能而是把自己最常做的三件事固化成技能并让它们在 Claude Code 和 Codex 上都能跑通。