1. 为什么你的第一个 Skill 总是加载失败很多刚接触大模型 Skill 开发的朋友第一次动手时都会遇到同一个场景照着文档写了一个SKILL.md放进本地 AI 工具的 skills 目录重启之后问模型“帮我旋转这个 PDF”结果模型一脸茫然要么答非所问要么干脆说“我没有这个能力”。你反复检查文件路径、重启工具、甚至怀疑是不是工具版本太旧但问题往往不在环境而在那份SKILL.md本身。Skill 的本质不是一份写给人看的说明文档而是一份写给模型执行的操作指令。它由两部分组成上半部分的 frontmatter 负责“什么时候触发”下半部分的 body 负责“触发之后怎么做”。新手最容易犯的错就是把背景介绍、设计原则、版本记录这些人类文档习惯塞进去导致模型在扫描阶段就抓不到关键触发词或者加载后拿到一堆模糊形容词却不知道具体该执行什么动作。这篇指南面向刚接触 Skill 开发的新手聚焦SKILL.md与 frontmatter 的骨架写法带你从零在本地 AI 工具里跑通第一个可运行的 Skill。我会给出可以直接复制的模板、统一 Key 与 API 通道的配置片段以及加载成功和调用失败的验证动作。整个过程不需要你懂复杂的框架只要会建文件夹、会改 JSON 就能跟上。2. 前置准备用 TaoToken 统一 Key 与 API 通道在写 Skill 之前先把模型通道打通。本地 AI 工具比如各类支持 Skill 的编码助手、对话客户端通常需要配置一个模型服务地址和 API Key。如果你同时用多个模型每个都单独配 Key、单独改地址管理起来会很乱。我习惯用 TaoToken 做统一入口一个 Key 走通对话和编码两类场景配置文件里只维护一份。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。注意 API 地址后面不加任何查询参数保持干净避免某些客户端解析异常。你需要先拿到一个 API Key。进入控制台创建即可地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建后复制那串以sk-开头的字符串后面配置要用。如果你打算长期做编码类 Skill、或者要接 Agent 工作流可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。只是想先验证模型能不能正常对话用模型对话页面就行https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置字段有疑问时对照查一下。如果你用的是 Claude Code 这类工具对应的 Anthropic 兼容配置参考 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. 可复制配置settings.json 与 SKILL.md 骨架3.1 settings.json 配置片段本地 AI 工具一般会有一个settings.json或类似的配置文件用来指定模型服务地址和 Key。下面这段可以直接改改就用把sk-你的Key替换成上一步拿到的真实 Key{ modelProvider: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, defaultModel: claude-sonnet-4-20250514 }, skills: { enabled: true, paths: [ ./skills ] } }这里baseUrl填的是 TaoToken 的 API 根地址不要在后面加/v1之类的后缀具体路径由客户端自己拼接。skills.paths指向你存放 Skill 文件夹的目录我习惯放在项目根目录下的skills/里方便版本管理。改完保存重启工具。如果工具支持热加载也可以不重启但第一次配置建议重启一次确保读取到新路径。3.2 SKILL.md 完整模板接下来是核心。在skills/目录下新建一个文件夹比如pdf-rotator然后在里面创建SKILL.md。文件夹名和 frontmatter 里的name必须完全一致这是很多工具校验时的硬性要求。--- name: pdf-rotator description: - 旋转 PDF 文件的页面方向。当用户说“旋转这个 PDF”“把这个 PDF 转 90 度” “调整 PDF 页面方向”或提供 PDF 文件路径并要求改变页面朝向时使用。 --- ## 使用方式 1. 从用户消息中提取 PDF 文件路径。如果用户没有提供路径询问文件位置。 2. 确认旋转角度默认 90 度。可选值90、180、270。 3. 执行脚本 python scripts/rotate.py 文件路径 角度 4. 脚本执行成功后告知用户输出文件的位置。 ## 注意事项 - 如果文件路径不存在提示用户重新确认路径不要猜测。 - 角度必须是 90 的整数倍否则提示用户输入合法角度。 - 输出文件默认保存在原文件同目录下文件名追加 _rotated 后缀。这个模板里frontmatter 只有name和description两个字段。description用-折叠写法把“做什么”和“什么时候用”都写清楚尤其是触发词要具体比如“旋转这个 PDF”“转 90 度”这种用户真实会说的话。body 部分用祈使句每一步都是可执行动作没有背景介绍、没有设计原则、没有版本记录。3.3 配套脚本骨架SKILL.md里引用了scripts/rotate.py所以要在同一文件夹下建scripts/目录放入脚本。下面是一个最小可运行版本依赖pypdfimport sys from pypdf import PdfReader, PdfWriter def rotate_pdf(input_path, angle): reader PdfReader(input_path) writer PdfWriter() for page in reader.pages: page.rotate(angle) writer.add_page(page) output_path input_path.replace(.pdf, _rotated.pdf) with open(output_path, wb) as f: writer.write(f) return output_path if __name__ __main__: if len(sys.argv) 3: print(用法: python rotate.py 文件路径 角度) sys.exit(1) path sys.argv[1] deg int(sys.argv[2]) result rotate_pdf(path, deg) print(f已生成: {result})安装依赖pip install pypdf。脚本的作用是执行确定性操作模型不需要读懂它只需要调用它。这就是 Skill 设计里“脆弱操作用脚本锁死”的思路——旋转角度、文件读写这些容易出错的环节交给代码保证一致性。4. 验证请求加载成功与调用失败怎么判断4.1 验证 Skill 是否被加载配置和文件都就位后重启工具。然后问模型一个和 Skill 无关的问题比如“今天天气怎么样”再问一个触发问题“帮我旋转这个 PDF路径是 /tmp/test.pdf转 90 度”。如果 Skill 加载成功模型会识别到pdf-rotator的 description 匹配了当前请求然后按照 body 里的步骤执行提取路径、确认角度、调用脚本。你会在工具的执行日志或对话回复里看到脚本被调用的痕迹比如输出“已生成: /tmp/test_rotated.pdf”。如果模型完全没有反应说明 frontmatter 的 description 没有匹配上。检查两点一是name和文件夹名是否一致二是 description 里的触发词是否覆盖了用户的实际说法。比如用户说“把这个 PDF 转一下”而你的 description 只写了“旋转 PDF 文件”可能就匹配不上。把常见口语说法补进去。4.2 验证 API 通道是否正常Skill 调用脚本之前模型本身要先能正常对话。如果模型连普通问题都答不了先排查 API 配置。可以用 curl 直接测一下通道curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }如果返回里有正常的文本内容说明 Key 和地址都没问题。如果返回 401检查 Key 是否复制完整返回 404检查 baseUrl 是否多写了路径返回超时检查网络是否能访问taotoken.net。4.3 验证脚本能否独立运行在让模型调用脚本之前先在终端手动跑一遍python scripts/rotate.py /tmp/test.pdf 90如果这一步报错比如ModuleNotFoundError: No module named pypdf先装依赖。如果报文件不存在换一个真实存在的 PDF 路径。脚本能独立跑通模型调用时才不会因为环境问题失败。5. 本篇常见错排查5.1 frontmatter 格式错误最常见的报错是 YAML 解析失败。比如description里用了冒号却没有加引号或者缩进用了 Tab。YAML 对缩进敏感统一用两个空格。下面这种写法会报错--- name: pdf-rotator description: 旋转 PDF支持 90 度旋转 ---冒号后面的内容被当成新键值对了。改成折叠写法或者加引号--- name: pdf-rotator description: 旋转 PDF支持 90 度旋转 ---5.2 name 与文件夹名不一致工具在扫描 skills 目录时会用文件夹名去匹配 frontmatter 里的name。如果文件夹叫pdf_rotator而 name 写的是pdf-rotator校验直接不通过。统一用连字符不用下划线且两者完全一致。5.3 description 太模糊导致不触发这是新手最隐蔽的坑。description 写“PDF 处理技能”用户说“帮我转一下这个 PDF”模型无法确定是否该触发。把用户可能说的原话列进去越具体越好。可以这样改description: - 旋转 PDF 文件的页面方向。当用户说“旋转这个 PDF”“把这个 PDF 转 90 度” “调整 PDF 页面方向”“PDF 方向不对”或提供 PDF 文件路径并要求改变页面朝向时使用。5.4 body 里放了触发条件有些朋友把“什么时候使用这个技能”写在 body 里但 body 是触发后才加载的那时候模型已经决定用了再看到触发条件已经晚了。所有 when to use 的信息必须放在 frontmatter 的 description 里。5.5 脚本路径写错SKILL.md里写python scripts/rotate.py但脚本实际在pdf-rotator/scripts/rotate.py而模型执行时的工作目录可能不是 Skill 文件夹。稳妥的做法是在 body 里写清楚相对路径的基准或者用绝对路径。如果工具支持可以在配置里指定 Skill 的工作目录。5.6 API Key 权限或额度问题如果模型对话正常但一调用 Skill 就报错检查 Key 是否有对应模型的权限。有些 Key 可能只开了部分模型。到控制台确认一下额度地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果额度用尽换一个 Key 或者补充额度。6. 跑通之后下一步怎么走第一个 Skill 跑通之后你会对 frontmatter 的触发机制和 body 的执行逻辑有直观感受。接下来可以尝试把重复出现的操作封装成更多 Skill比如文件格式转换、命名规范校验、固定格式的配置生成。每封装一个就少一次重复描述。如果你在接入过程中遇到配置问题优先查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要管理多个 Key 或查看用量去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型对话是否正常用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期做编码类 Skill 或 Agent 工作流可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Skill 开发的核心心法就一句话用最少的 token在正确的层级给模型最精准的约束。frontmatter 负责精准触发body 负责精准执行scripts 负责精准落地。三者各司其职你的 Skill 就能稳定跑起来。