1. 为什么你的 AI Agent 总像个“聪明但不懂事”的实习生你大概率遇到过这种场面让 Claude 帮你按公司规范生成一份接口文档它洋洋洒洒写了一大篇字段命名却全是它自己那套让它调用内部工单系统查个状态它反问你“请问这个系统的 API 地址是什么”。模型本身不笨它只是不知道你们团队的“行话”和“规矩”。Agent Skills 要解决的就是这件事。它是 Anthropic 推动的一套开放格式规范核心载体是一个叫SKILL.md的文件。你可以把它理解成给 AI 写的一份“岗位说明书”什么场景下该触发、按什么步骤做、用哪些脚本、注意哪些坑全部写清楚。Agent 启动时只读每个 Skill 的名字和描述约 100 token任务匹配上了才加载完整指令需要脚本了才去读脚本。这意味着你挂几十个 Skill上下文也不会爆炸。它适合三类人一是想把团队经验沉淀下来的工程师写一次、兼容的 Agent 都能用二是做 Agent 产品的开发者用户开箱即得扩展能力三是企业团队把内部流程变成可版本控制、可复用的技能包。Cursor、Claude Code、VS Code、GitHub Copilot 等主流工具都已跟进支持。下面我从零开始带你写一个能真正跑起来的 Skill并接上统一的 API 通道验证它被正确加载。2. 前置准备用 TaoToken 统一 Key 打通 Agent 调用通道在写 SKILL.md 之前先把“调用通道”理顺。不管你是用 Claude Code、Cursor 还是自己写的 Agent 脚本最终都要落到一个 API Key 和 Base URL 上。我习惯用 TaoToken 做统一入口原因是它把 Anthropic、OpenAI 等多家模型的调用收敛成一套 Key切换模型时不用改代码结构只改模型名即可。你需要先拿到 Key。打开控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建一个。拿到 Key 后接入地址统一用https://taotoken.net/api。这个地址同时兼容 Anthropic 风格和 OpenAI 风格的调用路径具体用哪个取决于你的 Agent 工具。比如 Claude Code 走 Anthropic 协议OpenAI 兼容的脚本走/v1/chat/completions。配置项值说明API Key控制台创建形如sk-...只显示一次Base URLhttps://taotoken.net/api不带 UTM代码里直接用Anthropic 路径/v1/messagesClaude Code / Anthropic SDKOpenAI 路径/v1/chat/completions兼容脚本 / 自研 Agent模型名按需填写如claude-sonnet-4-20250514如果你用的是 Claude Code可以直接在环境变量里配置省去改配置文件export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key配好之后先别急着写 Skill用一条最小请求确认通道是通的。这一步很关键很多人后面 Skill 加载失败其实是 Key 或 Base URL 就没配对。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: 回复两个字通了}] }返回里能看到content字段有正常文本说明通道没问题。这一步过了再进入 Skill 的编写。3. 可复制配置从零写一个 SKILL.md 骨架Skill 的本质就是一个文件夹里面必须有一个SKILL.md其余脚本、参考文档、模板都是可选的。目录结构建议这样组织team-api-doc/ ├── SKILL.md # 核心元数据 指令 ├── scripts/ │ └── gen_doc.py # 可选生成文档的脚本 ├── references/ │ └── field-rules.md # 可选字段命名规范 └── assets/ └── template.md # 可选文档模板SKILL.md由两部分组成顶部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 里name和description是必填的其余可选。命名只能用小写字母、数字、连字符不能大写、不能以连字符开头、不能有连续连字符。下面是一个可以直接复制使用的骨架场景是“按团队规范生成接口文档”--- name: team-api-doc description: 按团队字段命名规范生成 REST 接口文档包含请求参数、响应结构、错误码。当用户要求生成接口文档、API 文档或提到字段命名规范时使用。 license: MIT compatibility: 需要 python3 环境依赖 pyyaml metadata: author: platform-team version: 1.0.0 --- # 团队接口文档生成 ## 何时使用 当用户要求为某个接口生成文档或提到“按规范写文档”“字段命名”时触发。 ## 执行步骤 1. 读取 references/field-rules.md确认字段命名规则。 2. 按 assets/template.md 的结构组织输出。 3. 若用户提供了代码用 scripts/gen_doc.py 解析后填充模板。 4. 输出前自查字段是否全小写下划线、错误码是否覆盖 4xx/5xx。 ## 字段命名规则摘要 - 请求参数一律 snake_case禁止驼峰。 - 布尔字段以 is_ 或 has_ 开头。 - 时间字段统一以 _at 结尾值为 ISO8601 字符串。 ## 错误处理 - 若用户未提供接口路径先追问再生成。 - 若脚本执行失败回退到手动按模板填写并提示失败原因。这里有几个我踩过的坑值得说。第一description千万别写成“帮助处理文档”这种模糊描述Agent 匹配任务全靠它要写清楚做什么 什么时候用把关键词塞进去。第二正文控制在 500 行以内详细规则放references/避免每次激活都吃掉大量 token。第三脚本要自包含依赖在compatibility里写明白错误提示要友好否则 Agent 拿到报错也不知道怎么办。写完之后用官方提供的skills-ref工具校验一下格式能提前发现命名或 frontmatter 的问题pip install skills-ref skills-ref validate ./team-api-doc校验通过会输出类似OK: team-api-doc的结果。如果报invalid name多半是命名里有大写或连续连字符。4. 验证请求确认 Skill 被正确加载与调用Skill 写好了怎么确认 Agent 真的“学会”了分两步先确认它被发现再确认它被激活。发现阶段Agent 启动时会扫描 Skill 目录只读 frontmatter。你可以用skills-ref生成注入 System Prompt 的 XML直观看到 Agent 眼里的 Skill 长什么样skills-ref to-prompt ./team-api-doc输出大致是这样available_skills skill nameteam-api-doc/name description按团队字段命名规范生成 REST 接口文档.../description location/path/to/team-api-doc/SKILL.md/location /skill /available_skills这段 XML 就是你要塞进 System Prompt 的内容。以 Claude 为例把它拼进系统提示后发一条会触发该 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: 1024, system: available_skillsskillnameteam-api-doc/namedescription按团队字段命名规范生成 REST 接口文档/descriptionlocation/path/to/team-api-doc/SKILL.md/location/skill/available_skills, messages: [{role: user, content: 帮我给 /user/create 接口生成文档按团队规范来}] }判断是否激活成功看两个信号一是返回内容里字段命名是不是 snake_case、布尔字段有没有is_前缀二是如果你在 Skill 里要求了“先读取 references”Agent 的回复里通常会体现这个动作比如提到“根据字段规则”。如果它还是自由发挥说明没匹配上回去检查description的关键词是否覆盖了用户的说法。想更省事地验证模型行为可以直接在模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite里手动贴入 System Prompt 和用户问题快速对比加 Skill 前后的输出差异。这个方式适合调description措辞改一版测一版比反复跑脚本快。5. 本篇常见错排查Skill 不生效的六个原因报错一invalid skill name。命名违规。检查是否含大写、是否以连字符开头、是否有连续连字符。PDF-Processing、-pdf、pdf--processing都是错的改成pdf-processing。报错二Skill 被扫描到但从不激活。九成是description太笼统。Agent 靠描述匹配任务写“帮助处理 PDF”不如写“提取 PDF 文本和表格、填写表单、合并文档当用户提到 PDF、表单、文档提取时使用”。把用户可能说的词都放进去。报错三激活了但输出不符合规范。检查正文里的步骤是否可执行。如果只写“按规范生成”却没把规范写进references/或正文Agent 无从遵守。规则要具体到“字段全小写下划线”这种程度。报错四脚本执行失败。多半是依赖没装或路径写错。脚本里用相对路径时注意 Agent 的工作目录可能不是 Skill 目录。建议脚本开头打印当前目录或改用绝对路径拼接。依赖在compatibility里声明清楚。报错五上下文突然变长、响应变慢。说明你把太多内容塞进了SKILL.md正文每次激活都全量加载。把详细规则、大段示例挪到references/正文只留触发条件和核心步骤。报错六API 返回 401 或 404。这不是 Skill 的问题是通道没配对。401 检查 Key 是否复制完整、是否带了多余空格404 检查 Base URL 和路径Anthropic 协议用/v1/messages别错写成/v1/chat/completions。Key 管理在 API Keys 页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite可以随时重建。排查顺序建议固定下来先skills-ref validate过格式再to-prompt看注入内容再发触发请求看激活最后才怀疑模型。大部分问题在前两步就能定位。6. 把团队经验沉淀成可复用技能下一步怎么走Skill 跑通之后真正有价值的是把它变成团队资产。我的做法是每个 Skill 单独一个 Git 仓库或目录metadata里写清作者和版本改动走 PR 评审。这样“怎么做事”就从某个人脑子里变成了可版本控制、可回滚的文件。如果你要长期跑编码类或 Agent 类任务频繁调用模型可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它针对高频编码场景做了额度优化配合 Skill 使用能省不少成本。接入细节和更多协议示例在接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里Anthropic 协议的字段说明写得比较全遇到参数不确定时翻一下比试错快。最后给一个实用技巧先别追求写大而全的 Skill。挑一个你每周都要重复交代给 AI 的流程比如“按规范写 commit message”或“生成周报模板”写成最小 Skill跑通激活流程再逐步往里加脚本和参考文档。一个能稳定触发的小 Skill比十个从不激活的完美 Skill 有用得多。