1. 从一次技能不触发说起Claude Agent Skills 到底是什么如果你最近在 Claude Code 里写了 SKILL.md却发现模型压根不调用它别急着怀疑人生。我试过把技能目录建好、YAML 也写了结果提问「帮我提取这份 PDF 的表格」Claude 还是老老实实自己读文件完全无视我精心准备的技能。问题不在模型笨而在于没搞懂 Claude Agent Skills 的触发逻辑。Claude Agent Skills社区常简称 Skills是 Claude Code 里的模块化功能组件本质是一套预定义的工具调用规范。你可以把它理解成给 AI 助手准备的「岗位说明书」当用户请求命中某个技能的描述范围时Claude 会自动加载这个技能按里面写好的步骤和工具权限去执行任务。它和斜杠命令最大的区别在于触发方式——斜杠命令要你手动敲/xxx而 Skills 是模型自己判断「这活儿该用哪个技能」。从架构上看一个 Skill 等于三件事的标准化封装触发条件description 里的语义锚点、执行逻辑Instructions 里的步骤、返回结果脚本或模板产出的内容。它适合谁适合已经在用 Claude Code、想让重复工作流固化成工程工件的前后端开发者、数据工程师、以及需要团队共享专业知识的协作团队。你不需要会写复杂插件只要会写 Markdown 和一点 YAML就能把「每次都要重复交代的提示词」变成可发现、可复用、可版本管理的技能模块。这一篇我会带你走完整条链路SKILL.md 的目录结构与字段写法、通过 TaoToken 统一 Key 和 API 通道接入的可复制配置、一次真实的技能触发验证以及几个高频报错的排查。目标很明确——让你今天就能跑通 Skills 工作流而不是停留在概念层面。2. 前置准备用 TaoToken 统一 Key 打通 Claude Code 接入在写 SKILL.md 之前得先让 Claude Code 能正常跑起来。很多人的痛点在于多个模型、多个项目、多个工具各配一套 Key管理起来一团乱。我的做法是用 TaoToken 做统一入口一个 Key 走通 Claude Code 的 API 通道省得在环境变量里塞一堆东西。TaoToken 在这里扮演的是统一 API 网关的角色你拿到的 Key 可以对接 Claude 系列模型Claude Code 通过配置 Base URL 指向它即可。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 生成后先复制保存后面配置要用。这里有个关键点Claude Code 读取的是环境变量或配置文件里的 Base URL 和 Key。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 Base URL 使用。如果你用的是 Claude Code 的 settings 配置方式可以写进~/.claude/settings.json如果走环境变量就设ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。我建议先确认版本。Skills 的发现与工具管控能力跟 Claude Code 版本强相关团队环境最好统一到 1.0 以上避免有人能触发、有人触发不了。查看版本直接跑claude --version如果版本过低先升级再继续。升级完顺手确认一下 API 通道是否通这一步别跳过否则后面技能不触发你会误以为是 SKILL.md 写错了。验证命令很简单用 curl 打一次模型对话接口curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_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: ping}] }返回里能看到content字段有文本输出就说明 Key 和通道都正常。这一步通了我们再进 SKILL.md 的编写。顺便说一句如果你打算长期跑编码和 Agent 任务可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按需选择即可这里不展开。3. 可复制配置SKILL.md 目录结构与字段示例现在进入正题。Claude Agent Skills 的载体是目录核心文件是 SKILL.md。技能分三类存放位置个人技能放~/.claude/skills/项目技能放项目内的.claude/skills/插件技能随插件安装自动可用。团队协作我强烈建议用项目技能因为它能进 git成员拉取后自动生效。先建目录mkdir -p .claude/skills/pdf-processing/scripts mkdir -p .claude/skills/pdf-processing/templates一个完整的技能目录长这样pdf-processing/ ├── SKILL.md (必需) ├── REFERENCE.md (可选详细文档) ├── FORMS.md (可选表单说明) ├── scripts/ │ └── fill_form.py (可选可执行脚本) └── templates/ └── template.txt (可选模板)SKILL.md 由 YAML frontmatter 加 Markdown 正文组成。frontmatter 里两个字段是硬要求name只能用小写字母、数字、连字符长度不超过 64 字符description描述技能做什么以及何时使用不超过 1024 字符。description 是技能发现的关键必须同时包含「能力」和「触发场景」否则模型匹配不上。下面是一个可直接复制的 SKILL.md 示例注意 frontmatter 的开闭---和缩进--- name: pdf-processing description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages. allowed-tools: Read, Grep, Glob, Bash --- # PDF Processing ## Instructions 1. 使用 Read 工具读取目标 PDF 路径 2. 调用 scripts/fill_form.py 处理表单填写 3. 用 pdfplumber 提取文本与表格 4. 返回结构化结果 ## Examples 用户说「提取这份 PDF 的表格」时触发本技能。 For form filling, see [FORMS.md](FORMS.md). For detailed API reference, see [REFERENCE.md](REFERENCE.md). ## Requirements bash pip install pypdf pdfplumber这里有几个细节值得展开。allowed-tools 是限制技能激活时可用工具的关键字段只在 Claude Code 支持。上面我给了 Read、Grep、Glob、Bash意味着技能激活时 Claude 只能用这几个工具不用再逐次请求权限。对只读类技能建议只给 Read、Grep、Glob把改动风险降到最低。如果不写 allowed-tools就遵循默认权限模型。 辅助文件的作用是渐进披露长文档拆到 REFERENCE.md可执行步骤放 scripts/可复用内容放 templates/。Claude 只在需要时才加载这些文件不会一次性把上下文塞满。引用方式就是在 SKILL.md 里写相对链接比如 [REFERENCE.md](REFERENCE.md)。 如果你用 Claude Code 的 settings 方式管理配置~/.claude/settings.json 里可以这样写把 Base URL 和 Key 固定下来 json { env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }注意 Base URL 就是https://taotoken.net/api不要加多余路径。Key 从控制台拿模型 ID 按你实际使用的 Claude 模型填。这三件套——Base URL、Key、Model ID——在 Claude Code、Cline MCP、Codex 的 auth.json 里都是核心配置项缺一不可。写完后重启 Claude Code 让配置生效。4. 验证请求一次技能触发与返回结果配置写完最激动人心的时刻是看技能到底会不会被触发。测试方法很直接用与 description 匹配的问题去问 Claude不要显式点名技能。比如我的 pdf-processing 技能描述里提到了 PDF、forms、document extraction那我就问Can you help me extract text from this PDF?如果技能被正确加载Claude 会按 SKILL.md 里的 Instructions 走先 Read 文件再调用脚本最后返回结构化结果。你可以在对话里看到它引用了技能名或者直接执行了脚本。这一步不需要你敲任何斜杠命令全靠模型自己判断。想确认技能是否被系统发现可以直接问 ClaudeWhat Skills are available?或者List all available Skills它会把个人、项目、插件三个来源的技能列出来。如果列表里没有你的技能说明路径或 YAML 有问题往下看排查章节。再进一步用调试模式跑一次能看到技能加载的详细日志claude --debug在 debug 输出里搜索你的技能名能看到它是否被扫描到、description 是否被解析、触发时加载了哪些工具。这一步对定位「技能存在但不触发」特别有用。验证成功的标志有三个一是技能出现在可用列表里二是提问后 Claude 明确使用了技能而非自己硬做三是返回结果符合 Instructions 里定义的格式。我实测下来最容易出问题的是 description 写得太泛比如只写「Helps with documents」模型根本不知道什么时候该用。改成「Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.」之后触发率明显上来了。如果你还想单独验证模型通道是否正常可以用模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息确认 Key 和模型都通。这一步和技能验证是两回事别混在一起排查。5. 常见报错排查401、local proxy failed 与技能不触发跑 Skills 工作流时报错基本集中在两类接入层和技能层。我按真实遇到的顺序列一下。401 Unauthorized。这个最常见通常是 Key 没配对或环境变量没生效。先确认ANTHROPIC_API_KEY是不是从 TaoToken 控制台拿的再确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api。如果你在 settings.json 里配了但 shell 里又有旧的环境变量可能被覆盖。用echo $ANTHROPIC_API_KEY和echo $ANTHROPIC_BASE_URL检查一下实际值。改完记得重启 Claude Code。local proxy failed。这个报错一般出现在网络层说明请求没到达网关。检查你的 Base URL 有没有多写斜杠或路径比如写成https://taotoken.net/api/v1就可能出问题正确写法就是https://taotoken.net/api。另外确认本机没有其他进程占用端口或拦截请求。reading choices 相关报错。这类通常和返回体解析有关多半是模型 ID 写错或请求格式不对。确认model字段用的是有效模型名anthropic-version头带上2023-06-01。如果你在 Codex 的 auth.json 里配置注意 JSON 格式别写错字段名要和官方一致。OAuth 相关报错。如果你之前用 OAuth 方式登录过配置里可能残留旧凭证和 API Key 冲突。清掉旧的认证缓存统一走 Key 方式。技能不触发。这是技能层最典型的问题排查顺序是先看 description 是否具体模糊描述改成「能力触发场景关键词」再验证文件路径个人技能是~/.claude/skills/skill-name/SKILL.md项目技能是.claude/skills/skill-name/SKILL.md然后检查 YAML 语法开闭---是否成对、有没有用制表符代替空格、特殊字符有没有加引号。用这条命令快速看 frontmattercat .claude/skills/pdf-processing/SKILL.md | head -n 15脚本报错。如果技能触发了但脚本执行失败检查依赖是否安装、脚本是否有执行权限chmod x .claude/skills/pdf-processing/scripts/*.py路径统一用正斜杠别用反斜杠。多技能冲突时通过更具体的 description 区分触发领域避免两个技能抢同一个请求。排查完这些基本能覆盖 90% 的坑。剩下的就是 description 的语义打磨这个只能靠实际提问去回归测试。6. 把 Skills 用起来从单文件到团队共享跑通单个技能后下一步是让它真正产生价值。我的建议是从小处着手先写一个 commit-helper 技能只做一件事——根据git diff --staged生成规范的提交信息。这种单文件技能最容易验证也最快见效。--- name: generating-commit-messages description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes. --- # Generating Commit Messages ## Instructions 1. Run git diff --staged to see changes 2. Suggest a commit message with: - Summary under 50 characters - Detailed description - Affected components ## Best practices - Use present tense - Explain what and why, not how团队共享走项目技能最顺把.claude/skills/提交到 git成员拉取后自动可用。命令就三步git add .claude/skills/ git commit -m Add team Skill for PDF processing git push成员那边git pull之后重启 Claude Code技能就出现在列表里了。如果技能规模大、要跨团队分发再考虑打包成插件走插件市场。更新技能直接编辑 SKILL.md重启生效。重要变更建议在文件里维护版本历史方便回滚。移除技能就删目录再提交rm -rf .claude/skills/my-skill git commit -m Remove unused Skill最后给一个实用技巧description 的写法决定了技能的召回率把它当成「给模型看的搜索关键词」来写把用户可能说的各种说法都覆盖进去。技能不是写完就完事得拿真实提问反复测边界场景近似词、复合意图尤其要试。跑通之后你会发现那些以前每次都要重复交代的提示词现在一句话就能触发整套流程这才是 Skills 工程化的意义。需要查接入细节时接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 按需取用即可。