摘要面向已用 Claude Code 写代码的开发者讲清 Agent Skills 三层结构与实操路径帮你把重复工作流封装成可复用、可版本管理的技能包。导读如果你每次写技术文档都要粘贴同一段「格式要求 审校清单」这篇文章能帮你把这套流程固化成 Skill让 Claude 自动按规矩办事。上个月我把配图规范、输出模板打包成一个 Skill 文件夹。再次执行同类任务时Claude 没再问「摘要多长」直接按验收标准输出。我才真正意识到Skills 不是更长的 Prompt而是可 PR、可 Review 的 SOP 包可能有人会问这和 Cursor Rules、MCP 有什么不一样下文会专门对比。全文路线痛点 → 三层结构 → 加载链路 → 实操 → 资源层 → 与 MCP 分工 → 跨工具 → 落地建议。一、重复劳动藏在「每次都要讲一遍」里AI 编程助手越来越强团队里最高频的脏活往往不是写算法而是固定格式、固定步骤、固定验收的流水线按模板写 Release Note、按规范做 Code Review、把字幕整理成带截图的笔记。常见两种做法都不太理想每次手写长 Prompt漏步骤、换人就换风格还占上下文。把全部规范塞进 Rules 或 MCP启动就全量加载Token 贵维护也痛苦。Agent Skills 换了一个思路先给 Agent 一份「技能目录」只有任务匹配时才展开完整说明书。2025 年 12 月 Anthropic 把这套机制推成开放标准 agentskills.ioCodex、Cursor 等工具也在跟进——但目录约定、渐进式加载、/skills命令这套组合拳在 Claude Code 里仍然最完整。下面这张演进图帮你看清时间线——不必追每一个工具首发抓住「文件夹 SKILL.md 按需加载」即可。二、三层结构像 SOP 手册不像百科全书我不把 Skills 叫「带目录的说明书」——太抽象。更贴切的类比是值班 SOP 手册元数据层封面上的「科室 适用场景」夜班 / 过敏处置指令层值班步骤正文先问什么、再做什么、禁止什么资源层附录里的检查表、剂量表、可执行脚本只有封面信息在交班时人人可见真正打开某一章才加载对应正文和附录。Agent Skills 的三层与此同构层级放什么何时进入上下文元数据name、descriptionYAML frontmatterClaude Code 扫描时指令SKILL.md正文里的流程、约束、输出格式Agent 决定启用该 Skill 后资源scripts/、references/、assets/Agent 按指令需要时 Read 或执行核心概念到此为止只保留三个渐进式披露、三层结构、SKILL.md 入口。其余如 Cursor 的.cursor/skills/放到后文对照避免百科堆砌。三、长 Prompt、Skills、MCP三种方案各管什么在动手写第一个 Skill 之前先把三种常见方案摆到一张图里。很多人第一次接触 Skills 时会困惑既然 MCP 也能挂工具为什么还要多一层维度长 PromptAgent SkillsMCP核心资产一次性文本Markdown 指令 可选脚本工具 Server上下文每次全量粘贴渐进加载通常更省 Token工具 schema 往往常驻适合一次性探索SOP、写作规范、审查清单GitHub、数据库、浏览器等维护难版本化Git 追踪文件夹需维护服务进程说白了长 Prompt 适合试想法Skills 适合固化流程MCP 适合连外部系统。三者不是替代关系后面第七节会讲怎么组合。四、Claude Code 里的真实加载链路理解结构之后看一次调用链比背定义有用。你在项目根目录启动claude输入需求或拖入文件Claude Code 扫描.claude/skills/**/SKILL.md把各 Skill 的description汇总成列表发给模型模型判断要不要启用某个 Skill若启用再把指令正文与资源按需拉进上下文。这里有个细节值得强调scripts/里的 Python 或 Shell 不会整文件塞进 Prompt。Agent 通过 Bash 工具执行脚本脚本逻辑留在磁盘上——这正是 Skills 能同时「可编程」又「省 Token」的原因。我第一次给 Skill 挂 ffmpeg 截图脚本时还担心模型会把几百行代码读进去实际跑下来上下文里只有执行结果 JSON体验明显更轻。五、环境准备与第一个 Skill以下以 2026 年中版本为准发布前请核对 Claude Code 官方页搜Claude Code install。macOS / Linux / WSL常用安装方式curl-fsSLhttps://claude.ai/install.sh|bashWindows可参考官方安装器或包管理器说明。装好后在终端执行claude--versionclaude有 Claude 订阅账户可直接浏览器 OAuth 登录。若需接入第三方兼容端点可在用户目录~/.claude/settings.jsonWindows 为C:\Users\{用户名}\.claude\settings.json配置ANTHROPIC_BASE_URL与ANTHROPIC_AUTH_TOKEN——具体字段以你使用的服务商文档为准也可以直接使用cc switch工具完成切换。5.1 目录约定Claude Code 识别两类位置作用域路径适用项目级{项目}/.claude/skills/{skill-name}/仅当前仓库全局~/.claude/skills/{skill-name}/所有项目每个 Skill 是一个文件夹必须包含大写的SKILL.md注意大小写。标准目录长这样下面示例换成规范化 Git 提交信息便于团队推广--- name: commit-msg-writer description: - 根据 git diff 生成 Conventional Commits 格式提交说明。 在用户要求写 commit message、总结暂存变更时使用。 --- # 提交信息生成 ## 步骤 1. 运行 git diff --staged 获取变更 2. 判断 typefeat / fix / docs / refactor / test / chore 3. 标题 ≤ 72 字符正文说明「为什么」而非「做了什么」 4. 输出可直接粘贴到 git commit -m 的文本块 ## 禁止 - 不要编造未出现在 diff 中的文件 - 不要使用「更新代码」「修改 bug」等空泛描述元数据里的description 是触发器写清楚「什么情况下该用这个 Skill」比写长 name 更重要。5.3 验证 Skill 已被发现在项目根目录启动 Claude Code输入/skills六、资源层让 Skill 从「会说」到「会做」开放标准建议的目录布局如下与 Claude Code 实践一致my-skill/ ├── SKILL.md ├── scripts/ # 可执行脚本按需 Bash ├── references/ # 长文档、范文、规范 └── assets/ # 图片、模板等静态资源典型用法scripts/确定性操作ffmpeg 截帧、跑 linter、生成 CSV。指令里写「完成后执行python scripts/xxx.py」不要把脚本全文贴进 SKILL.md。references/风格范文、API 字段说明、团队规范。指令里写「写技术文前先 Readreferences/style-guide.md」。assets/Logo、封面模板等静态资源。七、Skills 和 MCP分工而不是二选一社区里常见「Skills 要取代 MCP 吗」的争论。我的结论是一个管「怎么想」一个管「怎么连外部系统」。维度Agent SkillsMCP核心资产Markdown 指令 可选脚本工具 ServerAPI 封装上下文渐进加载通常更省 Token工具 schema 往往常驻适合SOP、写作规范、审查清单GitHub、数据库、浏览器等开发成本低会写 Markdown 即可中高需维护服务进程执行稳定性脚本依赖本机环境封装好后跨机器更一致八、跨工具与社区资源Skills 文件夹的可移植性是开放标准的最大红利Codex项目内.codex/skills/需在~/.codex/config.toml开启skills true实验功能以官方文档为准Cursor个人技能~/.cursor/skills/项目技能.cursor/skills/勿与内置skills-cursor目录混淆迁移时通常只需复制文件夹并改顶层配置目录名SKILL.md本体可复用。九、落地建议与 FAQ什么时候该写 Skill同一类任务你已经在第 3 次粘贴同一段 Prompt团队要把「写法」和「验收标准」固化成可 PR 的文本资产流程里有多份参考文档但不希望每次全量塞进上下文什么时候别硬上 Skill强依赖统一运行环境的后端任务 → 优先 MCP 或 CI一次性探索性提问 → 直接对话更轻Cursor 用户必须转 Claude Code 吗不必。理解 Skills 的「三层 渐进披露」思想后在 Cursor 里用.cursor/skills/同样成立本文以 Claude Code 为主是因为其/skills命令与目录约定目前文档最全、行为最可预期。写在最后Agent Skills 不是又一种 Prompt 技巧而是把团队 know-how 文件夹化、版本化、按需加载的工程手段。以 Claude Code 为起点你可以从一个小 Skill提交信息、Review 清单、文档模板做起再逐步挂脚本和 MCP。如果还没有动手建议今天就建/.claude/skills/hello-skill/SKILL.md跑通/skills比读十篇概述都有用。