1. 先搞清楚 Agent Skills 到底解决什么问题Agent Skills 这个词最近在 Claude Code 和 OpenCode 的圈子里被反复提起但很多人第一次听到会以为是某种插件市场或者工具调用协议。其实它没那么玄乎Agent Skills 就是一套用 Markdown 写的“岗位说明书”让 AI 在特定任务里按你定义的规范干活。核心载体是一个叫 SKILL.md 的文件放在约定的目录下AI 加载后就会遵循里面的规则、风格和流程。它和 Tools 的区别值得先掰清楚。Tools 是 AI 的“手”比如联网搜索、读写文件、执行 Python这些是硬能力决定了 AI 能不能做某件事。Skills 是 AI 的“脑”决定 AI 做这件事时懂不懂行、符不符合你的审美和规范。举个例子你让 AI 写一个登录页Tools 让它能生成 HTML 文件但 Skills 才会告诉它“背景别用纯白、卡片要毛玻璃、按钮要有 hover 缩放”。没有 Skills你每次都得把这一长串要求重新粘贴一遍有了 Skills这些经验就固化成一个文件随项目走。适合谁用三类人最该上手。第一类是经常重复写同类提示词的人比如新媒体运营每次都要交代“写小红书要口语化、多用 emoji、标题带痛点”第二类是技术博主或老师想把复杂概念做成可复用的动画或图解第三类是前端和独立开发者希望 AI 产出的代码直接符合自己的设计系统而不是每次手动改配色和间距。这三类场景恰好对应我下面要拆的三个小案例。我试过把一套 UI 规范写进 SKILL.md 之后再让 Claude Code 生成页面它自动就带上了毛玻璃和微交互省掉了大量来回修改的时间。这篇文章就按“先跑通一个最小技能再逐步加复杂度”的思路带你把 SKILL.md 从零写到能在 Claude Code 和 OpenCode 里被 Prompt 触发最后用 TaoToken 的统一 Key 完成一次真实调用验证。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写技能之前得先把模型通道打通否则 SKILL.md 写得再好也没法验证。这里用 TaoToken 做统一入口好处是一个 Key 能覆盖多种模型Claude Code、OpenCode、Cline 这些客户端都指向同一个 Base URL切换模型时不用改一堆配置。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来形如sk-xxxxxxxx。这个 Key 就是后面所有客户端要填的凭证。注意别把它提交到 Git 仓库建议放在环境变量里比如export TAOTOKEN_API_KEYsk-xxxx。Base URL 统一用https://taotoken.net/api不要带任何多余路径。Model ID 按你实际要用的填比如claude-sonnet-4-5、gpt-4o这类具体以控制台模型列表为准。控制台地址是 https://taotoken.net/console 里面能看到可用模型和额度。如果你用的是 Claude Code它的配置走环境变量或 settings 文件。最直接的方式是在 shell 里设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoTokenKey export ANTHROPIC_MODELclaude-sonnet-4-5设置完执行claude启动它会读取这些变量。如果你更习惯用配置文件可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }OpenCode 的配置稍有不同它用opencode.json。在项目根目录或全局配置目录创建这个文件{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey }, models: { claude-sonnet-4-5: {} } } } }这里三件套要记牢Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 是claude-sonnet-4-5。三者缺一不可后面排障也主要围绕这三个点查。配好之后先别急着写技能跑一个最小请求确认通道是通的。用 curl 测一下curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字通了}] }如果返回里有choices字段和正常内容说明 Key 和通道都没问题。这一步很关键因为后面技能加载失败时你要能区分是通道问题还是 SKILL.md 格式问题。通道验证通过后再进入技能目录的搭建。3. 案例一写第一个 SKILL.md 并让 Claude Code 加载第一个案例目标最小写一个能生成小红书文案的技能跑通“目录结构 SKILL.md Prompt 触发”这条链路。目录结构按 Anthropic 和 OpenCode 的通用规范来在项目根目录建.claude/skills/每个技能一个子文件夹文件夹名就是技能名。项目根/ └── .claude/ └── skills/ └── xiaohongshu-creator/ └── SKILL.mdSKILL.md 的开头必须是 YAML Frontmatter这是 AI 识别技能的“身份证”。没有它AI 根本不知道这是个技能。格式如下--- name: xiaohongshu-creator description: 生成符合小红书风格的口语化种草文案标题带痛点与 emoji正文短句分段 license: MIT compatibility: opencode metadata: version: 1.0.0 --- ## What I do 我是一个生活方式类 KOC把平淡的产品信息转成有情绪、有分享欲的笔记。拒绝书面语和“首先其次总之”。 ## When to use me 当用户说“写个小红书”“帮我种草”“推广某个产品”时触发。 ## Content Guidelines ### 语气 - 禁止首先、其次、综上所述、正式开场白。 - 必须短句、口语化可用“家人们”“绝绝子”“真的会谢”。 - 风格热情、真诚、略带夸张。 ### 标题 - 至少两个 emoji。 - 结构情绪或痛点 解决方案 感叹。 - 示例3天瘦5斤这个食谱真的神了 ### 排版 - 每段结尾带一个 emoji。 - 多用换行不要大段文字。 - 结尾带标签如 #生活碎片 #好物分享注意name字段必须是小写字母、数字和单连字符正则大致是^[a-z0-9](-[a-z0-9])*$。写成Xiaohongshu_Creator或者带空格AI 可能识别不了。description控制在 1024 字符以内写清楚“干什么”和“什么时候用”。写完后在 Claude Code 里启动会话直接输入“帮我写个小红书推广一款保温杯”。如果技能被正确加载输出会明显带口语化短句和 emoji而不是那种“首先这款保温杯具有以下优点”的 AI 腔。如果没触发先检查目录层级是不是.claude/skills/技能名/SKILL.md再检查 Frontmatter 有没有写错。OpenCode 用户还要在.claude/下加一个opencode.json来放行技能权限{ $schema: https://opencode.ai/config.json, permission: { skill: { *: allow, pr-review: allow, internal-*: deny, experimental-*: ask } } }这个配置的意思是默认允许所有技能内部和实验性技能分别拒绝和询问。跑通这个最小案例后你已经掌握了 SKILL.md 的核心结构后面两个案例只是在这个骨架上加复杂度。4. 案例二SVG 动画技能与 Prompt 触发链路第二个案例做一个科普向的 SVG 动画技能用来验证“技能加载后Prompt 触发链路是否稳定”。这个技能的价值在于你只要说“画一个 TCP 三次握手的动画”AI 就输出一段可直接保存为.svg的代码拖进浏览器就能看到循环动画。目录结构一样新建.claude/skills/svg-animation-expert/SKILL.md--- name: svg-animation-expert description: 生成用于科普的循环 SVG 动画使用 CSS keyframes 可视化抽象概念 license: MIT compatibility: opencode metadata: output: svg-code style: flat-design --- ## What I do 我生成独立的 SVG 文件用 CSS keyframes 让元素动起来把抽象概念变成可见的流程。 ## Guidelines ### 画布 - 固定 viewBox0 0 800 600。 - 背景矩形 fill#f8f9fa。 ### 颜色 - 主色 #3b82f6错误色 #ef4444。 - 使用扁平化配色避免渐变堆叠。 ### 动画逻辑 - 所有动画 animation-iteration-count: infinite。 - 缓动用 ease-in-out机器类运动才用 linear。 - 用 animation-delay 做分步第一步 0s第二步 1s。 ### 输出示例 svg svg viewBox0 0 800 600 xmlnshttp://www.w3.org/2000/svg style keyframes move { 0% { cx: 100; opacity: 0; } 50% { opacity: 1; } 100% { cx: 700; opacity: 0; } } .packet { animation: move 2s infinite ease-in-out; fill: #3b82f6; } /style rect width800 height600 fill#f8f9fa/ circle r20 cy300 classpacket/ /svg这里有个细节SKILL.md 里嵌套代码块时外层用四个反引号内层用三个否则 Markdown 解析会乱。写完后在 Claude Code 里输入“帮我画一个数据包从 A 传到 B 的动画”观察输出是不是一段完整 SVG。如果 AI 只给了文字描述没给代码说明 metadata.output: svg-code 没被识别检查 Frontmatter 缩进。 Prompt 触发链路的关键在于 description 和 When to use me 的措辞。description 里要包含触发词比如“SVG”“动画”“科普”这样 AI 在匹配用户意图时更容易命中。实测下来description 写得越具体误触发和漏触发都越少。如果同时装了多个技能AI 会根据 description 的语义相似度选择所以别把两个技能的 description 写得太像。 这个案例还顺带验证了一件事技能文件是纯文本可以提交到 Git可以分享给同事可以随项目迭代。你今天写了一个 SVG 技能明天发现动画节奏不对改一下 SKILL.md 里的 animation-delay 就行不用重新教 AI。 ## 5. 案例三现代 UI 技能与常见报错排查 第三个案例做前端 UI 技能同时把这一节当成排障手册因为接入过程中最容易在这里遇到报错。先建 .claude/skills/modern-ui-expert/SKILL.md markdown --- name: modern-ui-expert description: 生成生产级前端代码强制使用 Tailwind CSS 与现代设计原则拒绝土味页面 license: MIT compatibility: opencode metadata: stack: nextjs-tailwind role: senior-frontend-architect --- ## What I do 我拒绝生成丑代码强制“留白即奢华”和“毛玻璃”设计原则。 ## Design System ### 颜色与层次 - 背景不用纯白用 bg-slate-50 或 bg-zinc-950。 - 毛玻璃bg-white/70 backdrop-blur-md border border-white/20。 - 阴影卡片 shadow-sm弹窗 shadow-xl。 ### 间距 - 区块最小 py-20。 - 网格间距至少 gap-6。 ### 组件 - 严格用 Tailwind 工具类。 - 图标用 lucide-react。 - 按钮必须有 hover:scale-105 active:scale-95 transition-all。 ## When to use me 用户要求“落地页”“仪表盘”“登录表单”时触发。写完后让 Claude Code 生成一个登录页正常输出应该带毛玻璃卡片和按钮微交互。如果这一步失败对照下面几个真实报错排查。第一个常见报错是401 Unauthorized。这通常是 Key 没填对或没生效。检查ANTHROPIC_API_KEY是不是sk-开头有没有多余空格环境变量有没有在启动 Claude Code 的同一个 shell 里 export。如果是 OpenCode检查opencode.json里apiKey字段。第二个是local proxy failed或连接被拒。这多半是 Base URL 写错了比如多写了/v1或者少了https://。正确值是https://taotoken.net/api不要带尾部斜杠。改完重启客户端。第三个是reading choices相关报错通常出现在返回体解析阶段。这说明请求发出去了但响应格式不对可能是 Model ID 填了一个不存在的模型。去 https://taotoken.net/console 核对模型列表把ANTHROPIC_MODEL改成实际可用的 ID。第四个是 OAuth 相关报错。Claude Code 有时会尝试走 OAuth 登录流程如果你用的是 API Key 模式确保没有残留的登录态。可以删掉~/.claude/下的凭证缓存再试。排查顺序建议先 curl 测通道再查客户端配置三件套Base URL、Key、Model ID最后查 SKILL.md 的 Frontmatter 格式。大部分问题出在前两步技能文件本身很少出错除非 YAML 缩进写乱了。6. 把技能用起来从验证到长期编码三个案例跑完你应该已经有一个能触发的小红书技能、一个 SVG 动画技能、一个 UI 技能。接下来做一次完整验证在 Claude Code 里同时保留这三个技能目录输入“帮我写个小红书推广这个登录页顺便画个数据流动画”观察 AI 是否能按需调用不同技能。如果它把三件事混在一起输出说明 description 区分度不够回去把每个技能的触发词写得更独立。验证模型本身是否正常可以直接用模型对话页面 https://taotoken.net/models 发一条消息确认通道和模型都活着。这一步和技能无关但能帮你快速定位是通道问题还是技能问题。如果你打算把技能用在长期编码或 Agent 工作流里建议走 Coding Plan地址是 https://taotoken.net/coding-plan 。它更适合持续性的编码任务配合 SKILL.md 能把你的团队规范固化下来新人拉下代码就自带一套 AI 行为准则。接入文档在 https://taotoken.net/doc 里面有各客户端的详细配置说明遇到本文没覆盖的客户端可以查这里。API Key 管理在 https://taotoken.net/api-keys 建议给不同项目建不同的 Key方便追踪用量。最后说一个实用技巧SKILL.md 不要一次写太长。先写最小可触发版本跑通后再往里加规则。我见过有人一上来写两千字规范结果 AI 反而抓不住重点。技能是迭代出来的不是一次写成的。今天先为你最常做的那件事写一个 SKILL.md明天根据实际输出改两行一周后它就是你最顺手的数字资产。