Agent Skills实战：用Claude Code和Codex打造可复用AI技能

这次我们来看一个比“用 AI 写提示词”更值得投入的方向把 AI 能力沉淀成可以反复调用的Agent Skills。如果你现在已经能用 Claude、ChatGPT 这类工具完成日常问答和代码生成但每次遇到相似任务还要重新组织提示词、重新描述上下文那么 Agent Skills 就是解决这个重复劳动的思路之一。Agent Skills 的核心并不复杂它不是一套新的编程语言也不是一个必须重写业务代码的框架而是一种“给智能体扩展专业能力”的组织方式。你把自己的工作流、判断规则、脚本工具打包成一个技能文件让 Agent 在遇到对应任务时自动读取并执行。本文会用 Claude Code 和 Codex 两个主流 AI 编程工具做载体从环境准备、技能目录结构、示例技能创建到跨 Agent 复用和批量任务封装完整走一遍。文章会包含可直接复制的 SKILL.md 示例、技能脚本示例和批量调用代码也会把最容易踩的坑整理成排查表格。适合已经会使用 AI 编程工具、想进入 Agent 开发的技术读者。先说明一下技能机制在不同的 CLI 版本中实现细节会有差异本文的结构和示例可用于日常工程实践但具体参数请以你本机--help输出和官方文档为准。1. 核心能力速览能力项说明核心理念把专业技能封装成“技能包”Agent 按需调用技能载体SKILL.md 指令文件 可执行脚本 资源文件主要工具Claude Code、Codex CLI 等支持自定义技能的 AI 编程工具典型结构项目级 skills 目录、用户级技能目录运行环境需要安装 Node.js 及对应 CLI通常使用云端模型不需要本地 GPU是否支持批量任务支持可以将技能封装为脚本后批量调度是否支持 API 接入技能本身是本地脚本可自行封装为服务可扩展方向代码审查、文档生成、日志分析、资料整理、CI 流程集成适合读者会写提示词、想进一步开发 Agent 的技术人员从能力边界来看Agent Skills 最适合“流程稳定、判断规则明确、需要频繁执行”的任务。它不是一个通用 Agent 框架也不是模型训练工具而是一层轻量的“技能编排”方案。真正复杂的工作流建议结合团队的工程体系来设计。2. 适用场景与使用边界先聊适用场景。我建议优先考虑用 Agent Skills 处理以下几类任务第一类是代码质量类任务比如按团队规范做代码审查、检查敏感信息是否泄露、扫描未处理的异常分支第二类是文档和知识整理类任务比如把零散的技术笔记整理成结构化文档、把接口报错日志归类并生成排查手册第三类是重复性较高的文件批量处理比如批量检查配置文件、批量转换格式、批量生成周报。这些任务的共同特点是判断标准相对明确输入输出可以结构化并且不需要 Agent 频繁进入“自由创作”状态。不合适的场景同样需要说清楚。如果任务要求毫秒级响应比如在线接口的实时鉴权那让 Agent 走一遍“技能读取 模型推理 脚本执行”的开销是不可接受的如果任务涉及高风险的自动变更比如直接删除数据库表、发布生产环境、修改线上权限也不要让 Agent 自动执行哪怕技能写得再完整也不行。Agent Skills 适合“辅助决策”和“半自动执行”不该成为“无人值守的变更工具”。使用边界方面有几点必须强调第一不要把 API Key、数据库密码、内部系统 Token 写进技能文件或脚本中技能文件经常会随仓库分发一旦泄露就是安全事故第二用 Agent 辅助生成代码时要留意开源许可证不要让模型生成与商业产品高度相似的代码也不要让 Agent 自动复制未经授权的代码片段第三如果技能里涉及用户数据、音频、图片、个人敏感信息需要在受控环境中处理且确保取得合法授权第四Claude Code 和 Codex 的服务条款需要在商用场景下重新确认不同账号类型的调用限制和商业化策略不完全一样。3. 环境准备与前置条件在创建第一个 Agent Skill 之前先确认本机环境。两个 CLI 工具都依赖 Node.js比较稳妥的做法是安装 Node.js 18 或更高版本。可以用下面命令快速检查环境node -v npm -vClaude Code 的常见安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后运行claude --version确认版本。Codex 的安装方式同样以官方文档为准常见是通过 npm 或安装脚本完成npm install -g openai/codex安装后运行codex --version验证。两个工具安装完成后都需要先登录或配置模型服务的访问凭证。Claude Code 通常会在首次启动时引导登录Codex 也需要配置对应的 API 访问方式。这里的细节在不同版本里差异较大不要凭记忆猜测建议直接看首次启动时的提示。建议为技能开发单独建立一个工作目录避免把测试项目和真实项目混在一起。目录结构可以参考下面这样agent-skills-lab/ ├── my-claude-project/ │ ├── .claude/ │ │ └── skills/ │ │ └── demo-skill/ │ │ ├── SKILL.md │ │ └── run.py │ └── inputs/ └── my-codex-project/ └── AGENTS.md开发过程中我会用到 Bash、Python 和 Markdown确保这些基础环境已经就绪。Linux 和 macOS 环境通常自带 PythonWindows 建议使用 PowerShell 或者安装 WSL避免脚本路径和权限问题影响测试。4. Agent Skills 的核心概念与目录结构先理解 Agent Skills 的底层逻辑。它的设计思路是把“告诉 AI 怎么做”和“让 AI 真正执行”两件事拆开。一个技能包由三部分构成指令文件通常是 SKILL.md包含技能的用途、触发条件和执行步骤可执行脚本负责真正完成计算、文件处理、命令调用等操作资源文件技能运行所需的模板、配置、参考文档等。SKILL.md 是技能的核心入口。文件顶部有一段 YAML 格式的 frontmatter常见字段是name和description。name是这个技能的唯一标识description决定了 Agent 在什么时候触发这个技能。描述写得越具体Agent 的命中率越高。比如“当用户要求执行代码规范检查时使用本技能”就比“代码检查工具”更容易被触发。下面是一个技能包的结构示例my-project/ ├── .claude/ │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ └── review.py └── src/ └── main.py在 Claude Code 中项目级技能通常放在.claude/skills/目录下用户级技能通常放在当前用户主目录下的 skills 目录中。不同版本的 CLI 对技能目录的配置方式可能不同启动后可以运行claude --help或在会话中输入/help查看技能相关命令。Codex 这边项目级指令通常通过AGENTS.md文件提供后面我会单独说明如何把 Claude Code 的技能内容迁移到 Codex 的指令体系里。需要特别注意SKILL.md 的质量决定了 Agent 行为的稳定性。不要再把它理解成一个“提示词文件”它更像是给 Agent 看的函数文档包括函数用途、参数说明、执行步骤、输出格式、禁止事项。只有把这一层写清楚Agent 才不会在调用脚本时自由发挥。5. 实战创建一个可复用的代码审查技能现在开始创建一个示例技能。这个技能的作用是对指定 Python 文件做基础规范检查输出问题清单。它不追求覆盖所有审查规则重点是演示完整的技能包结构和 Agent 调用链路。先创建技能目录mkdir -p my-project/.claude/skills/code-review然后创建SKILL.md--- name: code-review description: 使用项目代码规范对指定 Python 文件进行静态审查输出问题级别、文件位置和修改建议。当用户要求“检查代码规范”“review 代码”“检查代码质量”时使用本技能。 --- # 代码审查技能 在收到代码审查请求时按以下步骤执行 1. 先运行 python review.py 目标文件路径 获取基础检查结果。 2. 结合检查结果和项目规范定位问题文件、行号和问题类型。 3. 输出必须包含问题级别严重/一般/建议、文件位置、问题描述、修改建议。 4. 只输出审查结果不要直接修改源代码。 ## 禁止事项 - 禁止在审查过程中执行可能修改文件内容的命令。 - 禁止把未确认的规则当作项目规范。接着创建review.py脚本。这里只做两个最简单的检查单行长度和常见调试打印语句import sys from pathlib import Path def check_line_length(path: Path) - list: issues [] for line_no, line in enumerate(path.read_text(encodingutf-8).splitlines(), 1): if len(line.rstrip()) 100: issues.append({ level: 建议, file: str(path), line: line_no, message: f单行长度超过 100 字符当前 {len(line.rstrip())}, }) return issues def check_debug_print(path: Path) - list: issues [] for line_no, line in enumerate(path.read_text(encodingutf-8).splitlines(), 1): if print( in line and def not in line: issues.append({ level: 严重, file: str(path), line: line_no, message: 发现疑似调试 print 语句请确认是否保留, }) return issues def main(): for raw_path in sys.argv[1:]: path Path(raw_path) if not path.exists(): print(f[错误] 文件不存在: {path}) continue issues check_line_length(path) check_debug_print(path) if not issues: print(f[OK] {path} 未发现基础规范问题) continue for issue in issues: print(f[{issue[level]}] {issue[file]}:{issue[line]} {issue[message]}) if __name__ __main__: main()然后把这个技能注册到 Claude Code。常见做法是把技能目录放在项目的.claude/skills/下。如果你希望技能全局可用可以放在用户级技能目录中。开发阶段建议放在项目目录里避免影响其他项目。启动方式cd my-project claude进入 Claude Code 会话后直接说“请检查 src/main.py 的代码规范”Agent 会读取code-review的 SKILL.md然后调用review.py完成检查。判断技能是否被正确调用的标准是输出中能看到脚本生成的行号定位信息并且 Agent 会按照 SKILL.md 规定的格式整理结果。如果 Agent 没有触发技能优先检查三个点技能目录名是否包含下划线或大小写问题、SKILL.md 的 frontmatter 是否完整、description中是否包含用户请求中的关键词。6. 在 Claude Code 中调用与验证技能技能创建好之后需要验证它是否真正生效。这里给出一套最小验证流程。第一步用空的测试项目启动 Claude Code避免历史上下文干扰cd my-project claude第二步输入一句非常明确的触发语句请检查 src/main.py 的代码规范使用 code-review 技能。观察 Agent 的回复。如果技能被调用你应该能在回复中看到脚本输出的问题列表包括文件路径、行号和问题描述。如果 Agent 只是按普通对话方式回答没有调用脚本说明技能没有注册成功或者描述匹配出问题了。第三步故意制造一个失败场景来验证技能的边界。例如在输入中要求“顺便把 review.py 里的 print 删掉”如果 SKILL.md 的禁止事项生效Agent 应该拒绝修改源码只输出审查结果。这一步很关键它能验证技能包是否真的约束了 Agent 行为而不仅仅是“给 AI 看了一段文字”。在开发阶段还可以打开 CLI 的详细日志模式观察 Agent 何时读取了 SKILL.md、何时执行了脚本。Claude Code 不同版本的日志查看方式有差异常见做法是在启动时开启 verbose 或 debug 参数具体以claude --help为准。如果脚本执行失败日志中通常能看到报错堆栈。最后需要强调的是技能描述不要写抽象要写具体。比如“处理用户请求”这种描述就不会触发而“当用户要求检查 Python 代码规范时触发输入是文件路径输出是问题列表”这种描述就容易命中。这里不是玄学而是 Agent 按照语义相似度匹配description字段描述越接近用户表达越容易被选中。7. 与 Codex 联合实现跨 Agent 技能迁移Claude Code 可以方便地注册技能但实际项目中很多团队会同时使用 Codex。把同一个技能迁移到 Codex 环境是有实际价值的。Codex 有自己的项目指令体系常见的是在项目根目录维护一个AGENTS.md文件里面写清项目结构、常用命令和编码规范。虽然 Codex 和 Claude Code 对“技能包”的底层实现不完全一样但迁移思路是通用的保留技能中的执行脚本把 SKILL.md 中的规则转换成 Codex 能理解的项目指令。一个简单的迁移流程分四步第一步保留脚本文件。把review.py放到项目中的固定位置比如tools/code-review/review.py。第二步在项目根目录创建AGENTS.md写入技能的核心规则# 项目指令 ## 代码审查 当用户要求代码审查时 1. 运行以下命令获取基础检查结果 python tools/code-review/review.py 目标文件路径 2. 输出格式必须包含问题级别、文件位置、问题描述、修改建议。 3. 只输出审查结果不要直接修改源代码。第三步在 Codex 中打开项目用与 Claude Code 中类似的语句触发审查请审查 src/main.pyCodex 会读取AGENTS.md找到“代码审查”这段指令然后按要求执行脚本。第四步对比两个 Agent 的执行差异。因为 Claude Code 和 Codex 的模型底层不同它们对指令的遵循程度会有所差异所以迁移后必须做一轮同样的验证用例不能默认“在 Claude Code 里能用在 Codex 里也一定正常”。这种跨 Agent 迁移的最大收益是脚本层完全复用规则层针对不同工具做少量改写。你不需要为每个 Agent 重写一遍业务逻辑只需要维护“脚本 描述”这套组合。如果以后团队换成其他支持类似机制的 Agent 工具迁移成本也远低于从零开始提示词工程。8. 批量任务与工具链接入Agent Skills 的另一个重要使用方向是批量任务。交互式对话适合做“单个任务深度处理”但如果你有 100 个文件要检查、50 个日志文件要归类最好的方式不是让 Agent 逐个对话而是把技能改写为命令行工具再用脚本批量调用。首先把技能脚本改造成支持命令行参数的标准入口。前面写的review.py已经支持传入多个文件路径这降低了批量调用的成本。真正的批量调度可以放在 Python 脚本里import subprocess import pathlib import time INPUT_DIR pathlib.Path(./inputs) OUTPUT_LOG pathlib.Path(./outputs/review_result.log) SCRIPT [python, .claude/skills/code-review/review.py] OUTPUT_LOG.parent.mkdir(parentsTrue, exist_okTrue) files sorted(INPUT_DIR.glob(*.py)) print(f共发现 {len(files)} 个待检查文件) for index, file in enumerate(files, 1): print(f[{index}/{len(files)}] 正在处理: {file}) start time.time() try: result subprocess.run( SCRIPT [str(file)], capture_outputTrue, textTrue, timeout60, ) elapsed time.time() - start with OUTPUT_LOG.open(a, encodingutf-8) as log: log.write(f### {file} ({elapsed:.2f}s)\n) log.write(result.stdout) if result.stderr: log.write(f[stderr]\n{result.stderr}\n) if result.returncode ! 0: print(f [FAIL] 返回码 {result.returncode}) else: print(f [OK] 用时 {elapsed:.2f}s) except subprocess.TimeoutExpired: print(f [TIMEOUT] {file} 超过 60 秒) with OUTPUT_LOG.open(a, encodingutf-8) as log: log.write(f### {file}\n[超时]\n) print(f批量检查完成结果写入 {OUTPUT_LOG})这个批量脚本的核心思想有三个记录日志、控制超时、失败不中断后续任务。真实项目中还要加上失败重试和进度恢复机制。比如记录已经处理的文件名下次启动时跳过已完成文件避免重复执行。如果要把技能接入自己的工具链可以考虑把它封装成 HTTP 服务。但这里有一个工程建议不要为了“接口而接口”去给技能包硬套 REST API。更好的做法是先保持命令行接口稳定然后在需要时用 FastAPI、Flask 或内部的任务队列把命令行包一层。这样技能本身的逻辑和部署方式是解耦的。接入 CI 时也一样。你可以在 GitLab CI 或 GitHub Actions 的某个阶段直接运行那个批量脚本把技能检查放到合并请求之前。这样 Agent 技能就从“开发者的交互工具”变成了“团队流水线的一部分”。9. 资源消耗与成本观察Agent Skills 不涉及显存但它同样有资源消耗而且这部分经常被忽略。主要消耗在三处模型请求次数、Token 输入量、脚本执行时间。SKILL.md 被 Agent 调用时会作为上下文注入到模型请求中。如果一个技能包描述写得过长每次调用都会增加输入 Token。因此 SKILL.md 要追求“够用但不冗余”。我在实践中的一个原则是凡是能写进脚本的确定性逻辑就不要写进 SKILL.mdSKILL.md 只负责描述触发条件和处理流程。这样可以减少模型负担也能提高执行稳定性。批量任务执行时要重点观察耗时和失败率。不要在循环里不加限制地调用 Agent。更稳妥的做法是先跑通最小样本再扩大批量范围。批量脚本要允许指定输入子集比如先处理前 5 个文件# 通过 start 和 limit 控制本次执行范围 start 0 limit 5 for file in files[start:start limit]: ...模型侧同样有速率限制。如果批量任务数量很大建议在脚本中加入并发控制或固定延迟。具体限流参数取决于你的账号类型不要硬编码一个很大的并发数否则会碰到 429 限流。日志是观察资源消耗最重要的手段。建议每个技能都输出运行日志包含调用时间、输入文件、返回码、耗时。这样你能发现问题脚本、慢脚本和反复触发的 Agent 行为也能估算整体成本。10. 常见问题与排查方法问题现象可能原因排查方式解决方案技能没有被触发SKILL.md 的 description 与用户请求不匹配或目录路径错误检查目录是否在.claude/skills/下确认 frontmatter 完整修改 description加入更多触发词和语义描述CLI 提示找不到 Codex 可执行文件Codex 未安装到 PATH或 IDE 扩展中 Codex CLI 路径配置错误运行codex --version确认可执行查看 IDE 扩展配置项安装 Codex 并确保二进制路径已加入 PATH或手动指定 CLI 路径Claude Code 不识别某个模型名当前 CLI 版本不支持配置中的模型名检查模型配置项对比当前 CLI 支持的模型列表升级 CLI 到新版本或在配置中改用受支持的模型名Agent 执行超时提示 provider 未及时响应模型响应慢、技能脚本执行时间过长、网络不稳定查看 CLI 日志确认是模型侧超时还是脚本执行超时调大执行超时优化脚本批量任务拆分为更小片段本地网络中间层异常导致 endpoint 请求失败本地中间层服务未启动、端口冲突或请求路由异常检查中间层服务状态确认请求是否能正常转发到模型服务重启中间层服务检查端口和请求配置确认当前 CLI 的 endpoint 配置脚本执行权限错误脚本没有执行权限或目录不可写运行python review.py test.py直接测试添加可执行权限或改用 python 方式调用批量任务中途卡住单个文件处理超时脚本没有超时控制查看批量脚本日志定位最后处理成功的文件在脚本中加入timeout参数和失败记录机制Agent 输出不规范SKILL.md 中对输出格式约束不够检查 SKILL.md 是否明确规定了输出模块结构在 SKILL.md 中增加输出格式示例和禁止事项这里要特别提醒如果遇到和“本地中间层、模型路由、endpoint”相关的报错优先检查本地服务是否正常、端口是否被占用、模型名是否正确而不是盲目修改系统配置。网络环境和请求路由的配置需要符合本机网络管理规范不要为了绕过限制做不合规的设置。11. 最佳实践与使用建议从“会用 AI”到“会开发 Agent”中间最重要的一步是养成“沉淀技能”的习惯。我的建议是把下面几条实践落到日常开发中。第一技能设计遵循单一职责。一个技能只做一件事并且把这件事做清楚。不要把“代码审查 文档生成 日志分析”塞进同一个 SKILL.md。技能包越专注description 越容易写准确Agent 触发后的行为也越稳定。第二SKILL.md 要包含“禁止事项”。很多初学者只写“做什么”不写“不做什么”。但 Agent 在复杂任务中往往容易过度延伸比如要求审查代码它却擅自修改了源码。禁止事项是约束 Agent 行为的重要机制。第三脚本优先于描述。凡是能确定的东西例如规则、格式、路径尽量写进脚本不要期待模型每次都能准确地从描述中推导出逻辑。脚本能力不足时再让模型补充分析和输出格式。这样既省钱又稳定。第四技能包要纳入版本管理。技能文件会随着项目演进发生变化需要记录变更历史。我建议把技能目录与项目代码放在同一个 Git 仓库里并在技能变更时提交清晰的 commit message。第五敏感信息零容忍。技能目录里不能出现任何凭据。如果你在开发中用到了临时 Token务必在提交前清理。还可以在.gitignore中加入技能目录下的临时配置文件防止误提交。第六发布和商用前要做人工复核。Agent 生成的结果可能存在看似合理但实际错误的内容尤其是在代码审查和文档生成场景中。不要直接把 Agent 输出当成最终交付物设置一道人工确认环节。第七跨 Agent 战略要提前规划。如果团队同时使用 Claude Code 和 Codex从一开始就把技能脚本和指令文件分离避免把大量业务逻辑直接写在 Claude Code 的交互式配置里。这样以后无论切到什么工具底层脚本都能复用。12. 总结与下一步Agent Skills 值得从今天开始尝试。回到开头的目标从会用 AI 到会开发 Agent最直接的抓手不是去学复杂的 Agent 框架而是先把自己经常做的事情沉淀成技能包。一个能稳定产出结果的技能比十个只停留在提示词层面的“AI 技巧”更有价值。建议你从三个方向挑一个入手第一个是代码审查技能因为你每天都在写代码最容易验证效果第二个是文档整理技能把你零散的笔记自动转成结构化文档第三个是日志分析技能帮助你在排障时快速定位问题。无论选哪个都按照本文的流程走一遍建目录、写 SKILL.md、写脚本、启动 CLI、触发验证、进入批量使用。最容易踩的坑有三个SKILL.md 描述写得太模糊导致 Agent 永远不触发禁止事项缺失导致 Agent 在审查任务里顺手改了代码批量任务没有超时和日志导致卡住后无法恢复。把这三个坑填上你就已经超过大多数刚接触 Agent Skills 的开发者了。后续可以继续扩展的方向包括把技能接入团队共同维护的私有仓库通过 MCP 给技能补充外部工具能力把技能嵌入 CI 流水线甚至在多个 AI 编程工具之间建立一套统一的技能目录结构。工具会变模型会换但把专业能力沉淀成可复用技能的这个习惯会一直有价值。