Claude Code 实战：用 Agent Skills 搭建可复用的 SKILL.md 工作流

1. 为什么你的 Claude Code 每次都在重复问同样的问题如果你已经在用 Claude Code 写代码大概率遇到过这种场景每次让它生成技术文档都要重新粘贴一遍「格式要求 审校清单」每次让它做 Code Review都要重新说明团队的分支命名规范和提交信息格式。这些重复劳动的本质是你把本该固化下来的流程每次都当成一次性对话来处理。Agent Skills 就是来解决这个问题的。它允许你把重复性的工作流封装成一个可复用、可版本管理的技能包放在项目目录里Claude Code 在需要时自动加载。你不再需要每次手写长 Prompt也不用把所有规范塞进全局配置里让每次启动都全量加载。这篇文章面向已经用过 Claude Code、想进一步把日常重复任务工程化的开发者。我会从 SKILL.md 的目录结构讲起说清楚渐进式披露机制到底怎么工作然后给出可直接复制的 SKILL.md 骨架配置、MCP 协同调用示例以及用一条命令验证技能是否加载生效的具体操作。全程以 Claude Code 为主因为它的/skills命令和目录约定目前文档最完整、行为最可预期。2. TaoToken 前置让 Claude Code 稳定接入可用模型在开始写 Skill 之前你需要确保 Claude Code 能正常调用模型。如果你使用的是官方订阅账户直接 OAuth 登录即可。但如果你需要通过兼容端点接入或者想在不同模型之间灵活切换TaoToken 是一个值得考虑的接入层。TaoToken 提供统一的 API 入口支持 Claude 系列模型的调用。你可以在 Claude Code 的配置文件中设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN把请求指向 TaoToken 的 API 地址。这样做的好处是你不需要在本地维护多个服务商的密钥也不用担心某个端点临时不可用导致工作中断。具体配置方式是在用户目录下创建或编辑~/.claude/settings.jsonWindows 为C:\Users\{用户名}\.claude\settings.json填入以下字段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的API Key } }API Key 可以在 TaoToken 控制台的 API Keys 页面生成。如果你还没有账号可以先注册再创建密钥。配置完成后Claude Code 的所有模型请求都会经过 TaoToken 转发你可以在控制台看到调用记录和用量统计。注意ANTHROPIC_BASE_URL不要加末尾斜杠否则可能导致路径拼接错误。如果你同时使用多个工具建议用环境变量管理密钥避免明文写在配置文件里提交到 Git。3. SKILL.md 骨架配置从目录结构到渐进式披露Agent Skills 的核心设计思想是「渐进式披露」Claude Code 启动时只扫描每个 Skill 的元数据name 和 description把摘要列表发给模型只有当模型判断某个 Skill 与当前任务匹配时才会加载完整的指令正文资源文件脚本、参考文档、模板则只在指令明确要求时才被读取或执行。这种三层结构可以用一个类比来理解元数据层是手册封面上的「科室 适用场景」指令层是值班步骤正文资源层是附录里的检查表和可执行脚本。交班时人人只看封面真正需要处理某个情况时才翻开对应章节。3.1 目录约定Claude Code 识别两类 Skill 存放位置作用域路径适用场景项目级{项目}/.claude/skills/{skill-name}/仅当前仓库生效适合团队共享全局~/.claude/skills/{skill-name}/所有项目可用适合个人通用技能每个 Skill 是一个独立文件夹必须包含大写的SKILL.md文件。标准目录结构如下my-skill/ ├── SKILL.md # 必需入口文件 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选长文档、规范、范文 └── assets/ # 可选图片、模板等静态资源3.2 SKILL.md 骨架下面是一个可直接复制的 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更重要。Claude Code 会把所有 Skill 的 description 汇总成列表发给模型模型根据当前对话上下文判断是否启用某个 Skill。3.3 资源层的使用方式资源层是让 Skill 从「会说」到「会做」的关键。典型用法scripts/存放确定性操作脚本比如用 ffmpeg 截帧、跑 linter、生成 CSV。指令里写「完成后执行python scripts/xxx.py」不要把脚本全文贴进 SKILL.md。references/存放风格范文、API 字段说明、团队规范。指令里写「写技术文前先 Readreferences/style-guide.md」。assets/存放 Logo、封面模板等静态资源。这里有一个容易被忽略的细节scripts/里的 Python 或 Shell 脚本不会整文件塞进 Prompt。Agent 通过 Bash 工具执行脚本脚本逻辑留在磁盘上上下文里只有执行结果。这正是 Skills 能同时做到「可编程」和「省 Token」的原因。4. 可复制配置MCP 协同调用示例Skills 和 MCP 不是替代关系而是分工关系。Skills 管「怎么想」MCP 管「怎么连外部系统」。一个管流程和规范一个管工具和数据源。假设你有一个 Skill 负责「生成周报」流程里需要从 GitHub 拉取本周的 PR 列表。你可以把 GitHub 的访问封装成 MCP Server然后在 SKILL.md 的指令里调用它--- name: weekly-report description: - 生成本周开发周报包含 PR 列表、代码变更统计和待办事项。 在用户要求写周报、总结本周工作时使用。 --- # 周报生成 ## 步骤 1. 调用 MCP 工具 github.list_prs参数 since 设为 7 天前 2. 调用 MCP 工具 github.get_stats获取代码变更行数 3. 读取 references/report-template.md 获取输出格式 4. 按模板填充数据输出 Markdown 格式周报 ## 输出格式 - 标题本周开发周报YYYY-MM-DD 至 YYYY-MM-DD - 第一部分已合并 PR 列表标题 链接 - 第二部分代码变更统计新增/删除行数 - 第三部分下周待办从 PR 评论中提取 TODO对应的 MCP 配置在~/.claude/settings.json或项目级.claude/settings.json中{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: 你的GitHub Token } } } }这样配置后当你在 Claude Code 里说「帮我写本周周报」模型会识别到weekly-report这个 Skill 的 description 匹配当前任务加载指令正文然后按步骤调用 MCP 工具获取数据最后按模板输出。注意MCP Server 的进程管理由 Claude Code 负责你不需要手动启动。但如果 MCP Server 启动失败Skill 里的工具调用会报错排查时先检查 MCP 配置是否正确。5. 验证请求一条命令确认技能加载生效配置完成后你需要验证 Skill 是否被 Claude Code 正确识别。在项目根目录启动 Claude Code输入/skills这个命令会列出当前所有已加载的 Skill包括项目级和全局的。如果你看到自己创建的 Skill 出现在列表中说明元数据已经被扫描到。接下来做一次实际调用验证。在 Claude Code 里输入帮我写一个 commit message暂存区有变更如果 Skill 配置正确Claude 会自动加载commit-msg-writer的指令正文运行git diff --staged然后按 Conventional Commits 格式输出提交信息。你不需要手动指定使用哪个 Skill模型会根据 description 自动匹配。如果/skills列表里没有你的 Skill按以下顺序排查确认SKILL.md文件名是大写且位于.claude/skills/{skill-name}/目录下确认 YAML frontmatter 格式正确name和description字段没有拼写错误确认启动 Claude Code 时的工作目录是项目根目录而不是子目录如果是全局 Skill确认路径是~/.claude/skills/而不是~/.claude/skill/6. 本篇常见错排查6.1 Skill 不生效/skills列表为空最常见的原因是目录层级不对。Claude Code 要求SKILL.md必须直接位于.claude/skills/{skill-name}/下不能多一层或少一层。比如.claude/skills/SKILL.md是错的.claude/skills/my-skill/SKILL.md才是对的。另一个常见原因是 YAML frontmatter 格式错误。description如果包含冒号需要用引号包裹或者用-折叠写法。比如description: 生成周报包含 PR 列表会因为冒号被解析成键值对而报错应该写成description: 生成周报包含 PR 列表。6.2 Skill 被加载了但模型没有按指令执行这种情况通常是 description 写得不够具体。模型判断是否启用某个 Skill完全依赖 description 的语义匹配。如果你写的是「处理代码相关任务」模型很难判断什么时候该用。改成「根据 git diff 生成 Conventional Commits 格式提交说明在用户要求写 commit message 时使用」匹配精度会明显提高。另外指令正文里的步骤要足够具体。不要写「分析代码变更」要写「运行git diff --staged获取变更」。模型需要明确的动作指令而不是模糊的描述。6.3 脚本执行报错scripts/里的脚本执行失败通常是因为路径问题。Claude Code 执行脚本时的工作目录是项目根目录所以脚本里引用文件要用相对路径或绝对路径不能假设当前目录是脚本所在目录。如果脚本依赖第三方库确保运行环境里已经安装。Claude Code 不会自动帮你装依赖你需要在 SKILL.md 里写明「先执行pip install -r scripts/requirements.txt」或者提前在环境里配好。6.4 MCP 工具调用超时MCP Server 启动慢或者网络不通会导致工具调用超时。排查时先在终端手动运行 MCP Server 的启动命令确认能正常启动。如果是远程 MCP Server检查网络连接和认证信息是否正确。另外MCP 工具的 schema 是常驻上下文的如果你挂了很多 MCP Server启动时的 Token 消耗会明显增加。建议只挂当前项目需要的 MCP Server不用的及时移除。7. 把重复劳动变成可版本管理的技能包Agent Skills 的价值不在于「更长的 Prompt」而在于把团队 know-how 文件夹化、版本化、按需加载。你可以从一个小 Skill 做起比如提交信息生成、Code Review 清单、文档模板跑通/skills验证流程后再逐步挂脚本和 MCP。如果你还没有动手建议今天就建一个.claude/skills/hello-skill/SKILL.md写一个最简单的指令跑一次/skills确认加载生效。这比读十篇概述都有用。当你想把 Skill 接入实际模型调用时可以在 TaoToken 的模型对话页面测试不同模型对同一 Skill 指令的响应效果找到最适合你任务场景的模型组合。对于需要长期编码和 Agent 协作的场景Coding Plan 提供了更稳定的调用额度和管理能力。配置过程中如果遇到 API Key 或接入问题可以查阅接入文档获取详细的参数说明。