从会说会写到会开发Agent Skills 入门到实战用 Claude Code 和 Codex 打造可复用的智能体技能最近不少同学在群里聊同一个感受用 AI 写代码、写文档已经很顺手了但 AI 帮我们做的事始终限制在“对话”里。你问一句它答一句换个项目、换个环境同样的问题可能要重新调半天提示词之前积累的经验根本带不走。这就是 Agent 和普通 AI 助手的核心区别。普通 AI 是“你问它答”Agent 是“你交代目标它自己拆解、执行、交付”。而 Agent 能否真正稳定地干活关键又取决于它有没有一套可复用的“技能体系”。我从 Claude Code 和 Codex 的实际使用出发梳理了一套从零搭建 Agent Skills 的方法。本文包含完整的环境配置、技能目录结构、SKILL.md 编写规范、可运行的示例和常见报错排查方案适合刚从对话式 AI 转向 Agent 开发的同学参考。读完你可以自己定义一个项目级或团队级技能包让 Agent 在后续任务中持续复用。1. 背景与核心概念1.1 从“会用 AI”到“会开发 Agent”先打个比方。你让一个实习生干活如果只说“帮我做个数据报表”他大概率会反问一堆问题数据在哪报表要给谁看用什么格式但如果这个实习生已经带过很多次他自己就知道该查哪些表、按什么口径统计、邮件发给谁。Agent 也是这个道理。大模型本身是“应届生”知识面广但做事没有固定章法。而 Agent Skills 就是给这个“应届生”的一份标准化工作手册里面写着这个任务应该按什么流程做、有哪些注意事项、遇到什么情况调用哪个脚本、结果输出成什么格式。所以可以这样理解Prompt提示词是一次性的口头交代。Skill技能是沉淀下来的标准作业流程可以被反复调用。Agent智能体是具备一组 Skill、能自主规划执行路径的执行者。1.2 什么是 Agent SkillsAgent Skills 不是某个厂商的独家概念而是一种让大模型 Agent 具备“特定领域操作能力”的封装方式。它通常包含一个描述技能用途和调用方式的说明文件以及配套的脚本、模板、数据或配置。以 Claude Code 为例Skills 是放在特定目录下的能力模块。Agent 在执行任务时如果发现当前任务匹配某个 Skill 的描述就会自动加载这个 Skill 的说明并按照里面的步骤和脚本来操作。Codex 同样支持类似机制。在实际开发中我们可以把常用的代码审查、接口测试、日志分析、环境部署等操作封装成 Skill让 Agent 在接到任务时“自动想起”这些经验。1.3 Agent Skills 解决什么问题我总结了一下Agent Skills 主要解决四类问题问题没有 Skill 时的表现有 Skill 之后经验无法沉淀每次都要重新写提示词技能目录直接复用操作流程不稳定偶尔一次成功换场景就失败标准化步骤结果可预期工具调用混乱Agent 不知道该用哪个脚本SKILL.md 里明确指定团队协作低效个人经验无法共享Git 管理技能包团队共用更重要的是Skill 让 Agent 从“泛泛的通用助手”变成“懂你业务的专业助手”。同一个 Agent加载了“支付接口测试”的 Skill它处理支付项目时就会自动带上这套经验加载了“日志排查”的 Skill它遇到线上报错就知道该怎么定位。2. 环境准备与版本说明2.1 本文使用的工具链为了把概念讲清楚本文以 Claude Code 和 Codex CLI 两个工具为例。Claude CodeAnthropic 推出的终端编程助手支持在项目目录中读取文件、执行命令、修改代码。Codex CLIOpenAI 推出的命令行编码智能体通过自然语言驱动在本地仓库中完成任务。两者的核心思路一致通过 CLI 把大模型连接到你的项目环境Agent 在沙箱或授权模式下执行操作。2.2 Claude Code 安装Claude Code 通常通过 npm 安装。在确认本机已安装 Node.js 18 的前提下执行npm install -g anthropic-ai/claude-code安装完成后在项目目录下运行claude首次运行会引导你完成登录认证。需要说明的是不同版本的登录方式和 API 配置有一定差异如果网络环境中特殊变量较多可能需要配置代理参数具体以官方安装文档为准。2.3 Codex CLI 安装Codex CLI 同样可以通过 npm 安装npm install -g openai/codex安装后执行codex如果之前安装过旧版本建议先升级npm update -g openai/codex某些 IDE 插件会内置 Codex CLI但插件内配置的 CLI 路径可能与全局安装路径不一致容易触发“找不到 codex cli binary”的报错这在第 5 章会专门说明。2.4 版本说明本文写作时Claude Code 和 Codex CLI 的版本更新速度都非常快。不同版本对 Skills 目录的支持位置、配置字段可能有细微差异。如果你的版本行为与本文描述不一致请优先查阅官方 CHANGELOG。以下示例重点演示“思路与规范”不依赖某个精确版本代码中的目录结构和核心概念在目前的主流版本中都是适用的。建议在开始之前统一确认版本claude --version codex --version npm -v node -v3. Agent Skills 核心机制拆解3.1 SKILL.md 是技能的灵魂无论 Claude Code 还是 CodexAgent Skills 的核心都是一个 Markdown 文件通常命名为SKILL.md。这个文件的作用是告诉 Agent 三件事这个技能是干什么的—— 技能的用途描述用于 Agent 判断是否调用。这个技能怎么做—— 详细的步骤、规则、注意事项。这个技能能调用什么资源—— 相关的脚本、模板、二进制文件放在哪里。可以这样理解SKILL.md就是 Agent 的“任务说明书”Agent 在执行前先读说明书再动手。3.2 技能目录的标准结构一个典型的 Skill 目录如下skills/ code-review/ SKILL.md rules/ security-rules.md scripts/ run_review.sh templates/ review_report.md各目录的作用SKILL.md核心说明文件Agent 首先读取它。rules/存放补充规则比如安全红线、命名规范。scripts/存放可执行脚本Agent 可以调用这些脚本完成操作。templates/存放输出模板保证生成结果格式统一。当 Agent 配置了skills目录后在对话中遇到匹配任务会自动读取对应 Skill 的SKILL.md按照说明执行。3.3 SKILL.md 的内容结构参考当前社区通用的 Skill 编写规范一份完整的SKILL.md应该包含以下区块区块作用是否必须name技能名称必须description技能用途和触发条件必须使用场景说明在什么情况下调用推荐执行步骤具体操作流程必须工具与脚本说明列出可用的脚本、参数推荐输出要求约定输出格式推荐注意事项边界条件、禁忌操作推荐下面先看一个最小示例--- name: python-unit-test description: 当用户要求为 Python 项目编写或补充单元测试时使用。 --- # Python 单元测试技能 ## 适用场景 - 新建测试文件 - 为现有函数补充测试用例 - 运行测试并检查覆盖率 ## 执行步骤 1. 确认项目使用的测试框架pytest / unittest 2. 根据被测模块创建对应的 test_ 文件 3. 编写测试用例覆盖正常输入、边界输入、异常输入 4. 在项目根目录执行 pytest -v确认全部通过 ## 输出要求 - 测试文件命名规范test_模块名.py - 测试函数命名规范test_被测函数_场景这个文件并没有调用任何脚本但它已经算是一个完整的 Skill。因为它定义了一套标准作业流程Agent 在遇到“写单测”的任务时会按照这个流程执行而不是凭大模型的“临场发挥”。3.4 Agent 如何决定调用哪个 Skill当 Agent 加载了 Skills 配置后每一步决策过程大致如下读取用户输入的任务。扫描所有已注册 Skill 的description字段。计算任务与 Skill 描述的匹配度。如果匹配读取该 Skill 的详细步骤按步骤执行。如果多个 Skill 都匹配Agent 会规划组合方案。因此description写得好不好直接决定技能能不能被正确触发。它应该尽量包含“触发关键词”和“适用场景”而不是写得模棱两可。4. 完整实战从零创建并调用一个 Agent Skill这一节我们做一个带脚本、带模板、可运行的完整案例。目标开发一个“Git 仓库健康检查”技能Agent 通过这个技能自动分析仓库状态、识别常见风险并输出一份结构化报告。4.1 创建项目结构先创建技能目录mkdir -p skills/git-health-check/{scripts,templates}最终目录结构为skills/git-health-check/ SKILL.md scripts/ check_repo.sh templates/ health_report.md4.2 编写 SKILL.md在skills/git-health-check/SKILL.md中写入--- name: git-health-check description: 当用户要求检查 Git 仓库状态、分析分支健康状况、识别大文件或长期未合并分支时使用。典型触发词包括 git 检查、仓库健康、分支清理、大文件排查。 --- # Git 仓库健康检查技能 ## 适用场景 - 定期检查仓库状态 - 部署前确认仓库干净 - 识别长期未合并的分支 - 排查仓库体积过大问题 ## 执行步骤 ### 1. 执行仓库状态检查 运行 scripts/check_repo.sh传入仓库路径参数 bash bash scripts/check_repo.sh /path/to/repo2. 解析脚本输出脚本会输出以下信息当前分支和最近提交未合并分支列表超过 10MB 的大对象如存在仓库总大小3. 根据结果生成报告使用templates/health_report.md作为模板将上一步的结果填入报告。输出要求报告必须包含“风险等级”字段高存在大于 50MB 的游离大文件中存在超过 30 天未合并的分支低以上条件均不满足每个风险项必须给出建议操作注意事项只做只读检查不执行 git clean、git branch -D 等破坏性命令。如果仓库路径不存在或不是 Git 仓库立即停止并报告错误。### 4.3 编写检查脚本 在 scripts/check_repo.sh 中写入 bash #!/bin/bash # 文件路径skills/git-health-check/scripts/check_repo.sh # 功能只读检查 Git 仓库健康状况 REPO_PATH$1 if [ -z $REPO_PATH ]; then echo 错误请传入仓库路径 exit 1 fi if [ ! -d $REPO_PATH/.git ]; then echo 错误$REPO_PATH 不是有效的 Git 仓库 exit 1 fi cd $REPO_PATH || exit 1 echo 当前分支与最近提交 git branch --show-current git log -1 --oneline echo echo 未合并分支列表 git branch --no-merged HEAD | head -20 echo echo 仓库总大小 du -sh .git 2/dev/null | cut -f1 echo echo 大文件检查超过 50MB 的 Git 对象 git rev-list --objects --all | git cat-file --batch-check%(objecttype) %(objectname) %(objectsize) %(rest) | awk /^blob/ { if ($3 50000000) print $4, $3 } | sort -k2 -n -r | head -10 echo echo 检查完成给脚本添加执行权限chmod x skills/git-health-check/scripts/check_repo.sh这个脚本做的事情很清晰先用git branch --no-merged HEAD找到未合并分支这是最常见的仓库维护盲点。再用du -sh .git判断仓库体积。最后通过git rev-list --objects --all配合cat-file --batch-check扫描历史中的大文件对象。整套操作都是只读的不会改动仓库任何状态符合安全边界要求。4.4 编写报告模板在templates/health_report.md中写入# Git 仓库健康检查报告 - 检查时间{{date}} - 仓库路径{{repo_path}} ## 风险等级 {{risk_level}} ## 仓库状态 - 当前分支{{current_branch}} - 最近提交{{latest_commit}} - 仓库大小{{repo_size}} ## 未合并分支 {{unmerged_branches}} ## 大文件风险 {{large_files}} ## 建议操作 {{recommendations}}这个模板的意义在于它定义了输出的固定格式。Agent 每次生成报告时都会按照同样的结构输出不会出现“这次用表格、下次用列表”的混乱情况。4.5 配置 Agent 使用技能以 Claude Code 为例你可以在项目配置文件或启动参数中指定 Skills 目录。在项目根目录创建.claude/settings.json不同版本路径可能不同{ skills: { paths: [ ./skills ] } }然后在项目目录启动 Claude Codeclaude在对话中输入帮我检查当前仓库的健康状态输出一份报告Agent 会读取skills/git-health-check/SKILL.md识别出任务匹配执行脚本并生成报告。如果使用 Codex可以在启动时通过指令或项目配置文件指定 skills 位置。具体字段名随 CLI 版本会有变化建议用codex --help查看当前版本支持的配置方式。4.6 运行与验证假设仓库路径是/home/user/demo-repo手动验证脚本bash skills/git-health-check/scripts/check_repo.sh /home/user/demo-repo预期输出片段 当前分支与最近提交 main a1b2c3d fix: update readme 未合并分支列表 feature/login feature/payment 仓库总大小 8.2M 大文件检查超过 50MB 的 Git 对象 检查完成如果输出中没有大文件记录说明仓库状态健康。如果出现了大文件则需要进一步定位和处理。通过这个案例可以看到一个完整的 Skill 涉及三部分工作写说明SKILL.md、写逻辑脚本、定格式模板。三者缺一不可。5. 常见问题与排查思路在实际配置和使用 Agent Skills 的过程中我整理了几个高频报错场景尤其是 Claude Code 和 Codex 混用时环境问题非常典型。问题现象常见原因解决思路启动时报 unable to locate the codex cli binaryIDE 插件找不到 Codex CLI 可执行文件确认codex已全局安装并在插件设置中指定 CLI 路径提示 deepseek-v4-pro is not a model this version of claude code recognizes本地配置的模型名与当前 Claude Code 版本支持的模型不匹配更新 Claude Code 到最新版本或修改模型配置为受支持模型报 cc switch local proxy failed 相关错误本地代理切换与 Codex endpoint 冲突检查代理配置和 endpoint 设置确保指向合法的 API 服务Agent 没有执行 Skill 中的步骤description写得不够明确Agent 未识别为匹配任务重写描述加入触发关键词确认 Skills 路径配置正确脚本执行 Permission denied脚本没有执行权限执行chmod x 脚本路径Skill 目录变更后不生效Agent 进程缓存了旧配置重启终端中的 Agent 会话5.1 codex cli binary 找不到怎么办这个问题多发生在 VSCode 等 IDE 插件场景。原因通常是插件默认去找某个固定路径下的codex而你的实际安装路径不在其中。排查步骤# 1. 确认 codex 是否安装 codex --version # 2. 查看 codex 实际安装位置 which codex # 3. 在 IDE 插件设置中手动指定该路径如果你使用 npm 全局安装在 Linux/macOS 上路径通常在/usr/local/bin/codex或$(npm prefix -g)/bin/codex。5.2 模型名不被识别怎么办deepseek-v4-pro is not a model this version of claude code recognizes这类报错的本质是配置文件中写了一个当前版本不认识的模型标识。这个问题在两种情况下常见你手动改了模型配置写错了模型名称。当前 Claude Code 版本较旧还不支持这个新模型。处理方式# 升级 Claude Code npm update -g anthropic-ai/claude-code然后检查项目或用户级配置文件把模型名改成官方文档支持的标识。如果你确实需要接入其他模型的 API一定要确认当前版本对自定义 model 的支持方式和字段规则。5.3 Shell 脚本报错排查如果 Skill 引用了 Shell 脚本但 Agent 运行时报错建议先手动执行脚本确认脚本本身逻辑没有问题。关注几个点脚本首行是否写了#!/bin/bash。是否给脚本加了执行权限。脚本中是否有 Linux 和 macOS 不兼容的命令。路径是否包含空格导致参数解析错误。把这些检查项写进SKILL.md的注意事项可以有效减少后续 Agent 调用失败的概率。6. 最佳实践与工程建议6.1 Skill 的粒度要适中这可能是设计 Skills 时最容易纠结的问题。Skill 太大会变得臃肿Agent 加载后反而不容易快速定位关键信息。Skill 太小又会产生大量碎片目录维护成本上升。我的建议是一个 Skill 只解决一个内聚的业务问题。比如“代码审查”是一个 Skill不要把它拆成“审查 Python”“审查 Java”“审查 Go”三个 Skill。但“支付接口测试”和“用户登录测试”应该拆开因为它们的依赖环境、测试重点完全不同。判断粒度是否合适的标准很简单如果 Agent 在执行某个任务时只需要读一个 SKILL.md 就能完成粒度就是对的。6.2 SKILL.md 的 description 要适配触发机制Agent 是通过扫描 description 来决定是否加载技能的。所以 description 的写法直接影响触发成功率。好的写法description: 当用户要求对 Python 项目执行代码审查、检查潜在 bug、评估代码风格时使用。触发器包括 python review、code review、代码检查。差的写法description: 代码审查相关工具。关键词覆盖越具体Agent 越容易做出正确判断。但也不要为了堆关键词而写出一段不通顺的话保持自然语言同时让关键触发词出现在前后文即可。6.3 脚本必须做防御性校验Skill 中的脚本会被 Agent 自动调用这意味着脚本必须比普通脚本更稳健。因为你无法预判 Agent 会在什么环境下、传入什么参数去运行它。核心防御点参数为空时输出清晰错误并退出。路径不存在时给出提示不要继续执行。禁止在脚本中写死绝对路径除非你有充分理由。破坏性操作删除、覆盖、远程变更默认禁止如确有必要必须加二次确认参数。以本文的check_repo.sh为例第一步就校验参数和仓库路径这不仅仅是“严谨”更是避免 Agent 在错误路径上越走越远。6.4 输出模板化Agent 执行 Skill 的最终产物最好通过模板来约束格式。原因有两点稳定格式方便后续自动化处理。模板能提醒 Agent 不遗漏关键字段。在实际项目中模板可以结合 Markdown、JSON、CSV 等格式。如果 Skill 的产出要交给下游程序建议使用 JSON 模板并附上字段说明。6.5 用 Git 管理 Skill 仓库Agent Skills 本质上是文本文件非常适合用 Git 管理。建议的团队协作模式skills-repo/ skills/ code-review/ git-health-check/ docs/ CONTRIBUTING.md团队成员通过 Pull Request 更新技能评审者重点确认三件事SKILL.md 的 description 是否清晰。脚本是否有明显的安全和兼容性问题。输出模板是否与团队规范一致。这样Skills 就从“个人经验”变成了“团队知识资产”。6.6 权限与安全边界Agent 的能力随着 Skills 扩展会越来越强这也意味着风险面在扩大。必须明确以下安全边界技能脚本默认只读需要写操作时单独授权。涉及生产环境、外部服务、支付接口的技能必须经过严格评审。技能中不要硬编码任何密钥、Token、密码。敏感操作技能建议增加人工确认环节。在 Claude Code 和 Codex 的使用中也要了解各自的权限体系和沙箱机制。优先以最小权限运行 Agent不要图省事直接给 root 或管理员权限。7. 总结与下一步实战建议Agent Skills 是连接大模型和真实工程世界的一座桥。没有 Skills 的 Agent 像一个空有热情但没有工作方法的新人有了 Skills它才能真正融入团队节奏按标准流程产出稳定结果。本文从概念、环境、机制、实战到排错完整走了一遍理解了 Agent Skills 是什么以及它如何解决经验沉淀问题。掌握了 SKILL.md 的编写结构和核心原则。动手实现了一个 Git 仓库健康检查技能包含脚本、模板、调用配置。梳理了 Claude Code 与 Codex 使用中的高频报错和处理方式。总结了 Skill 粒度控制、输出模板、安全边界等工程建议。下一步建议你做三件事复盘自己的高频操作回顾最近一个月你让 AI 重复做的事情挑出频率最高的 3 个任务。把其中一个任务封装成 Skill不需要一开始就写脚本先用 SKILL.md 固化流程跑通了再加脚本和模板。在真实项目中迭代把 Skill 放入正式项目观察 Agent 的调用效果根据失败案例调整 description 和步骤。Agent 开发的学习路线本质上就是“把你会做的事情一步步移交给 Agent”。Skills 就是你移交经验的载体。从现在开始把第一篇 SKILL.md 写下来吧。