1. 从重复提示词到可维护技能Agent Skill 到底解决什么问题如果你已经在 Claude Code 里写过几十次「帮我按团队规范生成 commit message」「把这段代码按 ESLint 规则格式化后再跑测试」你会发现一个尴尬的事实每次都要重新描述一遍要求模型每次的理解还略有偏差。Agent Skill 就是把这个过程沉淀下来的机制——它让 Claude Code 通过一个SKILL.md文件加若干 Bash 脚本自动发现、按需加载、稳定执行你定义好的操作流程。简单说Agent Skill 是 Claude Code 里用来扩展能力的文件化机制。核心是一个放在项目目录下的SKILL.md里面用 YAML 元数据描述「这个技能叫什么、什么时候用」用 Markdown 正文写「触发后具体怎么做」。配套的scripts/目录放 Bash 或 Python 脚本让确定性操作交给脚本执行而不是让模型临场发挥。它适合谁适合每天在终端里用 Claude Code 写代码、跑测试、做代码审查并且已经积累了一批重复操作流程的开发者。和 LangChain Tools、OpenAI Plugins 那类通用 Agent Skill 相比Claude Code Skill 有几个关键差异。通用方案通常需要你在代码里显式注册工具类把 Schema 塞进 Prompt模型输出 JSON 参数再回调函数。Claude Code Skill 则是文件即技能你只要把目录放对位置Claude Code 启动时自动扫描元数据常驻加载正文按需注入。这个「渐进式披露」的设计很关键——元数据层只占很少 token只有当 Claude 判断要用这个技能时才把完整指令读进上下文。执行环境也不同通用方案跑在沙箱或云端Claude Code Skill 直接在你本地终端运行能访问文件系统、执行 git 命令、调用本地工具链。我试过把一个团队代码规范检查流程从「每次粘贴提示词」改成 Skill 之后最大的感受不是省了几行字而是结果稳定了。以前模型有时跳过某条规则现在脚本里写死的检查步骤不会漏。下面我会从目录结构、字段模板、Bash 脚本示例到加载调用和验证完整走一遍。2. TaoToken 前置准备给 Claude Code 配好可用的模型入口在写 Skill 之前得先确保 Claude Code 能正常调用模型。Claude Code 本身是终端工具它需要一个兼容 Anthropic API 的入口来发请求。TaoToken 提供的就是这个入口——你拿到 API Key 和 Base URL 后Claude Code 就能通过它调用模型进而加载和执行你写的 Skill。这一步不是可跳过的「注册教程」而是后面所有验证的前提。因为 Skill 的触发依赖模型理解你的自然语言请求如果模型入口没配好SKILL.md写得再规范也不会被加载。你需要准备三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面创建创建后只显示一次复制保存好。Model ID 根据你实际要用的模型填比如 Claude 系列对应的模型标识。配置方式有两种。第一种是环境变量适合临时测试export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key第二种是写进 Claude Code 的配置文件适合长期使用。Claude Code 的配置通常放在用户目录下的.claude/settings.json你可以这样写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Codex 或 Cline 这类工具配置思路类似但字段名不同。Codex 的auth.json里需要填base_url和api_keyCline 的 MCP 配置里则是baseUrl、apiKey、model三件套。不管哪个工具核心都是 Base URL Key Model ID 这三项对齐。配好之后先别急着写 Skill用一条最简单的请求验证入口通不通curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }如果返回里能看到content字段和模型输出说明入口正常。这一步过了再进 Claude Code 里跑claude命令它应该能正常对话。如果这里就报 401先检查 Key 有没有复制完整、有没有多余空格。入口通了Skill 才有意义。3. 可复制配置SKILL.md 目录结构与字段模板现在进入正题。一个 Claude Code Skill 的完整目录长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── check.sh ├── assets/ │ └── report-template.md └── references/ └── style-guide.mdSKILL.md是必需的核心文件。scripts/放 Bash 或 Python 脚本让技能在流程中调用本地工具比如 lint、format、跑测试。assets/放模板文件比如报告模板、PR 描述模板减少模型临场发挥导致的格式漂移。references/放参考资料比如团队代码规范、API 文档摘录。注意一个原则同一份信息不要同时出现在SKILL.md和references/里。如果信息量大把简略版放SKILL.md详细版放references/。SKILL.md本身是 YAML 元数据加 Markdown 指令的混合体。文件最顶部用---包裹的部分是元数据Claude Code 启动时就会加载用来判断这个技能是否可用、何时可用。关键字段有两个--- name: code-review-check description: 按团队规范检查代码变更。当用户要求审查代码、检查提交、或提到 code review 时使用。不适用于纯文档修改。 ---name通常和文件夹名一致。description极其重要因为 Claude 靠这段文字做语义匹配。它要包含三块信息具体能力能干什么、触发场景什么时候用、使用限制什么情况下不用。写得太笼统比如只写「检查代码」模型可能在该触发时不触发或在不该触发时误触发。元数据下面是 Markdown 正文也就是技能被触发后注入上下文的 Prompt。完整结构可以包含这些部分但很多不是必须的## 目标与范围 检查当前 git 暂存区的代码变更输出问题清单。 ## 输入要求 用户需提供或确认要检查的文件范围默认检查 git diff --cached。 ## 输出协议 必须输出 JSON包含 file、line、severity、message 四个字段。 ## 约束规则 禁止修改代码只做检查。禁止对未变更的文件发表意见。 ## 操作步骤 1. 运行 scripts/check.sh 获取变更文件列表 2. 逐个文件读取 diff 内容 3. 对照 references/style-guide.md 逐条检查 4. 按输出协议生成 JSON ## 决策规则 如果变更涉及配置文件优先级提升为 high。如果检查脚本报错先报告错误再继续。这个模板不是让你全填满而是给你一个参照。实际写的时候目标、输出协议、操作步骤这三块最值得写清楚因为它们直接决定模型行为是否稳定。约束规则也很关键它防止模型越界做你没让它做的事。配套的 Bash 脚本放在scripts/check.sh比如#!/usr/bin/env bash set -euo pipefail # 获取暂存区变更文件列表 git diff --cached --name-only --diff-filterACM脚本要尽量做确定性的事把「判断」留给模型把「执行」交给脚本。这样既快又省 token还不会因为模型理解偏差导致操作错误。4. 验证请求与成功结果在 Claude Code 中加载调用技能文件写好后怎么让 Claude Code 发现它Claude Code 会自动扫描项目目录中的 Skill 定义不需要你写注册代码。通常把技能目录放在项目的.claude/skills/下或者按 Claude Code 文档约定的位置放置。放好后启动claude它会在初始化时读取所有技能的元数据。验证技能是否被加载最直接的方式是问它。在 Claude Code 对话里输入你当前有哪些可用的 skill如果配置正确它应该能列出你刚创建的code-review-check并复述 description 里的内容。这一步能过说明元数据层已经被正确读取。接下来验证触发。故意说一句和 description 里触发场景匹配的话帮我审查一下当前暂存区的代码变更如果技能被正确触发Claude 会按照SKILL.md正文里的操作步骤执行先跑scripts/check.sh再读 diff再对照规范检查最后按你定义的 JSON 格式输出。你可以在终端里看到它执行 Bash 命令的过程。一个成功的输出大概长这样[ { file: src/utils/format.js, line: 12, severity: medium, message: 函数名使用了驼峰团队规范要求工具函数用下划线分隔 } ]如果输出格式和你定义的输出协议一致说明技能生效了。如果模型没触发技能而是用自己的方式回答了先检查 description 里的触发词是否覆盖了你说的那句话。语义匹配靠的是描述文字不是关键词硬匹配所以描述要写得自然、覆盖常见说法。验证通过后你可以把这个技能目录提交到团队仓库其他成员拉下来就能用。这就是「沉淀」的意义——重复提示词变成了可版本管理的文件。5. 本篇常见错排查401、技能不触发、脚本报错怎么处理实际落地时报错集中在几个地方。我按真实遇到的顺序列一下。401 或 authentication_error。这通常不是 Skill 的问题而是模型入口没配好。检查ANTHROPIC_API_KEY是否完整、有没有前后空格、是否过期。如果你用的是 settings.json确认 JSON 格式合法没有多余逗号。还有一种情况是 Base URL 写成了带路径的形式比如https://taotoken.net/api/v1而 Claude Code 期望的是https://taotoken.net/api多一层路径会导致请求打到错误端点。技能不触发。模型没按预期加载你的 Skill九成是 description 写得不够好。常见错误是只写了能力没写场景比如description: 检查代码。模型不知道什么时候该用它。改成「当用户要求审查代码、检查提交、或提到 code review 时使用」之后触发率会明显提升。另一个原因是技能目录位置不对Claude Code 没扫描到。确认目录在约定的 skills 路径下且SKILL.md文件名大小写正确。local proxy failed 或连接超时。这类报错说明请求没到达模型入口。检查网络是否能访问taotoken.net以及本地有没有其他工具占用了 Claude Code 需要的端口。如果你在 settings.json 里同时配了环境变量和文件配置可能产生冲突建议只保留一种。reading choices 相关报错。这通常出现在模型返回格式和预期不符时。如果你的 Skill 输出协议要求 JSON但模型返回了 Markdown 包裹的 JSON解析就会失败。解决办法是在SKILL.md的输出协议里明确写「只输出 JSON不要用代码块包裹」并在约束规则里强调。脚本执行失败。scripts/check.sh报错时先单独在终端跑一遍确认脚本本身没问题。常见原因是脚本没有执行权限需要chmod x scripts/check.sh。另一个原因是脚本里用了相对路径而 Claude Code 执行时的工作目录和你手动跑时不同。脚本里尽量用git rev-parse --show-toplevel获取仓库根目录再拼绝对路径。OAuth 相关报错。如果你之前用 OAuth 方式登录过 Claude Code切换成 API Key 后可能残留旧凭证。清理掉旧的认证缓存重新用 Key 配置。Codex 的auth.json里如果同时存在 OAuth token 和 api_key也可能冲突保留 api_key 即可。排查顺序建议是先确认模型入口通curl 能返回再确认技能被加载问它有哪些 skill最后确认触发和执行说触发词看行为。一层层往下比一上来就改SKILL.md高效得多。6. 把技能用起来从单个 Skill 到可维护的技能库单个 Skill 跑通之后真正的价值在于积累。团队应该逐步建立自己的技能库把代码规范检查、提交信息生成、测试脚手架、部署前检查这些重复流程都沉淀成 Skill。获取现成技能的渠道有几个Anthropic 官方维护的 skills 仓库、obra/superpowers 这类面向工程团队的套件、skills.sh 社区精选。但团队专属的业务规范还是得自己写。随着技能增多冲突会出现。两个技能都声称处理「代码检查」时模型可能选错。解决办法是在SKILL.md里指定优先级或者把技能设计成互斥的或者在 description 里明确「当 X 技能可用时优先使用 X」。另一个原则是保持精简单个SKILL.md最好小于 500 行超出的内容转向references/减少 token 消耗。组合方面一个 Skill 只做一件事不要做万能 Skill。不同技能之间可以通过指定方式组合链式调用或有向无环图都行。比如「生成提交信息」技能可以调用「检查代码规范」技能的结果作为输入。尽可能脚本化——能用 Bash 或 Python 脚本实现的确定性操作不要放在SKILL.md正文里描述脚本更快、更确定、更省 token。定期迭代也很重要。用 skill-creator 生成初版后根据实际触发情况和输出质量做微调。description 的措辞、输出协议的格式、约束规则的边界都是需要反复打磨的地方。如果你还没配好模型入口先去控制台创建 API Key参考接入文档把 Base URL 和 Key 填进 Claude Code。想先验证模型对话是否正常可以用模型对话页面发一条测试请求。长期在终端里做编码和 Agent 任务的Coding Plan 会更适合持续使用。技能库建起来之后你会发现 Claude Code 从一个「每次都要交代清楚」的工具变成了一个「懂你团队规矩」的协作伙伴。