1. SKILL.md 是什么给大模型读的任务操作手册SKILL.md 是给大模型读的任务操作手册它和 TaoToken 面对的是同一个问题的两头模型在 ReAct 循环里读取说明、执行动作、观察结果每一步都需要稳定的模型推理通道而开发者手里分散在多个平台的 API Key也需要一个统一入口。先到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建 API Key再把模型请求的 Base URL 指到https://taotoken.net/apiSKILL.md 里 curl 业务 API 的部分保持原样两条通道互不干扰。这样配出来的流程才是完整的、能落地跑的 Skills 工程。Skills 这个概念最近在大模型应用里出现频率越来越高。它的本质不是代码而是一个 Markdown 文件SKILL.md。这个文件告诉模型“这个技能是做什么的、什么情况下用、具体怎么执行、输出长什么样”。模型读完这份说明书之后自己组织工具调用自己决定下一步动作而不是由开发者在代码里写死每一步。1.1 操作手册类比大脑再聪明也得先读说明书把 LLM 比作一个经验丰富但没接触过具体业务的新员工SKILL.md 就是放在工位上的操作手册。没有手册时你问一句他答一句遇到复杂任务就开始自由发挥。有了手册他能按标准流程把“查 AI 资讯并整理简报”这种多步骤任务完整跑下来并且每次输出的格式基本一致。对象它在流程里的角色一句话理解LLM思考和执行的“大脑”能读懂规则但没有规则时会乱来SKILL.md给大脑读的说明书把“怎么做”和“别做什么”写得明明白白运行时 Runtime负责扫描目录、按需提供 SKILL.md相当于分发操作手册的管理员没有 Skills 的 LLM 更像一个只能聊天的专家有了 SKILL.md 的 LLM 才是一个能接活、能交付的助手。1.2 全量注入的代价SKILL.md 还没读完Token 先烧掉了很多人第一次接触 Skills 时会问直接把操作说明写进 System Prompt 不就行了这正是 Skills 要解决的痛点。假设你的 SKILL.md 有几十行说明references 目录里还挂着风格指南、历史样例、脚本使用说明一次性全塞进上下文一次任务也许不觉得什么但 ReAct 循环是多轮请求每一轮都会重新带着这些上下文计费。执行一个“查资讯、整理、生成简报”的任务前后可能出现十几轮模型调用每一轮都背着几十 KB 无关内容Token 消耗直接翻倍。Skills 的“按需加载”就是针对这个问题的System Prompt 里只留技能名称和一段 description模型觉得任务匹配才通过 Tool Call 把完整文件读进来。这个机制能省多少 Token取决于目录设计得清不清楚但整个循环要跑起来前提是模型推理请求必须稳定送达。这也是后面要把请求收敛到 TaoToken 的原因。2. Skills 与函数调用通信协议和操作手册的边界Function Calling 和 Skills 容易混淆。前者是一种通信协议开发者写好函数定义模型返回 tool_calls由外部代码执行函数后者是一份任务说明书模型读完 SKILL.md 之后自己写 curl、自己整理数据、自己决定还要不要再读 references。对比维度Function CallingSkills本质通信协议任务说明书开发者写什么函数定义和参数 SchemaSKILL.md 和配套资源模型返回什么tool_calls 调用请求模型自行组织执行计划由谁执行外部程序LLM 按说明自行执行适合场景精确操作如 get_weather复杂工作流如查询 AI 资讯并整理简报这个边界直接决定了你的配置方式。如果用 Function Calling模型只负责返回参数真正的业务逻辑在代码里跑模型通道短、请求次数少。如果用 Skills模型不仅要理解任务还要在 ReAct 循环里反复决策推理请求本身就变成任务的关键路径。请求一旦超时、报 401、或者模型 ID 配错SKILL.md 写得再好也执行不下去。2.1 读取 SKILL.md 本身也是一次 Tool Call在 Skills 机制里“读取 SKILL.md”不是一个后台预加载动作而是模型发起的 Tool Call。模型在 ReAct 循环里看到任务判断某个 Skill 的描述匹配于是发起read_text_file(skills/aihot/SKILL.md)Runtime 把文件内容作为 Observation 返回给模型。也就是说SKILL.md 进入上下文的那一刻背后已经完成了一次完整的模型推理请求。后续执行 curl、查看返回结果、决定是否调整查询条件又是多轮请求。这些请求全部经过你的 API 通道通道不稳定流程就断在读说明书这一环。所以配置 Skills 环境时真正值得花时间的地方不是把 SKILL.md 写得多花哨而是保证模型推理通道的 Key 和 Base URL 是稳定的。3. 渐进式披露、渐进式上下文加载以及 ReAct 循环怎么串起来标准 Skills 流程可以概括成四步启动时扫描技能目录读取每个子目录里的元数据构建出一份 Skill Catalog每次对话只在 System Prompt 中暴露 Catalog也就是每个技能的名称和描述任务到来后模型根据 description 判断要不要读取完整文件一旦读取就进入 ReAct 循环多轮执行和观察直到任务完成。这四个动作串联起来对应着三个关键机制渐进式披露、渐进式上下文加载、ReAct 循环。3.1 渐进式披露Catalog 常驻全文按需进入上下文渐进式披露的意思是启动时只暴露“技能名 description”。这样 System Prompt 不会因为加载大量说明文件而膨胀。Skill Catalog 常驻在上下文中但每个条目只占很少的 Token。模型看到一条描述“查询 AI 圈热门资讯适合做行业简报”就能判断当前任务是否匹配不需要提前读完整个工作流。这个机制省下的 Token 很可观你有 20 个技能每个技能完整说明平均 2000 Token全量注入就是 4 万 Token渐进式披露之后Catalog 可能只占 2000 Token其他全部按需加载。3.2 渐进式上下文加载references、脚本输出用到才读比 SKILL.md 更重的内容还包括 references 目录下的参考文档以及脚本运行时产生的临时输出。渐进式上下文加载要求这些内容也在需要时再进入上下文。比如写作技能里挂了一份references/guide.md模型只有在需要调整文风时才会去读这份文件而不是在启动阶段就把它加载进来。这一机制补完了按需加载的最后一环先读骨架再读血肉最后再看具体数据。3.3 ReAct 循环模型决定下一个动作而不是脚本决定ReAct 循环把决策权交给模型。循环长这样模型先思考当前需要什么信息发出一个 Action比如读取 SKILL.md 或者执行 curlRuntime 返回 Observation比如文件内容或接口响应模型再基于 Observation 决定下一步。是否调用某个 Skill由模型根据 Catalog 判断读完 SKILL.md 后是否还读 references也由模型自己决定。这种设计让复杂任务可以拆成多轮而不是一次性的“输入—输出”。但代价也在这里每一轮都要做一次模型推理推理通道的延迟、额度和稳定性直接决定用户体验。用一个统一入口管理 Key比同时维护多个平台的密钥要省心得多后面会具体说怎么配。4. SKILL.md 文件结构一个 aihot 技能从目录到执行SKILL.md 不是随便写几个标题就行。它需要结构足够清晰模型才能在有限的上下文里快速提取规则。典型结构包含六大块name 用来索引description 用来匹配任务什么时候用说明触发条件工作流说明给出具体执行步骤返回格式约定约束最终输出不要做提供反向约束。这些字段共同决定模型读完之后能不能稳定按预期执行。4.1 SKILL.md 结构从元数据到约束条件字段作用name技能的唯一名称模型用它在目录中引用description技能简介模型据此判断是否匹配当前任务什么时候用说明触发条件防止模型在无关任务中误用工作流说明具体操作步骤可能包含 curl、脚本、查询指令返回格式约定定义最终输出结构比如表格、JSON、Markdown不要做提供约束限制模型自由发挥的边界description 写得够不够好直接影响模型是否会把任务错配给别的技能。比如“查询 AI 资讯并整理简报”这种描述就比较清楚而“资讯处理”就太模糊。4.2 文件组织skills/ 目录怎么摆Skills 通常放在一个约定好的目录下每个技能一个子目录skills/ ├── aihot/ │ └── SKILL.md # AI 资讯查询简报技能 ├── weather-skill/ │ └── SKILL.md # 天气查询技能 ├── writing-skill/ │ ├── SKILL.md │ └── references/ │ └── guide.md # 写作风格指南按需读取 └── calculation-skill/ └── SKILL.md # 计算技能目录本身的扫描和 Catalog 构建由 Runtime 完成开发者只需要约定好目录规则。下面这段是给aihot技能写的一份 SKILL.md 示例重点展示工作流如何引导模型走 ReAct--- name: aihot description: 查询 AI 圈子最近的新闻和产品动态输出结构化简报。适合“今天AI圈有什么新闻”“最近AI圈发生了什么”这类任务。 --- # aihotAI 资讯简报技能 ## 什么时候用 用户要求查 AI 新闻、AI 资讯、行业动态、产品发布信息时使用。 ## 工作流 1. 执行 curl 拉取资讯源原始数据把地址替换为你实际的资讯服务。 curl -s https://api.example.com/ai-news -H Accept: application/json 2. 检查返回结果里是否有有效条目没有则换一个关键字重新请求。 3. 过滤重复新闻按时间从新到旧排序。 4. 按“时间、标题、来源、一句话摘要”整理成表格。 ## 返回格式 使用 Markdown 表格输出每条新闻一行。 ## 不要做 不要添加原始结果里不存在的评论。 不要拼接“据媒体报道”这类无出处描述。模型读到这份 SKILL.md 后会自己执行 curl然后根据返回内容继续决策结果太少就再查一次结果太多就做去重。整个过程不需要外部代码介入模型就是执行者。4.3 示例任务执行从“查新闻”到最终简报的完整链路拿“帮我查一下今天 AI 圈有什么新闻”这个任务走一遍模型在 System Prompt 的 Catalog 里看到 aihot 技能的 description判定匹配随后发起一次 Tool Call读取skills/aihot/SKILL.mdRuntime 返回完整的 SKILL.md 内容模型按照工作流执行 curl读取资讯接口的数据最后整理成简报输出。这个过程中模型读文件要花一次推理请求执行 curl 之后分析返回结果要花一次整理输出又是一次。用户在界面上看到的只是一问一答背后其实是多次模型调用。这也是为什么说SKILL.md 负责教会模型“做什么”而模型推理通道负责保证“每次调用都稳定发生”。如果一个人手里同时管着三四个平台的 Key这个任务跑一半就会因为额度超限或 Key 配置错误断掉。5. 给 aihot 的 ReAct 循环配推理通道Key 用 TaoToken前面的流程跑通之后剩下一件事就是让模型推理请求有一条稳定的通道。这里的关键是分清两种请求模型读 SKILL.md、分析数据、生成简报这些跟 LLM 推理相关的请求统一走 TaoTokenSKILL.md 工作流里 curl 访问资讯服务的请求那是业务 API继续保持原来的地址不要改成 TaoToken 的 Base URL。5.1 准备材料创建 API Key 并选定模型 ID先去 TaoToken 注册账号并创建 API Key。创建之后会得到一个形如YOUR_API_KEY的密钥保存时注意不要复制到换行符或空格。同时到 TaoToken 的模型广场查看可用的模型 ID你的自建 Agent 或 AI 编程工具最终要填的就是这个 ID。这里强调一下两个地址的区别官网落地页是注册、创建 Key、看模型广场的地方而填进工具的 Base URL 是https://taotoken.net/api末尾不要加/v1。5.2 推理通道与业务通道分开Base URL 只改模型请求有人配置时会把 SKILL.md 工作流里的 curl 地址也顺手改成 TaoToken 的地址这是最容易踩的坑。SKILL.md 里的 curl 访问的是资讯服务TaoToken 的https://taotoken.net/api是模型推理接口两者用途完全不同。你只需要把 Agent 初始化时传给大模型的 Base URL 换成 TaoTokenSKILL.md 里业务请求保持原样两条通道各自工作互不干扰。5.3 可复制的接入方式OpenAI SDK 与 Claude Code 环境变量如果你用 OpenAI SDK 风格的自建 Agent代码可以写成这样from openai import OpenAI client OpenAI( api_keyYOUR_API_KEY, base_urlhttps://taotoken.net/api, ) response client.chat.completions.create( model模型广场上的ID, messages[ {role: user, content: 读取 skills/aihot/SKILL.md 并执行帮我看今天 AI 圈有什么新闻} ], ) print(response.choices[0].message.content)如果你用的是 Claude Code可以在环境变量里配置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODEL模型广场上的ID注意ANTHROPIC_BASE_URL同样不加/v1。模型 ID 不要照抄网上教程里的历史版本以 TaoToken 模型广场当前列出的为准。6. 排障对照SKILL.md 能读到模型调用却失败ReAct 循环跑不通常见原因不在 SKILL.md 本身而在通道配置。这里列几个实际会遇到的问题。报错表现可能原因处理方式401 UnauthorizedAPI Key 无效或复制时带了空格回到官网重新创建复制完整 Key404 Not FoundBase URL 写成了带/v1的地址改成https://taotoken.net/apimodel not found模型 ID 写死成了教程里的旧 ID到模型广场核对当前 ID资讯接口请求失败SKILL.md 里的 curl 被误改成 TaoToken 地址恢复为实际的资讯服务地址提示SKILL.md 的读取请求和执行请求都会在控制台留下用量记录。跑完一次“查 AI 资讯”任务之后到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 核对用量如果读 SKILL.md 那一步没有记录说明 Base URL 没有指向https://taotoken.net/api检查配置后再试一次。注意https://taotoken.net/api与业务 API 是两条独立通道任何情况下都不要把 SKILL.md 里的 curl 地址替换成它。前者是给模型推理用的后者是给技能业务逻辑用的混在一起会出现“SKILL.md 读到了但模型频繁报错”的情况。把 aihot 这个技能完整跑通之后你会发现 Skills 的收益真正落在“按需加载”上模型只在需要时读取 SKILL.mdToken 消耗降低输出也容易保持一致。而这一整套流程能稳定运行靠的是模型推理 Key 被收敛到一个统一入口。现在就去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 完成注册创建你的 API Key在模型广场选定一个 ID从read_text_file(skills/aihot/SKILL.md)这一步开始把这次调用跑通。跑通之后后面无论加多少个 Skill都只是往skills/目录里多放一个文件夹的事。