这段时间 Claude Code、Codex 这类终端 Agent 编程工具非常火很多团队已经从“用聊天助手写代码”转向“在终端里让 Agent 直接改代码、跑测试、提 PR”。但真正落地时大家会发现光会安装工具远远不够真正拉开效率差距的是 Agent Skill 的设计能力怎么把团队规范、代码审查标准、项目上下文、质量检查流程打包成 Agent 能理解、能按需加载的“技能包”。这篇教程会从 Claude Code 与 Codex 的基本概念讲起逐步拆解技能架构、工具管理、上下文控制、质量评估再给出一套可以直接在企业内部复用的落地思路。适合刚接触 Agent 编程的新手也适合已经在团队里做 AI 研发效能建设的同学。先说明一下本文的定位这不是一篇简单的安装教程也不是纯概念科普。本文会尽量按照“是什么 → 为什么 → 怎么用 → 怎么落地 → 怎么排错”的顺序来写每个关键步骤都会解释原理。文中的代码和配置以通用实践为主遇到具体版本差异时我会明确提示你以官方最新文档为准。1. 背景为什么 Agent 编程工具和 Skill 突然火了1.1 从聊天助手到终端 Agent过去两年大家习惯的 AI 编程方式是在网页对话框里描述需求把生成的代码复制到项目里再手动处理依赖和报错。这种方式本质上是“AI 辅助生成代码片段”人仍然负责整个流程的上下文传递。Claude Code 和 Codex 这类工具出现后交互方式发生了很大变化它们直接运行在终端里能读取项目目录、查看文件内容、执行命令、运行测试甚至在你批准后修改文件并提交代码。AI 不再只是“生成代码的工具”而是变成了“能在项目里干活的 Agent”。这种变化带来的最大好处是上下文连续性。以前你在一个对话框里描述问题往往要贴大量文件内容而 Agent 工具可以自己打开相关文件、搜索关键函数、读取报错日志。它更像是“坐在你旁边的实习生”而不是“一个只能回答问题的搜索引擎”。不过这也带来了新的工程问题AI Agent 的能力越强越需要约束和引导。如果没有清晰的技能定义和上下文规范它可能读了大半个项目、做了很多无关操作、生成不符合团队风格的代码。这也是 Agent Skill 概念迅速流行起来的原因。1.2 Claude Code 与 Codex 分别是什么Claude Code 是 Anthropic 推出的终端编程 Agent与 Claude 系列模型深度集成强调长上下文理解、代码编辑和工具调用能力。你可以在项目目录里直接运行claude命令它会根据项目文件、指令文件和你的对话逐步完成任务。Codex 是 OpenAI 推出的命令行编程工具同样以 Agent 方式工作。它可以连接 OpenAI 的模型服务也支持通过自定义模型提供方接入其他兼容模型。Codex 适合已经有 OpenAI 生态使用习惯的团队也适合希望通过命令行自动化完成编码任务的开发者。两者在理念上非常接近都是“让 Agent 在本地环境里安全地操作项目”。但在具体的技能格式、配置方式、支持的命令和模型策略上存在差异。团队落地时不需要一开始就纠结“哪个更好”而应该先明确你想要 Agent 完成什么任务再选择工具。1.3 Agent Skill 在其中的位置Agent Skill 不是某个工具的专属功能而是一种把“完成某类任务的方法论”封装成 Agent 可读取、可调用、可复用单元的方式。一个 Skill 通常包含任务描述、适用场景、执行步骤、约束条件、示例、工具使用建议等。你可以把 Skill 理解为“岗位说明书”或“SOP 手册”。Agent 本身是执行者Skill 是给它预先写好的工作流程。团队里常见的高价值 Skill 包括代码审查、单元测试生成、数据库迁移脚本编写、日志排查、依赖升级、安全扫描、接口文档生成等。这类技能之所以突然被频繁讨论是因为大家发现同一个模型没有 Skill 时表现很随机有了 Skill 后输出稳定很多。原因是 Skill 把隐性经验显性化了。2. 概念区分Agent、Skill、工具、上下文控制2.1 Agent 与 Skill 的关系很多初学者容易把 Agent 和 Skill 混在一起。Agent 是整个执行系统它由模型、工具、上下文、对话循环组成。Skill 是 Agent 可加载的“能力包”它告诉 Agent 在特定场景下应该遵循什么流程、调用哪些工具、输出什么格式。可以这样理解Agent会思考、会调用工具、会执行操作的“工人”。Skill工人手里的“操作手册”不同任务对应不同手册。Tool工人实际使用的“工具”比如文件读写、命令行执行、网络请求。Context工人当前看到的“工作环境”包括项目文件、历史对话、全局规则。举个实际例子你做代码审查时Agent 需要读取 diff、理解业务逻辑、检查安全漏洞、给出修改建议。如果你没有定义 SkillAgent 会自由发挥如果你把团队代码规范、审查重点、输出模板写进一个 Code Review SkillAgent 就会按固定流程执行。2.2 Skill 和系统提示词工程的区别系统提示词工程大家比较熟悉通常是在系统提示词里写“你是资深工程师请遵循以下规范……”。这种方式适合约束 Agent 的通用行为但它有一个明显的短板随着规则增多提示词变得冗长Agent 每次对话都要处理大量固定文本既消耗上下文也容易“记不住重点”。Skill 的思路不一样。它强调按需加载Agent 在开始任务时先根据用户意图判断需要哪些技能再加载对应的说明文件。换句话说系统提示词更像是“公司全体员工的通用入职手册”Skill 则是“不同岗位的专项作业指导书”。通用手册要精简专项指导书可以详细。这也是为什么很多团队开始把冗长的“提示词工程文档”拆分成多个 Skill 文件。拆分之后上下文占用减少Agent 对当前任务的专注度反而更高。2.3 Claude Code 与 Codex 中 Skill 的落地形态在 Claude Code 中常见的做法是使用项目级指令文件如CLAUDE.md来定义通用规则同时把具体的技能说明放在独立目录中由SKILL.md文件承载。当 Agent 遇到匹配任务时可以读取对应的SKILL.md。在 Codex 中类似机制通过项目指令文件如AGENTS.md和自定义命令实现也可以把技能说明组织成可复用的文本文件。不同版本的工具对技能目录、加载机制的支持程度不一样建议你以官方最新文档为准。这里要强调一点我们不需要纠结“到底是 Claude Code 的 Skill 更标准还是 Codex 的 Skill 更标准”。真正重要的是掌握底层设计思路然后根据工具的当前能力做适配。方法学会了换工具也只是改一下文件格式。3. 环境准备与安装3.1 安装 Claude CodeClaude Code 的安装方式在不同阶段有所变化目前比较常见的方式是通过 npm 全局安装。你需要先准备好 Node.js 环境然后在终端执行npm install -g anthropic-ai/claude-code安装完成后进入项目目录执行claude首次启动时会引导你完成登录和权限确认。登录成功后Claude Code 就能读取当前目录下的项目文件了。如果你是在 VS Code 中使用可以到扩展市场搜索 Claude Code 官方扩展。装好后在扩展面板中登录然后就可以在编辑器终端里直接启动会话。它的核心逻辑仍然是命令行工具扩展只是提供了更友好的图形界面入口。另外多说一句Claude Code 的官方支持范围会根据服务条款和账号地区发生变化。如果启动时出现类似“Claude Code might not be available in your country”的提示说明当前环境不在官方支持范围内。这时候不要尝试绕过限制而是应该以官方支持列表为准企业部署也应在合规网络环境下进行。3.2 安装 CodexCodex 同样可以通过 npm 安装npm install -g openai/codex安装完成后运行codex首次使用需要登录并验证账号。部分用户会遇到手机号验证这通常和账号所属地区、安全策略有关。如果收不到验证码优先检查账号信息是否完整以及当前地区是否在服务范围内。Codex 支持通过配置自定义模型提供方。很多团队会把 Codex 接入第三方兼容模型例如 DeepSeek 或自建模型网关。具体配置方法会随版本变化整体思路是在 Codex 的配置文件中声明一个自定义提供方并指定模型名称、接口地址、鉴权方式等。下面的示例只是展示配置结构你需要按实际版本调整{ model_providers: { my_provider: { name: My Provider, base_url: https://your-model-endpoint.example.com, env_key: MY_PROVIDER_API_KEY, wire_api: chat } } }配置完成后通过-p或相关参数指定提供方和模型即可。这类自定义配置改动频繁强烈建议查阅官方文档中的最新配置说明。3.3 版本与运行时注意事项无论安装哪个工具都要注意三点第一工具版本更新非常快。今天可用的参数下个月可能就会废弃。如果你的项目里既有稳定版本要求又有新功能需求建议把 CLI 工具的版本固定下来而不是每次都装 latest。第二Node.js 环境要保持干净。如果你之前装过其他命令行工具环境变量 PATH 可能存在冲突。执行which claude或which codex可以查看命令实际指向的位置。第三企业内部安装时尽量使用统一版本并把安装步骤写进团队文档。否则不同开发者的工具行为不一致Agent 生成的结果也会有很大差异。4. 核心机制拆解Skill 架构设计4.1 Skill 的标准结构虽然不同工具对 Skill 的具体实现有差异但社区里已经形成了一套比较通用的结构约定。一个 Skill 通常是一个独立目录目录里包含skills/ code-review/ SKILL.md examples/ 01-安全漏洞.md 02-性能问题.md其中SKILL.md是核心文件它用 Markdown 编写顶部包含元信息下面是对 Agent 的详细指令。元信息一般包括技能名称、描述、适用场景部分实现还支持声明允许使用的工具。编写时要注意描述信息要具体且可匹配。Agent 能否在合适的时机加载这个 Skill很大程度上取决于description是否写得清楚。如果描述是“用于代码审查”太宽泛如果写成“当用户要求审查 Pull Request、检查代码安全性或提交规范时使用输入通常包含 git diff”效果会好很多。4.2 如何编写一个 SKILL.md下面给出一个SKILL.md的示例骨架你可以直接参考这个结构来写自己的技能--- name: code-review description: 当需要审查代码变更、检查代码规范、发现安全风险和性能隐患时使用。适用于 Pull Request 审查、提交前自检、他人代码走查等场景。 allowed-tools: - read_file - run_command --- # Code Review 技能 ## 目标 对当前代码变更进行系统性审查输出可执行的修改建议而不是泛泛而谈。 ## 执行步骤 1. 获取代码变更范围git diff 或指定文件。 2. 识别变更涉及的核心模块和风险点。 3. 按安全、性能、可读性、测试覆盖四个维度检查。 4. 输出结构化审查意见。 ## 输出格式 - 问题列表按严重程度排序。 - 每个问题包含文件位置、问题描述、修改建议、示例代码。 - 最终给出整体结论通过 / 需修改后通过。 ## 常见红线 - 禁止直接修改生产环境配置。 - 敏感信息必须使用环境变量不得硬编码。 - 不改变原有业务逻辑的前提下优先做最小改动。这里的关键不是格式本身而是“可执行”。很多新手写的 Skill 只有抽象原则比如“请认真审查代码”。这种描述 Agent 无法转换为具体动作。好的 Skill 应该包含步骤、判断条件、输出格式和红线约束。另外Skill 里可以写“何时不要使用”。例如如果用户只是问一个概念问题就不需要加载代码审查技能。这类负向描述能减少 Agent 误用技能的概率。4.3 Skill 与工具管理的关系工具管理是 Skill 设计中容易被忽略的一环。Agent 本身可以调用很多工具但并不是每个场景都需要全部工具。例如代码审查 Skill 需要读取文件、执行 git diff但可能不需要写文件数据库迁移 Skill 需要执行 SQL 脚本但必须限制在测试库。如果你使用的工具支持在 Skill 中声明allowed-tools一定要善用这个能力。它相当于给技能设置了权限边界。即便工具不支持这种声明你也应该在 Skill 正文中明确写清楚本技能可以调用哪些命令、禁止调用哪些命令、如果要执行破坏性操作必须停下来等待用户确认。4.4 在 Claude Code 和 Codex 中接入 Skill在 Claude Code 中整体流程是先在项目下创建skills目录把 Skill 文件夹放进去然后在对话中描述任务Agent 会根据描述决定是否加载对应技能。你也可以把常用技能的说明写入CLAUDE.md让 Agent 在启动时就了解项目里有哪些技能可用。在 Codex 中常用做法是利用项目指令文件AGENTS.md描述项目背景和可复用技能再通过自定义命令把复杂的技能调用封装成一条短命令。例如把一个代码审查流程写成自定义命令后每次执行都可以复用同一套标准。需要注意的是这两个工具的加载机制都还在快速演进。我建议你采用“先读官方文档 → 再建最小 Demo → 再团队推广”的路径。不要照搬网上的某个配置文件因为那很可能已经过时了。5. 完整实战搭建一个团队级 Code Review Skill5.1 需求与设计下面我们通过一个完整案例把前面的概念串起来。假设团队需要统一代码审查标准希望 Claude Code 或 Codex 在审查代码时能输出固定格式的报告并且自动检查常见安全红线。我们先设计 Skill 的目标和范围。目标不是“替代人工审查”而是“让人工审查更高效”。因此 Skill 的输出要结构化直接暴露风险点而不是输出一篇散文。范围限定在 Java 后端项目的 Pull Request 审查重点关注SQL 注入、空指针、事务边界、敏感信息泄露、异常吞掉等问题。5.2 编写 Skill 文件按照上面的结构我们创建一个java-pr-review的 Skill--- name: java-pr-review description: 用于 Java 后端项目的 Pull Request 代码审查。当用户以 git diff、PR 链接或代码片段方式请求审查时使用。重点检查安全漏洞、事务问题、空指针风险、敏感信息泄露。 --- # Java PR 代码审查 ## 审查范围 - 只审查本次变更涉及的代码不扩展审查无关模块。 - 同时读取关联的测试文件检查变更是否有对应测试覆盖。 ## 审查维度 ### 1. 安全 - 拼接 SQL 字符串必须使用 PreparedStatement 或参数化查询。 - 文件上传路径必须校验防止目录穿越。 - 日志中不得打印身份证号、手机号、密码、token 等敏感信息。 ### 2. 事务 - 涉及多表更新的方法检查是否标注 Transactional。 - 事务方法内部不得捕获异常后继续执行避免事务失效。 - 长事务需要拆分为短事务避免锁竞争。 ### 3. 空指针与异常 - 外部接口返回值使用前必须判空。 - catch 块不能为空至少要记录日志。 - 不要吞掉 InterruptedException。 ### 4. 性能 - 循环内不得执行 SQL 查询必须改批量查询。 - 大批量数据操作检查是否有分页或分批处理。 ## 输出格式 输出包含三部分 1. 变更概述一句话说明变更内容和涉及模块。 2. 问题列表按严重程度从高到低排列每个问题必须包含文件路径、行号、问题描述、修改建议。 3. 结论通过 / 需要修改后通过。 ## 红线约束 - 不修改任何代码只输出审查意见。 - 如果变更中存在敏感信息硬编码必须标记为阻断项。 - 审查意见必须基于实际代码事实禁止猜测。这个 Skill 的关键点在于把团队过去积累的常见问题显性化了。Agent 看到这条指令后不再自由发挥而是按四个维度逐项检查。每个维度的结论都必须基于代码事实这也能减少虚假报告。5.3 接入 Claude Code 与 Codex在 Claude Code 中把上面的目录放到.claude/skills/java-pr-review/下并确保文件名是SKILL.md。然后在CLAUDE.md中增加一行说明## 技能列表 - java-pr-reviewJava 后端 PR 代码审查当收到 PR 审查请求时使用。在 Codex 中可以把技能正文放到项目文档目录中并在AGENTS.md中引用。如果 Codex 自定义命令可用还可以在配置文件中注册一条review命令让用户通过codex review直接触发。接入时最容易出问题的不是格式而是路径。很多同学把 Skill 文件写好了但是目录名和文件名不对导致 Agent 扫描不到。建议先做一个最小验证直接问 Agent“项目里有哪些技能可用”看看它能否正确列出你刚添加的 Skill。5.4 运行与效果验证接入完成后找一个小型 Pull Request 做实验。让 Agent 获取 diff 并执行审查观察输出是否符合预期。第一次运行很可能不够好这时不要急着改 Skill 文件而是先看 Agent 在哪个环节出了问题如果它没有按四个维度检查可能是描述不够明确或 Skill 没有被加载。如果它输出了错误的行号可能是 diff 上下文不足需要在 Skill 中增加“先读取完整文件再定位行号”的步骤。如果它报了不存在的安全问题可能是检查项过于模糊需要补充正反例。一个可用的 Skill 往往需要迭代几天。建议团队里由一个人先负责把 Skill 版本管理起来像维护代码一样维护 Skill。6. 企业落地上下文控制、质量评估与团队级提效6.1 上下文控制的工程手段企业使用 Agent 编程时上下文控制是最大的成本与质量杠杆。这里的“上下文”包含两层含义一是模型能看到的项目信息量二是模型需要处理的对话历史长度。上下文过长会导致费用上升、响应变慢、注意力分散上下文过短又会导致 Agent 缺少必要信息做出错误判断。常见的控制手段有五个第一精简全局指令文件。CLAUDE.md或AGENTS.md中只写稳定且高价值的规则例如项目结构说明、常用命令、代码风格、禁止事项。不要把所有团队规范全部堆进去。第二按需加载技能。把大段流程说明从全局指令移到 Skill 文件中让 Agent 只在特定任务加载它。这样可以减少每次请求的基础 token 消耗。第三控制文件读取范围。在 Skill 中明确指出“只读取 src/main/java 下的相关文件不扫描 node_modules、build、target 目录”。你也可以在调用命令时通过工具参数限制搜索范围。第四拆分会话。一个会话只做一件事。如果任务是“先审查代码再重构再写测试”尽量拆成多个独立会话避免历史对话积累过多无效信息。第五建立索引式文档。在项目指令文件中维护一张表格列出“什么类型的问题到哪个文档查”。Agent 第一次看到问题描述时先查索引再决定是否读取详细文档。6.2 质量评估如何判断 Agent 输出是否合格很多团队引入 Agent 后最大的困惑是“如何评估效果”。这里推荐一套比较轻量的评估方式准备一组黄金测试用例定期把它交给 Agent 执行然后人工打分。例如针对代码审查 Skill可以准备三个历史 PR一个有 SQL 注入风险、一个有事务失效风险、一个规范但有小问题。每次 Skill 更新后都让 Agent 跑一遍这三个用例检查它能否发现固有风险以及是否存在误报。分数可以分三档完全命中、部分命中、未命中。这种评估方式看起来简单但能解决两个关键问题一是技能迭代是否有正向效果二是不同模型接入后行为是否稳定。团队规模较大时可以把黄金用例的执行结果自动记录到表格里形成回归测试集。需要注意的是Agent 的输出天然有一定随机性。单次测试通过不代表每次都通过建议在评估时让同一个用例运行三次取多数结果。如果随机性太大优先从上下文和 Skill 指令的确定性上找原因。6.3 团队级落地流程企业级落地不能只靠几个开发者自己用一定要形成流程。这里给出一个经过实践检验的落地顺序第一步选定一个高价值、低风险场景试点。推荐从“代码审查”或“单元测试生成”开始因为这两类任务边界清晰、结果可评估、不会直接改动生产环境。第二步指定专人负责维护 Skill 模板。Skill 本质上是团队知识资产不应该散落在个人目录里。建议在 Git 仓库中单独建一个skills/目录把技能纳入版本管理。第三步建立“Agent 操作安全边界”。原则上Agent 不能直接操作生产环境不能读取未授权的密钥不能修改环境变量。如果工具支持权限审批必须开启人工确认。团队应该明确列出“Agent 禁止执行名单”例如禁止执行rm -rf、禁止直接连接生产数据库执行 DML。第四步设计人机协作流程。例如Agent 负责生成代码草稿和单元测试人负责审查和合并Agent 负责定位日志中的错误人负责决定修复方案。不要把 Agent 的结论当成最终结论。第五步定期复盘错误案例。每次 Agent 产生严重错误都要复盘是模型问题、Skill 描述问题还是权限配置问题。把错误案例补充到对应的 Skill 中形成“负面清单”。6.4 成本与权限管理成本控制是团队落地时必须面对的问题。Agent 编程工具调用模型的方式和普通聊天不同它会不断读取文件、生成多轮对话单次任务的 token 消耗可能很高。建议从三方面控制首先是上下文长度限制。设置单次会话的项目文件扫描上限禁止 Agent 读取整个仓库。其次是任务拆分。大任务拆小任务每个任务控制在可预期的范围内。最后是模型分级。简单任务用便宜模型复杂推理用强模型在工具配置中按技能类型切换。权限管理则遵循最小权限原则。Agent 能读的目录尽量少能执行的命令尽量窄能调用的外部服务尽量少。特别是当 Codex 接入第三方模型接口时API Key 必须通过环境变量注入不能写进 Skill 文件或代码仓库。这里补充一句企业落地时所有涉及生产环境变更的操作必须经过授权审批流程并在测试环境完整验证后才能执行。7. 常见问题与排查思路下面列出使用 Claude Code 和 Codex 过程中常见的问题覆盖安装、登录、配置和运行几个阶段。问题现象常见原因解决思路安装时提示 npm 权限不足Node.js 全局目录无写权限修复 npm 全局目录权限或用 nvm 管理 Node.js 版本启动时提示“Claude Code might not be available in your country”当前环境不在官方支持范围以官方支持列表为准企业部署应使用合规网络环境Codex 提示auth token is unavailable登录状态失效或环境变量未配置重新登录检查 API Key 相关环境变量是否设置正确Codex 请求模型时报model is not supported配置的模型名与当前提供方不匹配检查模型名称拼写确认提供方支持该模型查看官方模型列表cc switch 切换配置时本地网络转发失败本地网络配置与目标模型服务端不匹配检查本地请求转发端口、协议配置确认目标服务可访问收不到 Codex 手机号验证码账号地区限制或安全策略检查账号绑定信息确认当前地区是否在服务范围内VS Code 中找不到扩展命令扩展未激活或 PATH 未配置重启 VS Code确认终端中能直接运行 claude/codex 命令Agent 不加载自定义 Skill目录名或文件名不符合约定检查 SKILL.md 文件名、description 描述是否足够匹配Agent 频繁读取无关文件全局指令中没有限制扫描范围在 CLAUDE.md 或 AGENTS.md 中明确忽略目录与文件类型任务执行一半自动停止长时间运行触发了超时或人工确认拆分任务将确认步骤移到关键节点前排错时建议按“环境 → 配置 → 模型 → 技能”的顺序排查。先确认命令能正常运行再检查配置是否被正确加载然后确认模型提供方是否可用最后才排查 Skill 本身的问题。因为 Skill 问题通常不会报错而是表现为输出不符合预期不容易直接发现。另外不要忽略日志。Claude Code 和 Codex 通常会在本地保存会话日志日志中能看到 Agent 实际读取了哪些文件、调用了哪些工具、模型返回了什么内容。养成“看日志”的习惯比反复猜测配置有效得多。8. 总结与学习路线这篇文章从 Claude Code 和 Codex 的基础概念开始重点拆解了 Agent Skill 的设计思想并通过一个 Java PR 审查的例子演示了从编写到接入的完整过程。你可以把本文的核心内容归纳为五点Agent 是执行者Skill 是执行手册技能要按需加载而不是塞进系统提示词上下文控制决定质量和成本质量评估需要黄金用例团队落地必须做好权限和安全边界。如果接下来想继续深入建议按这个顺序学习先把你手头最重复的一项开发任务写成 Skill 并跑通然后尝试用评估用例量化效果再研究工具的配置项优化模型选择和上下文长度最后在团队内小范围推广逐步沉淀团队专属技能库。最后给你一个比较实在的建议不要一开始就追求“让 Agent 自动修所有 Bug”也不要轻易让 Agent 直接操作生产环境。从代码审查、单测生成这类低风险任务开始把 Skill、上下文、评估三个环节打磨顺了再逐步扩展到更复杂的开发任务。如果你正在团队里推动 Agent 编程落地不妨先建一个只有几个人的试点小组把这套方法论跑通再推广到全团队。