Claude Code与Codex的Agent Skill实战：从上下文管理到团队落地

最近在团队里推进 AI 编程助手落地时遇到一个很现实的问题Claude Code 和 Codex 的安装资料到处都是但真正讲清楚 Agent Skill 设计、上下文管理、质量评估和团队协作的文章却很少。很多人把 Agent、Skill、系统提示词混在一起装好工具之后也只是当成“高级补全”来用完全没有发挥出可复用的技能体系价值。本文把这一整套内容整理成一份可以直接参考的实战笔记从核心概念、环境安装到技能架构、上下文控制、质量评估和团队级落地一次性讲透。1. 背景与核心概念1.1 为什么需要 Agent Skill传统开发流程中经验沉淀依赖人代码规范写在文档里安全 checklist 放在 wiki 里架构约定靠老员工口头传达。AI 编程助手出现后如果只是让它读一两个文件就生成代码结果往往不稳定因为它不知道团队规范也不了解项目上下文。Agent Skill 解决的就是这件事把可复用的经验、流程、脚本和校验规则打包成技能交给 AI 按需加载。Skill 不是一段提示词而是一个结构化的技能包。这套思路在企业研发提效里尤其重要。团队里真正可复制的不只是代码还有“怎么审查代码”“怎么写数据库迁移”“怎么排查线上故障”这些流程。如果每个流程都散落在不同文档里Agent 永远学不会如果把它们整理成 Skill团队新成员和 AI 助手就能共享同一套方法论。1.2 Claude Code 与 Codex 是什么Claude Code 是 Anthropic 推出的命令行 AI 编程助手可以直接在终端里让 AI 读代码、改文件、执行命令、运行测试。它的特点是深度绑定终端工作流适合本地开发、仓库级任务和自动化脚本场景。Codex 是 OpenAI 推出的编程代理产品线包含云端环境和 CLI 工具同样可以在终端里完成代码生成、解释和重构任务。两者定位相近但实现细节不同。Claude Code 更强调项目上下文记忆和技能扩展Codex 更强调与 OpenAI 生态的联动。实际项目中不必只选一个团队完全可以让不同角色使用不同工具再通过统一的 Skill 仓库沉淀经验。1.3 Skill 与 Agent 的区别Agent 是一个能感知环境、规划步骤、调用工具、完成任务的智能体。Skill 是 Agent 可以复用的能力模块类似“工具包 操作手册 校验规则”的组合。一个 Agent 可以装载多个 Skill在遇到对应场景时自动判断并调用。举个容易理解的例子Agent 像一位开发工程师Skill 像公司里的标准作业流程。工程师可以灵活思考但做代码审查时必须按流程检查安全漏洞、性能隐患和规范问题。Skill 就是这套流程的数字化表达它让 Agent 的行为从“自由发挥”变成“有据可依”。1.4 系统提示词工程与 Skill Agent 的关系系统提示词工程偏重“怎么说”通过设计系统提示词来约束模型行为、设定角色、注入全局规则。Skill Agent 偏重“怎么做”通过定义任务流程、工具调用和校验脚本来固化能力。提示词是被动读取的指令文本Skill 是主动加载的执行单元。在实际使用中系统提示词适合放稳定不变的全局规则例如“回答要简洁”“不要删除未确认的文件”Skill 适合放按需启用的专业技能例如“执行数据库回滚”“生成接口文档”“进行安全审查”。如果把所有规则都塞进系统提示词上下文窗口迟早会爆炸把专业流程放进 Skill需要时才加载才是可持续的做法。2. 环境准备与安装2.1 安装 Claude CodeClaude Code 以 npm 包形式分发需要先准备 Node.js 环境。不同版本对 Node.js 版本要求有差异建议使用 Node.js 18 或更高版本新版工具可能要求 Node.js 20具体以官方文档为准。# 检查 Node.js 版本 node -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证安装 claude --version安装完成后在终端中输入claude即可启动交互界面。首次启动会进入认证流程一般支持浏览器 OAuth 登录或 API Key 方式。如果在启动时看到区域不可用提示说明当前所在地区不在官方支持范围内应查看官方支持地区列表并遵守服务条款不要使用非正规途径绕过限制。2.2 安装 Codex CLICodex CLI 同样是 npm 包安装方式和 Claude Code 类似。npm install -g openai/codex # 验证安装 codex --versionCodex CLI 需要使用 OpenAI 账号认证。不同版本的认证指令略有区别常见的是codex login部分版本使用codex auth login。登录过程中可能涉及手机号验证按官方引导完成即可。如果提示codex auth token is unavailable通常是登录状态失效或 token 未被正确识别重新登录一般能解决。2.3 初始化与账号配置两个工具都支持通过环境变量注入认证信息和模型配置。例如在 bash 或 zsh 配置文件中声明# Claude Code 使用 Anthropic 相关配置 export ANTHROPIC_AUTH_TOKENsk-xxxx # Codex 使用 OpenAI 相关配置 export OPENAI_API_KEYsk-xxxx这里需要注意环境变量的名称和取值随版本变化不要直接照抄网上旧教程。正确的做法是先运行claude --help或codex --help查看当前版本支持的配置项再按需设置。部分团队会通过兼容网关对接内部统一模型服务做法是修改 API Base URL 和模型名但这涉及服务条款和合规要求需要团队内部自行确认。2.4 在 VS Code 中接入除了终端模式Claude Code 和 Codex 都提供了 IDE 扩展。在 VS Code 扩展市场搜索官方扩展并安装可以像普通插件一样在编辑器里唤起 AI 能力。IDE 模式的好处是能直接读取当前打开文件、选中代码和项目结构减少来回复制粘贴。桌面客户端也在陆续推出。安装桌面版后通常需要登录同一个账号同步会话历史和项目记忆。需要注意IDE 扩展和桌面版的具体入口随版本迭代变化较快如果找不到入口优先回退到 CLI 模式CLI 是功能最完整、兼容性最好的入口。3. 技能架构与原理拆解3.1 Skill 的目录结构与 SKILL.md一个标准的 Agent Skill 通常由一个描述文件和若干辅助资源组成。目录结构示例如下skills/ code-review/ SKILL.md scripts/ check_todo.py resources/ review_rules.mdSKILL.md是技能的核心描述文件里面说明技能的用途、适用场景、执行步骤和注意事项。Agent 在决定是否调用该技能时主要读取这个文件的描述信息在执行技能时则按文件里的步骤调用脚本和资源。描述越清晰Agent 的触发准确率越高。例如一个代码审查技能的 SKILL.md 开头可以是--- name: code-review description: 基于项目规范对代码变更进行审查检查规范、安全和测试覆盖适用于 PR 合并前检查。 --- ## 使用场景 - 提交 PR 前的自查 - 审查他人代码变更 - 检查安全隐患和测试遗漏description字段尤其重要Agent 靠它判断何时应该加载这个技能。如果描述写得太泛例如“审查代码”Agent 可能在所有场景都尝试调用如果写得太窄例如“只审查 Python 文件”又会错过 Java 项目中的问题。3.2 工具管理与权限边界Agent 调用 Skill 时往往会执行命令、读文件、甚至修改代码。为了避免误操作工具管理必须设置清晰的权限边界。常见的做法是默认只读写操作需确认危险命令禁止执行。在 Claude Code 和 Codex 中都可以配置允许或拒绝执行的命令。例如删除文件、修改权限、推送远端等操作应默认要求人工确认。企业落地时安全边界不是靠 Agent 自觉而是靠工具配置强制约束。这里要特别强调最小权限原则Agent 能访问的路径、能执行的命令只开放给当前任务必要的最小范围。# 示例设置工具权限提示 # 不同版本配置方式不同核心思路是让危险命令必须经过人工确认3.3 上下文控制与 Memory 机制AI 编程助手的能力上限很大程度受上下文窗口限制。一次性把所有文件都读入上下文既消耗 token又会稀释模型注意力。上下文控制的目标是让 Agent 只拿到当前任务最需要的信息。Claude Code 通过项目记忆文件记录项目的长期规范例如项目结构、代码风格、常用命令Codex 也提供类似的项目说明机制。当 Agent 启动时它只读取这个记忆文件而不是扫描全仓库。Skill 同样是一种上下文控制手段需要哪方面的专业知识就加载对应的 Skill 目录不需要的内容不进上下文。日常使用中建议控制单个任务的输入粒度。不要对 Agent 说“看看这个项目”而要说“阅读src/main/java下的订单模块找出状态机处理逻辑”。后者信息密度更高Agent 更容易聚焦。上下文接近上限时可以执行上下文压缩命令让 Agent 把关键信息浓缩成摘要后继续工作压缩命令的具体写法随版本变化以当前版本的帮助信息为准。3.4 MCP 与外部工具集成MCP 的全称是 Model Context Protocol是一种开放协议用于让 AI 助手连接外部数据源和工具。通过 MCPAgent 可以查询数据库、读取监控系统、调用内部 API而 Skill 可以把这些外部能力封装成固定流程。例如一个故障排查 Skill 可以包含以下步骤查询最近日志、检查服务健康状态、对比发布记录、定位可疑变更。每一步都通过 MCP 工具执行Agent 不需要用户反复提供信息而是按技能流程推进排查。可以把 MCP 理解为 Skill 与外部系统的桥梁Skill 负责定义流程MCP 负责执行具体调用。4. 实战构建一个团队级代码审查 Skill4.1 需求分析团队当前痛点代码审查依赖人肉检查规范执行不统一常见的安全问题和遗留标记经常漏掉。目标做一个代码审查 Skill让 Agent 在 PR 提交前自动执行基础检查并输出结构化审查报告。功能拆解读取指定目录或文件列表中新增的代码。检查 TODO、FIXME、console.log 等遗留标记。检查明显安全风险例如 SQL 拼接、明文密码、危险函数调用。输出审查结果包含风险级别、文件位置和修正建议。4.2 创建 Skill 目录结构mkdir -p skills/code-review/scripts mkdir -p skills/code-review/resources目录结构如下skills/code-review/ SKILL.md scripts/scan_markers.py resources/review_rules.md4.3 编写 SKILL.md--- name: code-review description: 对当前代码变更执行基础审查检查遗留标记、安全风险和测试遗漏适用于 PR 合并前自查或他人代码审查。 --- ## 执行步骤 1. 获取本次变更涉及的源文件列表。 2. 对每个文件运行 scripts/scan_markers.py检查遗留标记。 3. 针对关键文件检查 SQL 拼接、危险函数、硬编码密钥等安全问题。 4. 输出审查报告包含问题列表、风险级别和修改建议。 ## 注意事项 - 不要对未变更的文件做全量审查。 - 风险级别分为 high / medium / low 三级。 - 报告中必须给出具体文件路径和行号。4.4 编写辅助脚本辅助脚本的作用是把“检查 TODO 标记”这类机械操作交给 Python而不是靠模型逐个猜测。脚本代码如下# 文件路径skills/code-review/scripts/scan_markers.py import os import re import sys # 需要关注的遗留标记 MARKERS { TODO: 未完成的功能占位, FIXME: 存在需要修复的问题, console.log: 调试日志未清理, print(: 调试输出未清理, password: 疑似硬编码密码, api_key: 疑似硬编码密钥, } def scan_file(file_path): try: with open(file_path, r, encodingutf-8, errorsignore) as f: lines f.readlines() except Exception as e: print(f无法读取文件: {file_path}, 错误: {e}) return [] issues [] for line_no, line in enumerate(lines, start1): for keyword, description in MARKERS.items(): if keyword in line: issues.append({ file: file_path, line: line_no, marker: keyword, description: description, }) return issues def main(file_list): all_issues [] for file_path in file_list: all_issues.extend(scan_file(file_path)) if not all_issues: print(未发现遗留标记或安全关键词。) return for issue in all_issues: print(f{issue[file]}:{issue[line]} 发现 {issue[marker]} - {issue[description]}) if __name__ __main__: files sys.argv[1:] main(files)这个脚本是一个可运行的基础版本实际团队落地时可以根据编程语言扩展规则例如检查 Python 的eval()、JavaScript 的eval()、SQL 的字符串拼接等。4.5 在 Claude Code 中使用在 Claude Code 会话中把技能目录路径配置好后可以用自然语言触发请使用 code-review 技能审查 src/main/java/com/example/order/OrderService.javaAgent 会读取 SKILL.md定位辅助脚本执行扫描再综合规则输出审查报告。如果仓库根目录或CLAUDE.md中配置了技能目录路径Agent 会自动扫描并加载可用技能。4.6 在 Codex 中使用Codex 的使用方式类似。确保技能目录在 Codex 能访问的路径下然后在对话中描述任务运行 code-review 技能检查本次改动涉及的文件。由于两个工具对 Skill 目录的默认搜索路径可能有差异建议在项目配置文件中显式声明技能路径。具体配置字段以你使用的工具版本为准核心思路是让 Agent 知道去哪里找 SKILL.md。4.7 验证与效果评估用几个典型文件验证技能是否触发准确。准备三个用例用例预期行为结果含 TODO 的文件报告 TODO 及行号应按预期发现含硬编码密钥的文件报告高优问题应按预期发现完全规范的文件报告无问题应按预期输出如果技能没有触发优先检查 SKILL.md 的 description 是否足够明确如果触发了但没有检查出问题检查辅助脚本路径是否被正确读取。实际上技能质量提升的核心就是不断用真实历史问题做回归验证。5. 质量评估体系5.1 评估维度Skill 不是说写完就算完还需要持续评估效果。建议从五个维度建立评估打表维度说明触发准确率需要时是否触发不需要时是否误触发任务完成率技能执行后是否产出预期结果输出质量报告是否正确、可执行、覆盖关键风险上下文消耗执行技能消耗的 token 数量人工介入次数用户需要纠正多少次才能得到满意结果触发准确率是最容易被忽略但最重要的指标。一个描述含糊的 Skill 会在不相关的对话中频繁误触发浪费上下文窗口还让用户反感。5.2 评估流程建立一个小规模基准集例如 10 到 20 个历史真实任务覆盖正常代码、问题代码、边界情况。每次调整 Skill 后都跑一遍基准集记录通过率。基准集示例case-001: 含 SQL 拼接漏洞的 Python 文件 case-002: 规范提交的 Java 文件 case-003: 含 TODO 的 TypeScript 文件 case-004: 超长文件中遗漏遗留标记的边界场景对每个 case 记录触发情况、报告质量、耗时和 token 成本。持续跑基准集的责任可以交给 CI 脚本在技能仓库更新时自动触发。5.3 持续优化闭环质量评估不是一次性工作而是闭环。每次使用技能后收集用户的纠正反馈例如“这个报告漏了缓存问题”“这个风险级别定高了”。定期把反馈整理成新规则更新到 SKILL.md 和辅助脚本中。优化的重点不是让 SKILL.md 越来越长而是让规则越来越精准。如果描述文件超过一千行Agent 反而难以抓住核心。经验是把复杂规则尽可能放进脚本把“何时使用”和“关键步骤”放在 SKILL.md 中保持描述文件精简。6. 常见问题与排查思路6.1 安装与启动类问题现象常见原因解决思路claude命令找不到npm 全局路径未加入 PATH执行npm config get prefix并检查 PATH安装时提示 Node 版本过低Node.js 版本不符合要求升级 Node.js 到官方推荐版本启动时提示网络连接异常本地请求转发配置错误检查环境变量中是否有残留的 API 地址配置提示所在国家或地区不可用官方支持范围限制查看官方支持地区列表遵守服务条款关于“国家不可用”的问题需要理性看待。这属于服务范围限制不是技术配置能解决的问题。如果你所在地区不在支持列表内就不要使用非正规手段绕过而是把精力放在官方支持范围内的方案上。6.2 认证与模型类问题现象常见原因解决思路codex auth token is unavailable登录状态失效或 token 配置错误重新登录检查环境变量是否覆盖了 token模型名不被支持配置了不存在的模型名查询当前版本支持的模型列表修改模型名提示需要手机号验证账号安全策略要求按官方流程完成验证模型名报错是接入第三方模型时的常见坑。例如网上流传的某个模型名可能只存在于某个中间网关并不被官方工具直接支持。遇到model is not supported这类错误不要怀疑工具坏了先回到模型列表确认名称。6.3 Skill 加载类问题现象常见原因解决思路技能完全不触发description 不清晰或技能目录路径未配置明确描述触发场景检查路径配置技能触发但脚本不执行脚本路径写错或权限不足检查 SKILL.md 中的路径引用确认脚本可执行技能内容太多导致混乱SKILL.md 过长且重复精简描述文件把规则下沉到脚本一个容易被忽略的点是SKILL.md 中的相对路径是相对于技能目录的不是相对于项目根目录的。如果脚本路径写错Agent 会尝试读取失败后自行发挥产出就会不稳定。6.4 上下文超限与性能问题上下文接近上限时Agent 的行为会变得奇怪答非所问、丢失早期指令、重复读取文件。遇到这类问题优先压缩上下文而不是继续追问。长期方案是优化任务拆解减少单次会话的输入量。如果技能执行很慢常见原因是脚本里做了全量扫描。控制扫描范围例如只扫描 diff 涉及的文件而不是扫描整个仓库性能会明显提升。7. 团队级落地与工程建议7.1 建立统一 Skill 仓库团队落地 Skill 的第一步是建立统一的 Git 仓库管理技能资产。仓库结构建议按领域划分skills/ review/ code-review/ security-review/ devops/ database-migration/ deployment-check/ docs/ api-doc-generator/ shared/ common-utils/统一仓库的好处非常明显版本可追溯、变更可审查、新人可学习。Skill 的每一次更新都走代码审查流程和普通代码一样进行 diff 评审避免“某个人的经验只存在于他的本地目录”。7.2 命名与结构规范Skill 命名使用短横线风格例如code-review、db-migration避免使用空格和大写。每个 Skill 必须包含 SKILL.md最好包含独立的 scripts 和 resources 目录。SKILL.md 中必须有明确的name和description且description要写触发条件。建议在仓库根目录放一份 README说明每个技能的适用范围、维护人和更新记录。这样当团队规模扩大后不会出现“技能有人用没人维护”的情况。7.3 安全与权限最小化企业环境里Agent 的权限控制是底线问题。原则如下默认只读写操作需人工确认。禁止 Agent 执行未列入白名单的危险命令。密钥和敏感配置不写入 Skill 仓库。日志中不记录 token 和密钥。具体实现时可以在工具配置中声明危险命令禁止列表。团队越大越要强调安全边界因为 Agent 的失误在多人使用时会被放大。这里没有“信任 Agent”的说法只有“配置是否正确”的说法。7.4 发布与灰度策略Skill 发布不建议直接全量替换。先从试点团队开始运行一段时间收集反馈再推广到全公司。灰度期间重点关注触发准确率和人工介入次数这两个指标能直观反映技能质量。版本管理建议使用语义化版本号例如1.0.0、1.1.0。每次变更必须更新 CHANGELOG说明改动点。发布后如果发现问题可以通过 Git 回滚到上一个版本避免影响线上使用。7.5 成本与效能度量AI 编程助手的成本不能只看订阅价格还要看 token 消耗和人工修正成本。建议记录以下数据每个任务的 token 消耗。每次会话平均耗时。用户接受 AI 输出而无需修改的比例。技能触发率和误触发率。成本控制的几个实用手段限制单次任务的输入文件数量、及时压缩上下文、把高频操作固化为 Skill 而不是反复用对话描述需求。固化为 Skill 后输入更精简输出更稳定token 成本自然下降。8. 总结与学习路线从工具下载到团队级落地Claude Code 与 Codex 的 Agent Skill 体系并不是高不可攀的架构而是一套可以逐步搭建的方法。核心可以概括为几句Skill 把流程固化成可复用模块上下文控制决定 Agent 是否聚焦工具权限决定 Agent 能否安全执行质量评估决定技能能否持续变好。如果刚接触这个概念我建议按照下面顺序推进第一周在个人项目中安装 Claude Code 和 Codex完成账号认证和基础对话重点熟悉终端工作流。第二周为个人项目搭建一个最简 Skill例如“生成单元测试”或“检查遗留标记”体验从 SKILL.md 到脚本的完整流程。第三周把其中一个 Skill 放到团队试点建立基准用例开始记录触发准确率和人工介入次数。第四周根据试点反馈完善技能整理安全边界和发布流程形成团队级 Skill 仓库。如果只记住一条经验我会选择不要把希望寄托在让 Agent 更聪明而要把做正确事情的规则放进 Skill 里。AI 的规划能力一直在变强但稳定可靠的能力封装才是企业研发提效的立足点。希望这份整理对你有所帮助可以先收藏等真正搭建技能体系时再对照实践。