1. 为什么你的 Skill 总是加载失败从一次真实的踩坑说起你可能已经在 Claude 或者别的 AI 工具里见过 Skill 这个词但一直没动手。原因很简单网上大部分教程一上来就讲概念讲完概念就让你去注册账号最后你连一个能跑起来的文件都没见到。我这次换个思路直接给你一个能复制粘贴就跑通的最小闭环。Skill 是什么用一句话说它就是一个文件夹加一个 Markdown 文件。文件夹是容器Markdown 文件是说明书。AI 工具在启动或者对话时读取这个说明书就知道自己该扮演什么角色、遵守什么规则、参考哪些资料。它解决的核心痛点是你不想每次对话都重复交代背景。比如你是 Java 后端项目用 Java 17遵循阿里巴巴规范支付模块的表结构长这样——这些话你说了八百遍AI 还是记不住。Skill 就是把这堆上下文固化下来一次写好反复加载。适合谁适合所有跟 AI 协作但还没用过 Skill 的人。你不需要会写代码不需要懂 LangChain不需要申请服务器。你只需要会新建文件夹、会写 Markdown。这篇文章的目标很明确让你在 10 分钟内看到自己的 Skill 被正确加载并响应。中间涉及的所有 API 调用我会用 TaoToken 的统一 Key 通道来跑通这样你不用在多个平台之间来回切换。我试过在三个不同的项目里用同一套 Skill 骨架从代码审查到接口文档生成实测下来最稳的路径就是本地建文件夹 → 写 SKILL.md → 配 settings.json → 用统一 Key 发一次请求验证。下面按这个顺序走。2. TaoToken 前置准备拿到统一 Key 和 API 地址在写 SKILL.md 之前你需要先有一个能调用的 API 通道。TaoToken 在这里的角色是统一入口你拿一个 Key就能接入 Claude 等模型不用每个平台单独申请。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加任何参数。具体操作分三步。第一步打开官网注册并登录。第二步进入控制台找到 API Keys 管理页面新建一个 Key。这个 Key 就是你后面所有请求的凭证复制下来存好不要泄露。第三步确认你的账户有可用额度免费额度通常够跑通本文的验证请求。这里有一个容易踩的坑很多人拿到 Key 之后直接去调模型对话接口结果发现 Skill 根本没被加载。原因是 Skill 的加载逻辑不在模型对话接口里而在你的本地配置和请求参数里。TaoToken 提供的是通道Skill 的加载是你自己控制的。所以顺序不能乱先有 Key再写 Skill 文件最后在请求里把 Skill 内容带进去。如果你还没有 Key现在去开一个整个过程不超过两分钟。开完之后回到这里我们继续写文件。3. 可复制配置SKILL.md 骨架 settings.json 片段3.1 建文件夹和 SKILL.md在你的电脑上任意位置新建一个文件夹名字叫 my-first-skill。名字用英文不要带空格和中文。进入这个文件夹新建一个 Markdown 文件文件名必须叫 SKILL.md大小写敏感不能写成 skill.md 或者 Skill.MD。打开 SKILL.md把下面这段内容完整粘贴进去--- name: java-code-reviewer description: 根据团队 Java 编码规范对提交的代码片段进行审查输出问题等级和修改建议。 --- # 角色定义 你是一名资深 Java 后端工程师精通代码审查熟悉阿里巴巴 Java 开发手册对并发、性能、安全有敏感度。 # 审查规则 1. 逐条检查以下规范 - 命名是否符合驼峰规范避免拼音与英文混用 - 并发场景下是否正确使用锁或线程安全集合 - 数据库操作是否考虑事务边界和 SQL 性能 - 异常处理是否避免吞掉原始异常打印必要堆栈 - 集合操作是否考虑判空避免 NPE 2. 对每一个发现的问题给出严重等级高/中/低和修改建议示例。 3. 如果没有发现问题回复“未发现明显问题但建议补充相关单元测试”。 # 项目背景参考 请在分析代码前优先阅读 docs/ 目录下的所有文件作为上下文基础。保存文件。到这里你的第一个 Skill 的骨架就已经完成了。注意 YAML 头部的 name 和 description 不是给你自己看的是给 AI 调度器看的。description 写得越精准AI 越知道什么时候该激活这个 Skill。不要写“帮我干活”这种泛词。3.2 补充资料文件夹在 my-first-skill 文件夹里再新建一个子文件夹叫 docs。把你项目的相关资料放进去比如payment_flow.md支付状态流转说明db_schema.sql核心表结构known_issues.md历史故障复盘记录这些文件不需要特殊格式Markdown、SQL、纯文本都行。SKILL.md 里已经写了“优先阅读 docs/ 目录”AI 在加载时会把这些文件作为上下文一起读进去。3.3 settings.json 配置片段如果你用的是支持 settings.json 的客户端比如某些 Claude 桌面端或 IDE 插件可以在配置里指定 Skill 路径和 API 通道。下面是一个可复制的片段{ api_base: https://taotoken.net/api, api_key: 你的_TaoToken_Key, model: claude-sonnet-4-20250514, skills: [ { name: java-code-reviewer, path: ./my-first-skill/SKILL.md, enabled: true } ] }把 api_key 替换成你在 TaoToken 控制台拿到的真实 Key。model 字段填你账户可用的模型名。skills 数组里 path 指向你刚才建的 SKILL.md 文件。如果你的客户端不支持 skills 字段也没关系后面我会讲怎么在请求里手动带上 Skill 内容。4. 验证请求发一次真实调用看 Skill 是否被加载4.1 用 curl 发一次请求打开终端执行下面这条命令。注意把 YOUR_TAOTOKEN_KEY 替换成你的真实 Keycurl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: YOUR_TAOTOKEN_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 1024, system: 你是一个代码审查助手。以下是你的技能说明\n\n---\nname: java-code-reviewer\ndescription: 根据团队 Java 编码规范审查代码。\n---\n\n# 审查规则\n1. 检查命名规范\n2. 检查并发安全\n3. 检查异常处理\n4. 输出问题等级和修改建议, messages: [ { role: user, content: 请审查这段代码\n\npublic void releaseLock(String key) {\n redisTemplate.delete(key);\n} } ] }这条请求做了两件事第一通过 TaoToken 的 API 地址发送请求第二在 system 字段里把 SKILL.md 的核心内容带了进去。这样即使你的客户端不支持自动加载 SkillAI 也能读到你的规则。4.2 预期结果如果一切正常你会收到类似下面的响应{ id: msg_xxx, type: message, role: assistant, content: [ { type: text, text: 审查结果\n\n1. 严重等级高\n问题释放锁时没有判断锁是否属于当前线程直接 delete 可能导致误删其他线程持有的锁。\n修改建议使用 Lua 脚本或 Redisson 的 RLock 来保证锁的归属判断。\n\n2. 严重等级中\n问题没有处理 redisTemplate.delete 返回的布尔值无法确认释放是否成功。\n修改建议记录返回值并打日志。\n\n3. 严重等级低\n问题方法缺少注释建议补充 Javadoc。 } ] }看到这个输出说明你的 Skill 已经被正确加载并生效了。AI 按照你在 SKILL.md 里定义的规则逐条检查了命名、并发、异常处理并给出了等级和建议。整个过程从建文件夹到看到结果熟练之后不超过 10 分钟。4.3 用模型对话页面快速验证如果你不想敲 curl也可以直接打开 TaoToken 的模型对话页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在对话页面里把 SKILL.md 的内容粘贴到系统提示词或者对话开头然后发一段代码过去。效果和 curl 一样适合快速验证。5. 本篇常见错排查Skill 不生效的六个原因第一个原因文件名写错。必须是 SKILL.md不能是 skill.md、Skill.md、SKILL.MD。大小写和扩展名都要对。我见过有人写成 SKILL.txtAI 根本读不到。第二个原因YAML 头部格式错误。--- 必须是独立的一行name 和 description 的冒号后面要有空格。如果写成 name:java-code-reviewer 没有空格解析会失败。第三个原因API Key 没有替换。curl 命令里的 YOUR_TAOTOKEN_KEY 是占位符你不替换成真实 Key请求会返回 401。去 TaoToken 控制台重新复制一次。第四个原因API 地址写错。必须是 https://taotoken.net/api 后面不要加 /v1 之外的路径也不要加 UTM 参数。加错了会 404。第五个原因system 字段里没有带 Skill 内容。如果你用的是手动请求方式Skill 规则必须放在 system 或者第一条 user 消息里。只配了 settings.json 但客户端不读取等于没配。第六个原因模型名不对。model 字段要填你账户实际可用的模型名。填错了会返回 model not found。去控制台看一下可用模型列表。排查顺序建议先确认文件名和 YAML 格式再确认 Key 和 API 地址最后确认 Skill 内容有没有真正进入请求。大部分问题出在前两步。6. 下一步把你的 Skill 用起来到这里你已经有了一个能跑的 Skill。接下来最值得做的事是把它变成你日常协作的一部分。我的做法是在项目根目录建一个 .skills 文件夹把不同用途的 Skill 分文件夹放进去用 Git 管起来。团队新人拉一份仓库加载技能文件夹直接具备老员工的八成功力。如果你要长期在编码和 Agent 场景里用 Skill建议走 Coding Plan 通道配置更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。如果你只是想先验证模型和 Skill 的配合效果用模型对话页面就够了。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后说一个我踩过的坑不要试图一次把 SKILL.md 写完美。先跑 10 个真实场景把不符合预期的地方记下来回到文件里补规则、加禁止项。改过三四轮之后这个 Skill 才会进入靠谱阶段。你现在就可以打开编辑器把最常跟 AI 抱怨的那句话写进 SKILL.md然后发一次请求看看效果。
1. 为什么你的 Skill 总是加载失败从一次真实的踩坑说起你可能已经在 Claude 或者别的 AI 工具里见过 Skill 这个词但一直没动手。原因很简单网上大部分教程一上来就讲概念讲完概念就让你去注册账号最后你连一个能跑起来的文件都没见到。我这次换个思路直接给你一个能复制粘贴就跑通的最小闭环。Skill 是什么用一句话说它就是一个文件夹加一个 Markdown 文件。文件夹是容器Markdown 文件是说明书。AI 工具在启动或者对话时读取这个说明书就知道自己该扮演什么角色、遵守什么规则、参考哪些资料。它解决的核心痛点是你不想每次对话都重复交代背景。比如你是 Java 后端项目用 Java 17遵循阿里巴巴规范支付模块的表结构长这样——这些话你说了八百遍AI 还是记不住。Skill 就是把这堆上下文固化下来一次写好反复加载。适合谁适合所有跟 AI 协作但还没用过 Skill 的人。你不需要会写代码不需要懂 LangChain不需要申请服务器。你只需要会新建文件夹、会写 Markdown。这篇文章的目标很明确让你在 10 分钟内看到自己的 Skill 被正确加载并响应。中间涉及的所有 API 调用我会用 TaoToken 的统一 Key 通道来跑通这样你不用在多个平台之间来回切换。我试过在三个不同的项目里用同一套 Skill 骨架从代码审查到接口文档生成实测下来最稳的路径就是本地建文件夹 → 写 SKILL.md → 配 settings.json → 用统一 Key 发一次请求验证。下面按这个顺序走。2. TaoToken 前置准备拿到统一 Key 和 API 地址在写 SKILL.md 之前你需要先有一个能调用的 API 通道。TaoToken 在这里的角色是统一入口你拿一个 Key就能接入 Claude 等模型不用每个平台单独申请。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加任何参数。具体操作分三步。第一步打开官网注册并登录。第二步进入控制台找到 API Keys 管理页面新建一个 Key。这个 Key 就是你后面所有请求的凭证复制下来存好不要泄露。第三步确认你的账户有可用额度免费额度通常够跑通本文的验证请求。这里有一个容易踩的坑很多人拿到 Key 之后直接去调模型对话接口结果发现 Skill 根本没被加载。原因是 Skill 的加载逻辑不在模型对话接口里而在你的本地配置和请求参数里。TaoToken 提供的是通道Skill 的加载是你自己控制的。所以顺序不能乱先有 Key再写 Skill 文件最后在请求里把 Skill 内容带进去。如果你还没有 Key现在去开一个整个过程不超过两分钟。开完之后回到这里我们继续写文件。3. 可复制配置SKILL.md 骨架 settings.json 片段3.1 建文件夹和 SKILL.md在你的电脑上任意位置新建一个文件夹名字叫 my-first-skill。名字用英文不要带空格和中文。进入这个文件夹新建一个 Markdown 文件文件名必须叫 SKILL.md大小写敏感不能写成 skill.md 或者 Skill.MD。打开 SKILL.md把下面这段内容完整粘贴进去--- name: java-code-reviewer description: 根据团队 Java 编码规范对提交的代码片段进行审查输出问题等级和修改建议。 --- # 角色定义 你是一名资深 Java 后端工程师精通代码审查熟悉阿里巴巴 Java 开发手册对并发、性能、安全有敏感度。 # 审查规则 1. 逐条检查以下规范 - 命名是否符合驼峰规范避免拼音与英文混用 - 并发场景下是否正确使用锁或线程安全集合 - 数据库操作是否考虑事务边界和 SQL 性能 - 异常处理是否避免吞掉原始异常打印必要堆栈 - 集合操作是否考虑判空避免 NPE 2. 对每一个发现的问题给出严重等级高/中/低和修改建议示例。 3. 如果没有发现问题回复“未发现明显问题但建议补充相关单元测试”。 # 项目背景参考 请在分析代码前优先阅读 docs/ 目录下的所有文件作为上下文基础。保存文件。到这里你的第一个 Skill 的骨架就已经完成了。注意 YAML 头部的 name 和 description 不是给你自己看的是给 AI 调度器看的。description 写得越精准AI 越知道什么时候该激活这个 Skill。不要写“帮我干活”这种泛词。3.2 补充资料文件夹在 my-first-skill 文件夹里再新建一个子文件夹叫 docs。把你项目的相关资料放进去比如payment_flow.md支付状态流转说明db_schema.sql核心表结构known_issues.md历史故障复盘记录这些文件不需要特殊格式Markdown、SQL、纯文本都行。SKILL.md 里已经写了“优先阅读 docs/ 目录”AI 在加载时会把这些文件作为上下文一起读进去。3.3 settings.json 配置片段如果你用的是支持 settings.json 的客户端比如某些 Claude 桌面端或 IDE 插件可以在配置里指定 Skill 路径和 API 通道。下面是一个可复制的片段{ api_base: https://taotoken.net/api, api_key: 你的_TaoToken_Key, model: claude-sonnet-4-20250514, skills: [ { name: java-code-reviewer, path: ./my-first-skill/SKILL.md, enabled: true } ] }把 api_key 替换成你在 TaoToken 控制台拿到的真实 Key。model 字段填你账户可用的模型名。skills 数组里 path 指向你刚才建的 SKILL.md 文件。如果你的客户端不支持 skills 字段也没关系后面我会讲怎么在请求里手动带上 Skill 内容。4. 验证请求发一次真实调用看 Skill 是否被加载4.1 用 curl 发一次请求打开终端执行下面这条命令。注意把 YOUR_TAOTOKEN_KEY 替换成你的真实 Keycurl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: YOUR_TAOTOKEN_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 1024, system: 你是一个代码审查助手。以下是你的技能说明\n\n---\nname: java-code-reviewer\ndescription: 根据团队 Java 编码规范审查代码。\n---\n\n# 审查规则\n1. 检查命名规范\n2. 检查并发安全\n3. 检查异常处理\n4. 输出问题等级和修改建议, messages: [ { role: user, content: 请审查这段代码\n\npublic void releaseLock(String key) {\n redisTemplate.delete(key);\n} } ] }这条请求做了两件事第一通过 TaoToken 的 API 地址发送请求第二在 system 字段里把 SKILL.md 的核心内容带了进去。这样即使你的客户端不支持自动加载 SkillAI 也能读到你的规则。4.2 预期结果如果一切正常你会收到类似下面的响应{ id: msg_xxx, type: message, role: assistant, content: [ { type: text, text: 审查结果\n\n1. 严重等级高\n问题释放锁时没有判断锁是否属于当前线程直接 delete 可能导致误删其他线程持有的锁。\n修改建议使用 Lua 脚本或 Redisson 的 RLock 来保证锁的归属判断。\n\n2. 严重等级中\n问题没有处理 redisTemplate.delete 返回的布尔值无法确认释放是否成功。\n修改建议记录返回值并打日志。\n\n3. 严重等级低\n问题方法缺少注释建议补充 Javadoc。 } ] }看到这个输出说明你的 Skill 已经被正确加载并生效了。AI 按照你在 SKILL.md 里定义的规则逐条检查了命名、并发、异常处理并给出了等级和建议。整个过程从建文件夹到看到结果熟练之后不超过 10 分钟。4.3 用模型对话页面快速验证如果你不想敲 curl也可以直接打开 TaoToken 的模型对话页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在对话页面里把 SKILL.md 的内容粘贴到系统提示词或者对话开头然后发一段代码过去。效果和 curl 一样适合快速验证。5. 本篇常见错排查Skill 不生效的六个原因第一个原因文件名写错。必须是 SKILL.md不能是 skill.md、Skill.md、SKILL.MD。大小写和扩展名都要对。我见过有人写成 SKILL.txtAI 根本读不到。第二个原因YAML 头部格式错误。--- 必须是独立的一行name 和 description 的冒号后面要有空格。如果写成 name:java-code-reviewer 没有空格解析会失败。第三个原因API Key 没有替换。curl 命令里的 YOUR_TAOTOKEN_KEY 是占位符你不替换成真实 Key请求会返回 401。去 TaoToken 控制台重新复制一次。第四个原因API 地址写错。必须是 https://taotoken.net/api 后面不要加 /v1 之外的路径也不要加 UTM 参数。加错了会 404。第五个原因system 字段里没有带 Skill 内容。如果你用的是手动请求方式Skill 规则必须放在 system 或者第一条 user 消息里。只配了 settings.json 但客户端不读取等于没配。第六个原因模型名不对。model 字段要填你账户实际可用的模型名。填错了会返回 model not found。去控制台看一下可用模型列表。排查顺序建议先确认文件名和 YAML 格式再确认 Key 和 API 地址最后确认 Skill 内容有没有真正进入请求。大部分问题出在前两步。6. 下一步把你的 Skill 用起来到这里你已经有了一个能跑的 Skill。接下来最值得做的事是把它变成你日常协作的一部分。我的做法是在项目根目录建一个 .skills 文件夹把不同用途的 Skill 分文件夹放进去用 Git 管起来。团队新人拉一份仓库加载技能文件夹直接具备老员工的八成功力。如果你要长期在编码和 Agent 场景里用 Skill建议走 Coding Plan 通道配置更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。如果你只是想先验证模型和 Skill 的配合效果用模型对话页面就够了。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后说一个我踩过的坑不要试图一次把 SKILL.md 写完美。先跑 10 个真实场景把不符合预期的地方记下来回到文件里补规则、加禁止项。改过三四轮之后这个 Skill 才会进入靠谱阶段。你现在就可以打开编辑器把最常跟 AI 抱怨的那句话写进 SKILL.md然后发一次请求看看效果。
