前几周我在几个技术社群里看到同一个现象大家用 Claude Code 和 Codex 已经不再满足于“聊天写代码”而是开始讨论怎么把一套固定的开发规则、代码规范、审查清单保存下来让 AI 助手在每次任务里都自动遵守。有人管这叫 Skill有人叫 Skills有人叫 Agent Skill还有人直接说“这不就是提示词工程的高级版吗”。这个讨论背后其实是 AI 编程助手从“会话级工具”走向“团队级工程资产”的关键转折。如果你还停留在每次打开终端、手动粘贴一段提示词让 Claude 或 Codex 干活的阶段那你实际使用的只是这两个工具最基础的形态。真正拉开效率差距的是把经验沉淀成可复用、可版本管理、可团队共享的 Skill。这篇文章会从概念讲起对比 Claude Code 和 Codex 的 Skill/Agent 机制差异给出手工创建 Skill 的完整示例然后讨论上下文控制、质量评估和团队落地的工程方法。1. 这篇文章真正要解决的问题先问一个现实问题在一个 10 人研发团队里为什么使用 AI 编程助手的产出质量参差不齐常见答案是人跟人的提示词水平不一样。这个回答只对了一半。更准确地说是“个人经验”没有变成“团队资产”。一位资深工程师知道项目里数据库变更必须写回滚脚本、知道日志里不能打印敏感字段、知道测试用例要覆盖边界条件这些经验如果能被 AI 助手在每个任务中自动遵守团队整体效率会上一个台阶如果只能靠每个人临场写提示词那 AI 助手就永远是“高级补全工具”。Agent Skill 解决的正是这个问题。它把一套指令、规则、示例代码和工作流程打包成结构化文件放在约定目录下AI 助手在执行相关任务时自动加载并遵循。这意味着新人不需要自己摸索提示词直接继承团队经验。代码规范和审查清单不再躺在 Wiki 里吃灰而是进入 AI 的执行上下文。团队可以像管理代码一样管理“AI 行为规范”评审、迭代、回滚都成为可能。这篇文章面向的读者很明确已经安装过 Claude Code 或 Codex但还没系统使用过 Skill 的开发者以及在团队里推动 AI 研发提效需要一套可落地方案的技术负责人。读完你会理解 Skill 与 Agent 的本质区别能手工创建自己的第一个 Skill知道如何通过上下文控制避免 AI“乱加载”并且掌握一套评估 Skill 质量的指标和排查问题的方法。2. Agent Skill 的核心概念它和提示词、Agent 有什么区别先把概念边界说清楚。Skill 这个词在不同工具里含义略有差异但核心思想一致它是一段“可复用的能力封装”。你告诉 AI“用 Python 的 FastAPI 写一个用户登录接口”这是一次性提示词你把“如何在本项目里编写 FastAPI 接口”的规范、代码模板、检查清单做成一个文件放到约定目录让 AI 在相关任务里自动参考这就是一个 Skill。很多文章把 Skill 和 Agent 混在一起讲其实两者维度不同。Agent 是执行任务的智能体它负责理解目标、调用工具、规划步骤、生成代码Skill 是 Agent 可以加载的“能力模块”相当于给 Agent 增加一种专业技能。类比一下Agent 是员工Skill 是这个员工的工作手册和操作规范。员工还是那个员工但有了手册之后他的工作质量下限会明显提高。系统提示词System Prompt和 Skill 也容易混淆。系统提示词是对话开始时就注入的全局指令通常描述 AI 的角色和总原则Skill 则是按需加载的局部知识只有任务匹配时才进入上下文。一个典型的区分是系统提示词回答“你是谁、你总体怎么工作”Skill 回答“遇到某类具体任务时你应该遵循哪些步骤和规则”。从工程视角看两者最大的差别在于管理方式。系统提示词往往写死在应用配置里改起来要发版Skill 以文件形式存在可以放在项目仓库里走 Git 管理也可以在用户目录下统一维护。这个差异对团队落地至关重要。对比维度一次性提示词系统提示词 / CLAUDE.mdAgent Skill作用时机每次任务临时输入会话开始时自动加载任务匹配时按需加载复用性低中高版本管理不可管理可管理但粒度较大按技能维度独立管理团队共享很难可以但易膨胀天然适合典型内容具体任务指令全局角色与规则步骤、模板、检查清单、示例3. 当前生态Claude Code 与 Codex 的 Skill 机制对比先说 Claude Code。它的 Skill 机制建立在项目记忆和工作区的基础上。你在项目中可以通过 CLAUDE.md 定义持久规则也可以在用户目录~/.claude/下维护全局规则。Skills 则放在~/.claude/skills/或项目.claude/skills/目录下每个技能是一个目录内部包含SKILL.md作为入口文件里面用 frontmatter 声明技能的名称和描述正文写具体的指令、步骤和示例。更关键的是 Skills 中的conversation目录它可以存放一段会话记录作为示例让 AI 学习“这类任务应该怎么对话和拆解”。如果你完成过一次高质量的任务可以把那段对话沉淀成 Skill 的示例下次遇到类似任务时 AI 就有了参照。Codex 的 Agent 机制也很接近。Codex CLI 支持使用AGENTS.md文件描述项目的协作规则和默认行为Codex 也能识别 skills 目录中的能力定义。两者在理念上高度一致都是把任务规则从“一次性提示词”中解放出来变成文件系统中的一等公民。差异主要体现在生态和习惯上。维度Claude CodeCodex全局规则文件~/.claude/CLAUDE.md~/.codex/AGENTS.md项目规则文件./CLAUDE.md./AGENTS.md技能目录.claude/skills/或~/.claude/skills/支持 skills 目录与自定义 Agent 配置技能入口SKILL.md含 frontmatter 和正文以 Markdown 描述能力、指令和示例会话示例conversation/目录存放参考对话可在技能描述中嵌入示例片段从当前生态看Claude Code 的 Skills 目录结构更标准化适合作为团队模板Codex 的 Agent 能力与 OpenAI 模型家族的协作更紧密如果你主要使用 Codex 接入不同模型也可以参考相同的“目录即技能”思路来组织知识。4. 环境准备与安装把 Claude Code 和 Codex 跑起来在创建 Skill 之前先把工具安装好。如果你已经用过这两个工具可以跳过这一节如果你是第一次接触建议按下面流程走一遍。4.1 安装 Claude CodeClaude Code 目前主要依赖 Node.js 环境。安装前先确认本机有 npmnode -v npm -v然后全局安装npm install -g anthropic-ai/claude-code安装完成后在项目目录里运行cd your-project claude首次使用会要求登录或配置认证信息。如果在启动时看到地区不可用之类的提示可以参考官方支持范围开发环境的网络出口也会影响模型服务的连通性遇到连接失败时优先检查网络链路而不是反复重装。4.2 安装 Codex CLICodex 同样提供 npm 安装方式npm install -g openai/codex运行codexCodex 登录时会校验账号和模型访问权限。从实际使用经验看很多“打不开”的报错都集中在认证失败和本地网络异常两类原因上排查时先看认证状态再看模型服务是否可达。4.3 最小验证确认工具能完成一次对话装完之后不要急着配 Skill先跑一个最小任务确认工具链路通畅。比如让 Claude Code 回答当前目录结构claude 列出当前项目的目录结构并说明每层的职责如果系统给出结构清晰、符合常识的回答说明基础链路没问题。Codex 同样操作一遍。只有工具本身稳定后续调试 Skill 才不会陷入“到底是配置错了还是工具坏了”的泥潭。5. 手工创建第一个 Agent Skill完整示例这一节我们手工创建一个名为python-api-review的技能。它定义的任务是当 AI 需要审查一个 Python API 项目的代码时自动加载团队规范按清单逐项检查并输出结构化报告。5.1 创建目录结构在 Claude Code 的项目工作区里目录如下.claude/ └── skills/ └── python-api-review/ ├── SKILL.md ├── reference/ │ └── api-review-checklist.md └── conversation/ └── example-conversation.md每个组成部分的职责SKILL.md技能入口描述技能名称、触发条件和执行步骤。reference/存放技能运行时的参考材料比如审查清单。conversation/存放一次高质量会话记录AI 可以参考它理解任务节奏。5.2 编写 SKILL.md--- name: python-api-review description: 审查 Python API 项目代码时使用。主要检查路由设计、参数校验、异常处理、数据库访问安全、日志规范和代码风格。 --- # Python API 代码审查 当用户要求审查 Python API 代码时按以下步骤执行。 ## 审查步骤 1. 定位入口文件和应用路由梳理 API 接口清单。 2. 检查每个接口的输入参数是否使用 Pydantic 或等价方式做校验。 3. 检查异常处理是否有未捕获的底层异常敏感错误信息是否直接返回给客户端。 4. 检查数据库访问是否使用参数化查询是否存在 N1 查询风险。 5. 检查日志是否包含请求 ID是否打印了密码、Token、手机号等敏感字段。 6. 输出审查报告报告格式见审查清单。 ## 审查报告格式 - 接口清单 - 严重问题必须修复 - 建议改进可以优化 - 优点是哪些 ## 注意 - 不要直接修改代码除非用户明确要求。 - 对每个问题给出文件和行号。SKILL.md 的 frontmatter 中name和description是 AI 判断是否加载技能的依据。description写得越具体触发越准确写得过于宽泛可能会在无关任务中频繁误加载浪费上下文。5.3 编写参考清单在reference/api-review-checklist.md中存放更细致的审查项# API 代码审查清单 ## 路由与接口设计 - RESTful 路径是否语义清晰 - 是否处理了 HTTP 方法语义 ## 参数与校验 - 是否使用 Pydantic 模型 - 是否校验了必填字段、枚举值、长度边界 ## 异常与错误处理 - 是否有全局异常处理器 - 是否避免向客户端返回堆栈信息 ## 数据层 - 是否使用 ORM 或 SQL 参数化 - 是否处理事务提交与回滚 ## 日志与可观测性 - 日志是否包含 request_id - 是否记录耗时和状态码reference 目录的作用是把细节从SKILL.md正文中抽离避免技能入口文件过长同时让 AI 在需要时可以引用参考文件这也是上下文控制的一部分。5.4 用 conversation 示例教会 AI 任务节奏conversation/example-conversation.md可以放一段简短对话例如用户说“帮我审查一下 payment 模块”理想的助手回复是先列接口清单、再逐项审查、最后给报告。这个文件不是每次必读但加载技能时可以引导 AI 按相同模式完成任务。如果你用的是 Codex概念完全一样在项目根目录维护AGENTS.md并建立 skills 目录组织类似结构Agent 会在任务匹配时读取这些内容。两个工具的字段命名可能不同但工程模式是通用的。6. 上下文控制为什么 Skill 设计必须考虑上下文做完第一个 Skill 之后很多人会立刻遇到新问题技能越加越多AI 的上下文越来越长响应变慢甚至开始“答非所问”。这就是上下文控制没有做好。AI 编码助手每次任务能携带的上下文有限。如果把团队所有规范、所有 Skill 的描述、所有参考文档一次性加载AI 会被信息淹没真正关键的内容反而被稀释。上下文控制的本质是让 AI 在正确的时间只加载当前任务最需要的信息。几个实践原则第一Skill 的description要“窄而准”。它决定了 AI 什么时候加载技能。描述写成“帮助开发人员写代码”就太宽了写成“在用户要求审查 Python FastAPI 接口代码时使用”就更精确。第二不要把所有内容塞进SKILL.md。正文只写核心步骤和决策规则细节放reference/示例放conversation/。这样技能加载时消耗的是少量核心上下文AI 需要细节时才读取参考文件。第三区分全局记忆和按需技能。CLAUDE.md或AGENTS.md适合放项目长期稳定、几乎所有任务都需要的规则具体的执行流程更适合放 Skill。全局记忆和按需技能的关系类似于操作系统的常驻内存与按需加载的插件。第四定期审计技能触发情况。如果一个 Skill 在大量无关任务中被触发说明描述写得不够精确如果一个 Skill 极少触发说明描述与用户实际使用场景不匹配。上下文的优化不是一次性的而是一个持续调参的过程。从团队角度看上下文控制不只是效率问题还是质量稳定性的保障。当一个 AI 助手同时掌握 20 个 Skill 的描述和 10 份参考文档时它输出的稳定性一定下降。好的 Skill 体系应该做到“静若处子动若脱兔”——平时不干扰正常对话遇到匹配任务时精准介入。7. 质量评估如何判断一个 Skill 真的有效Skill 写出来之后怎么判断它有没有用很多团队的做法是“感觉快了”这不够。质量评估需要落到可观察、可比较的指标上。推荐从四个维度评估任务完成率在相同任务集上加载 Skill 前后AI 一次通过的比率。代码正确率对代码生成或审查类 Skill检查产出代码能否通过编译、测试和静态检查。上下文命中率技能是否只在相关任务中触发是否经常误入无关任务。人工返工成本人类工程师 review AI 产出的平均耗时变化。这几个指标不需要复杂的平台就能采集。团队可以先准备一个 20 到 30 条任务的评测集例如“审查某个支付接口”“为某个模型生成 CRUD 代码”“修复某个超时问题”。然后分别在开启和关闭 Skill 的情况下运行任务记录结果。下面是一个简单的评测脚本思路假设你已经用 CLI 跑完任务并输出了结果文件# 文件路径scripts/evaluate_skill.py import json from pathlib import Path def evaluate(result_dir): results [] for result_file in Path(result_dir).glob(*.json): data json.loads(result_file.read_text()) results.append({ task_id: data[task_id], success: data.get(build_passed, False), review_time_minutes: data.get(review_time_minutes, 0), skill_triggered: data.get(skill_triggered, False), }) total len(results) success sum(r[success] for r in results) avg_review_time sum(r[review_time_minutes] for r in results) / max(total, 1) print(f任务总数: {total}) print(f成功数: {success} 成功率: {success / max(total, 1):.2%}) print(f平均人工 review 耗时: {avg_review_time:.1f} 分钟) return results if __name__ __main__: evaluate(results/)在实际操作中对比数据比绝对数字更有价值。同一个任务集不加载 Skill 跑一轮加载 Skill 再跑一轮两轮数据放在一起对比才看得出 Skill 到底是提升了稳定性还是仅仅改变了回答的语气。这里要特别提醒一点评估任务集不能太小3 到 5 个任务得出的结论噪声太大至少要有 20 个代表性任务。质量评估还应该有“回归”意识。Skill 改了一版之后要用旧任务集重新跑一遍确认没有把之前正确的行为改坏。这一点和代码重构非常像没有回归测试的 Skill 迭代最终一定会出现“修了一个问题引入三个新问题”的情况。8. 团队级落地把 Skill 变成工程资产个人使用 Skill 可以很随意但团队落地需要一套工程化思维。这里的核心不是“再买一个 AI 平台”而是把 Skill 当作普通代码资产来管理。8.1 集中管理与版本控制团队应该为 Skill 建一个独立仓库例如team-ai-skills目录按技能维度组织team-ai-skills/ ├── README.md ├── python-api-review/ │ ├── SKILL.md │ └── reference/ ├── database-migration/ │ ├── SKILL.md │ └── reference/ └── scripts/ └── validate_skills.py每个技能目录的命名要统一建议使用领域-动作或动作-对象的格式例如python-api-review、database-migration、frontend-component-gen。命名混乱是 Skill 库腐化的起点因为 AI 依赖 description 判断触发而人类依赖目录名维护仓库两层都必须清晰。8.2 格式校验与 CI 集成既然 Skill 是文本文件就可以像代码一样接入 CI。比如写一个脚本检查每个SKILL.md是否有合法的 frontmatter、name和description是否非空、目录名是否与name一致。脚本思路如下# 文件路径scripts/validate_skills.py from pathlib import Path SKILLS_ROOT Path(.) def validate_skill(skill_dir: Path): errors [] skill_file skill_dir / SKILL.md if not skill_file.exists(): errors.append(f缺少 SKILL.md: {skill_dir}) content skill_file.read_text(encodingutf-8) if not content.startswith(---): errors.append(fSKILL.md 缺少 frontmatter: {skill_dir}) if name: not in content.split(---)[1]: errors.append(fSKILL.md 缺少 name 字段: {skill_dir}) if description: not in content.split(---)[1]: errors.append(fSKILL.md 缺少 description 字段: {skill_dir}) return errors def main(): all_errors [] for skill_dir in SKILLS_ROOT.iterdir(): if skill_dir.is_dir() and not skill_dir.name.startswith(.): all_errors.extend(validate_skill(skill_dir)) if all_errors: for err in all_errors: print(err) raise SystemExit(1) print(所有 Skill 格式校验通过) if __name__ __main__: main()运行方式python scripts/validate_skills.py这一步的价值在于用最低成本保证团队 Skill 库的规范性。如果团队用 GitHub Actions 或 GitLab CI可以在推送时自动执行该脚本不符合格式的技能不允许合入主分支。8.3 评审与试运行机制Skill 变更应该走类似代码评审的流程。新增技能或修改技能描述后建议先在两个真实任务上试运行把输出结果贴到评审记录里确认没有引入风险再合并。评审重点不是“措辞是否优美”而是“该技能在目标场景下是否稳定、是否会被错误触发、是否引入额外的上下文负担”。8.4 与企业现有规范分层团队往往已有编码规范、数据库变更流程、安全审查规则。Skill 不应该是另一套规则而应该是现有规则的“可执行版本”。更推荐的做法是在组织层面维护一份team-rules基础规范然后按技能领域拆分实施细则。例如组织规范规定“生产环境变更必须可回滚”数据库迁移技能则细化成对应的步骤清单。分层的好处是避免同一个规则在多个技能里重复出现、修改时遗漏。8.5 明确边界与风险团队落地 Agent Skill 时要清醒认识它的边界。 Skill 本质上是提示词它不会自动保证代码安全也不会替代人类审查它只是把规范从文档变成了 AI 的执行倾向。涉及权限、认证、数据库变更、生产环境操作的场景必须仍然遵循团队现有的审批流程。Skill 可以辅助生成迁移脚本但执行迁移之前该做的备份、灰度、回滚预案一样都不能少。9. 常见问题与排查思路结合社区中高频出现的问题整理成一张排查表问题现象可能原因排查方式解决方案Claude Code 安装后无法启动Node.js 版本过低或依赖安装不完整查看终端错误信息与npm ls依赖树升级 Node.js 并重新全局安装登录报错或提示在当前地区不可用账号权限、网络出口受限检查官方支持范围与网络连通性确认网络链路后重试必要时联系团队管理员Codex 提示认证 Token 不可用登录态过期或 CLI 与服务端时间不同步检查系统时间重新执行登录流程重新认证并确保本机时间正确cc switch local proxy failed while handling codex endpoint /responses本地代理服务异常或代理目标不可达查看代理进程状态检查代理配置与目标地址可达性修复代理配置或改用直连方式再重新发起请求调用模型时提示model is not supported当前模型名与工具支持的模型列表不匹配查看工具支持的模型核对配置中的模型标识修改模型配置为受支持的模型名称Skill 未被自动加载frontmatter 格式错误或 description 触发条件与用户意图不匹配检查 SKILL.md 格式查看工具日志中的技能匹配记录修正 frontmatter优化 description 关键词上下文越来越长响应变慢Skill 描述过宽、全局规则文件写入过多内容审计各技能触发次数检查配置文件体量将非必要内容移入 reference精简全局记忆同一个任务在开启 Skill 后输出反而变差Skill 内容与项目实际情况冲突对比开启前后的输出定位冲突片段根据项目实际修订 Skill 内容这里单独说一下代理相关报错。很多开发者为了加速依赖安装或请求外部服务会配置本地代理环境变量。当代理服务异常、代理地址失效或代理转发链路不稳定时CLI 请求模型端点就会失败表现就是类似local proxy failed的错误。排查顺序是先确认代理进程是否在运行再检查代理配置里的地址和端口最后看目标服务是否可达。不要一上来就卸载重装工具这类问题多数不是安装问题。10. 最佳实践与工程建议最后把最关键的经验浓缩成几条建议第一从一个小而准的技能开始。不要第一次就试图做“全栈 AI 研发助手”先选择一个高频重复且规范清晰的场景比如代码审查、接口代码生成、数据库迁移脚本生成。跑通之后再做扩展。第二Skill 目录和 frontmatter 要严格控制。目录名对应技能领域name唯一description窄而准。这是团队协作的基础也是 AI 正确触发的前提。第三上下文控制是 Skill 设计的核心能力。核心规则放SKILL.md细节放reference/示例放conversation/。全局记忆文件只放长期稳定的规则一切能按需加载的内容都不要常驻。第四建立评测集让 Skill 迭代有依据。准备 20 个以上代表性任务在每次技能变更后跑回归对比任务完成率和人工 review 耗时。没有评测的 Skill 优化只能叫碰运气。第五团队落地必须做评审和格式校验。把validate_skills.py这类脚本接入 CI把 Skill 变更纳入评审流程用管理代码的方式管理 AI 行为。这不是流程主义而是保证 Skill 库不腐化的最低成本手段。第六安全边界不能因为 AI 而放松。Skill 可以辅助生成 SQL、写部署脚本、分析日志但涉及数据删除、权限变更、生产环境操作时团队审批和人工 review 仍然是必须的。最低权限、先测试后上线、变更可回滚这些原则在任何情况下都不应该被“AI 太强了”冲昏头脑。11. 总结与后续学习方向这篇文章从 Agent Skill 的核心概念讲起对比了 Claude Code 与 Codex 在技能组织方式上的异同然后手工创建了一个python-api-review技能重点讨论了上下文控制、质量评估和团队落地方法。你会发现Skill 本质上没什么高深魔法它就是把“资深工程师的经验”和“项目团队的规范”做成了 AI 可以按需加载的文件资产。真正困难的部分是如何让这套文件资产保持精确、稳定、可持续迭代。下一步的实践路径很清晰。如果你还没用过 Skill先去创建一个最小技能比如把团队代码规范做成一个审查清单在真实任务里验证它的触发效果如果你已经在用 Skill建议转向评估和工程化建立任务集、跑量化对比、接入 CI 校验。再往后值得深入的方向包括多 Skill 之间的冲突消解、Skill 与项目自动生成的文档如何联动、以及如何让 Skill 描述更精准地匹配团队真实工作流。建议把这篇文章收藏起来等真正开始搭建团队 AI 研发体系时直接把这些方法用起来。
