1. 从体检报告说起为什么单一智能体需要 Agent Skills 框架先聊一个真实场景。假设你接到一个需求用户上传一份体检报告系统要完成三件事——解析各项指标、评估健康风险、生成个性化建议。最直觉的做法是写一个超长 Prompt让 LLM 一口气从解析干到建议。Demo 阶段能跑通但一上生产就露馅Prompt 越堆越长token 成本飙升中间某一步算错整条输出全废想调整风险评估策略得改整段 Prompt牵一发动全身。那换成 Multi-Agent 呢三个 Agent 各管一摊、互相通信。听起来很美但你会发现这三步是严格串行的后一步依赖前一步的输出压根不需要协商和并行。Multi-Agent 引入的通信协议、独立 Memory、协调开销在这个场景下全是多余的复杂度。这就是 Agent Skills 框架要解决的问题把大任务拆成标准化的小技能用一个编排器按序调度共享同一份上下文。打个比方Multi-Agent 像多进程——各自独立内存、靠 IPC 通信、隔离性好但开销大Agent Skills 像同一进程下的多线程——共享内存、轻量调度、按需执行不同功能。不是说谁更好而是看你的问题需要隔离还是共享。Agent Skills 可以理解为通用智能体的扩展包。智能体通过加载不同的 Skills 包就能具备不同专业知识、工具使用能力稳定完成特定任务。它适合谁刚接触 LLM 与 Multi-Agent 的开发者、想用单一智能体覆盖多种业务能力的团队、以及被长 Prompt 和 token 成本折磨过的工程师。这篇教程会带你从零跑通一个多技能智能体包含可复制的技能注册配置、统一 Key 接入示例和本地运行验证步骤。2. TaoToken 统一 Key 前置准备一个 Key 打通多模型调用链路在动手写 Skills 框架之前得先把模型调用这一层搞定。Agent Skills 框架里Planner、Executor、Synthesizer 都要调 LLM如果每个组件各配一套 Key、各记一个 Base URL调试起来会非常痛苦。我试过用统一 Key 的方式收敛这一层实测下来确实省心。TaoToken 提供的就是这样一个统一入口一个 API Key兼容主流模型调用格式Base URL 固定为https://taotoken.net/api。你不需要在代码里维护多套鉴权逻辑Skills 框架里所有需要调模型的地方共用同一个客户端即可。前置准备分三步。第一步注册并登录控制台地址是https://taotoken.net/api-keys在 API Keys 页面创建一个新 Key复制保存好后面配置里要用。第二步确认你要用的模型 ID比如claude-sonnet-4-5、gpt-4o这类具体以控制台模型列表为准。第三步把 Base URL、Key、Model ID 这三件套记下来它们是后面所有配置的核心。这里要强调一个概念Agent Skills 框架里的 Skill 是被动的。它不是一个有自主意识的 Agent不需要自己的 Memory、自己的规划能力、自己的通信协议。它只需要满足一个简单契约——给我输入我返回输出。所以模型调用层越简单越好统一 Key 正好符合这个设计哲学。如果你后续要做长期编码或 Agent 类项目可以了解下 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite适合需要持续调用、额度较大的场景。但本篇教程先用按量调用的方式跑通链路不涉及套餐选择。配置环境变量是最推荐的做法避免 Key 硬编码进代码export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-5Windows 用户用 PowerShell$env:TAOTOKEN_API_KEYsk-你的实际Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api $env:TAOTOKEN_MODELclaude-sonnet-4-5环境变量配好后写一个最小的连通性测试脚本确认 Key 能用import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL], messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)跑出来打印「通了」说明统一 Key 这一层没问题。如果报 401先检查 Key 有没有复制完整、有没有多余空格如果报连接错误检查 Base URL 是不是写成了带路径的地址。这一步过了再往下搭 Skills 框架。3. 可复制配置Skill 目录结构与统一客户端 settings 片段Agent Skills 框架的核心设计可以概括为一句话一个协调器统一调度多个 Skills 各司其职三层上下文贯穿始终。五个核心角色职责如下角色职责AgentContext三层结构化上下文贯穿整个流程的信息中枢Planner理解用户意图把大任务拆成小步骤Executor逐步执行每个 Skill管理多种执行模式Synthesizer把多步结果综合为连贯的自然语言回答Coordinator串联以上所有角色的调度中心先解决一个根本问题一个 Skill 到底长什么样答案是一个目录。放进skills/文件夹框架自动发现、自动注册零配置即插即用skills/ └── parse_report/ ├── SKILL.md # 必需元数据 使用文档 ├── prompt.template # 可选Prompt 模板 └── executor.py # 可选自定义执行逻辑SKILL.md的 YAML front matter 定义了 Skill 的身份——名字、描述、触发词、标签。Planner 正是读这些描述来决定选哪个 Skill--- name: parse_report_skill description: 解析体检报告原始数据提取并分类各项检验指标 triggers: - 体检报告 - 体检数据 - 化验单 tags: - 健康 - 体检 --- # parse_report_skill ## 功能说明 接收体检报告原始文本输出结构化指标列表。 ## Available Tools ### 1. check_reference_range 工具名称: Calculation Tool 工具用途: 检查指标是否在参考范围内 工具输入: indicator_name, value 工具返回: status, deviation_percentSkill 的执行有三种模式Executor 按优先级依次检测有executor.py走自定义执行器有prompt.template填充模板后调用 LLM都没有则把SKILL.md的文档部分作为 system prompt 直接调用 LLM。接下来是统一客户端配置。为了让框架里所有组件共用同一个模型入口我把它抽成一个settings.py# settings.py import os from openai import OpenAI TAOTOKEN_BASE_URL os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) TAOTOKEN_API_KEY os.environ[TAOTOKEN_API_KEY] TAOTOKEN_MODEL os.environ.get(TAOTOKEN_MODEL, claude-sonnet-4-5) def get_client() - OpenAI: return OpenAI( api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, ) def invoke(prompt: str, system: str ) - str: client get_client() messages [] if system: messages.append({role: system, content: system}) messages.append({role: user, content: prompt}) resp client.chat.completions.create( modelTAOTOKEN_MODEL, messagesmessages, temperature0.3, ) return resp.choices[0].message.content如果你用 Cline 或 Claude Code 这类工具做辅助开发配置方式类似核心三件套是 Base URL、Key、Model ID。以 Cline 的 MCP 配置为例在 settings 里填{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }注意 Base URL 不要带多余路径Key 不要提交到 Git。这套配置的好处是Skills 框架里的 Planner、Executor、Synthesizer 全部通过settings.invoke()调模型换模型只改一个环境变量。4. 本地运行验证从 Planner 规划到 Synthesizer 综合的完整链路配置就绪后写一个最小可运行的 Coordinator把 Planner、Executor、Synthesizer 串起来。先看 Planner 的实现它负责把用户意图拆成步骤序列# planner.py import json from settings import invoke PLAN_SYSTEM 你是一个任务规划器。根据用户请求和可用 Skill 列表 输出 JSON 格式的执行计划包含 intent 和 steps 两个字段。 每个 step 包含 skill、sub_task、confidence 三个字段。 confidence 低于 0.5 的步骤请过滤掉。只输出 JSON不要额外解释。 def plan(user_input: str, skills: list) - dict: skill_desc \n.join( f- {s[name]}: {s[description]} (triggers: {s[triggers]}) for s in skills ) prompt f用户请求{user_input}\n\n可用 Skill\n{skill_desc} raw invoke(prompt, systemPLAN_SYSTEM) raw raw.strip().removeprefix(json).removesuffix().strip() return json.loads(raw)Executor 负责逐步执行这里体现渐进式上下文披露的核心设计——每一步只看到最小必要上下文由三部分组成自己的 sub_task、累积的前置结果、原始请求。压缩策略遵循一个直觉越新的步骤输出越重要。始终保留原始请求完整保留最新一步输出较早的步骤输出可截断加「已压缩」标记已被消化的最早步骤可丢弃。# executor.py from settings import invoke def build_step_input(sub_task: str, original_request: str, scratchpad: list) - str: parts [f原始请求{original_request}, f当前任务{sub_task}] if scratchpad: recent scratchpad[-1] parts.append(f上一步输出{recent}) if len(scratchpad) 1: earlier | .join(str(s)[:200] for s in scratchpad[:-1]) parts.append(f更早步骤摘要已压缩{earlier}) return \n\n.join(parts) def execute_step(skill: dict, sub_task: str, original_request: str, scratchpad: list) - str: step_input build_step_input(sub_task, original_request, scratchpad) system skill.get(doc, ) return invoke(step_input, systemsystem)Synthesizer 读取原始请求和所有步骤结果生成连贯回答# synthesizer.py from settings import invoke SYNTH_SYSTEM 你是一个综合回答生成器。基于原始请求和各步骤执行结果生成连贯、自然的最终回答。 def synthesize(original_request: str, scratchpad: list) - str: steps_text \n.join(f步骤{i1}结果{s} for i, s in enumerate(scratchpad)) prompt f原始请求{original_request}\n\n{steps_text} return invoke(prompt, systemSYNTH_SYSTEM)最后是 Coordinator 主流程# coordinator.py from planner import plan from executor import execute_step from synthesizer import synthesize SKILLS [ { name: parse_report, description: 解析体检报告原始数据提取并分类各项检验指标, triggers: [体检报告, 体检数据, 化验单], doc: 你负责解析体检报告输出结构化指标列表。, }, { name: assess_risk, description: 基于解析后的指标评估健康风险, triggers: [风险评估, 健康风险, 风险分析], doc: 你负责评估健康风险按心血管、代谢、肝脏、肾脏四维度评分。, }, { name: generate_advice, description: 基于风险评分生成个性化健康建议, triggers: [健康建议, 调理建议, 注意事项], doc: 你负责生成个性化健康建议和复查计划。, }, ] def run(user_input: str) - str: plan_result plan(user_input, SKILLS) print(规划结果, plan_result) scratchpad [] for step in plan_result[steps]: skill next(s for s in SKILLS if s[name] step[skill]) result execute_step(skill, step[sub_task], user_input, scratchpad) scratchpad.append(result) print(f步骤 {step[skill]} 完成) return synthesize(user_input, scratchpad) if __name__ __main__: answer run(帮我分析体检报告并给出建议。) print(\n最终回答\n, answer)运行python coordinator.py你会看到类似输出规划结果打印出三步计划每步执行完打印完成提示最后输出综合回答。如果链路正常说明 Planner 选对了 Skill、Executor 按序执行、Synthesizer 综合成功。这一步跑通整个 Agent Skills 框架的骨架就立起来了。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错搭框架的过程中报错是常态。这一节把几个高频错误对照着讲清楚方便你快速定位。401 Unauthorized。最常见的原因是 Key 没配好。检查三处环境变量TAOTOKEN_API_KEY是否真的导出成功echo $TAOTOKEN_API_KEY看有没有值Key 是否复制完整有没有首尾空格Base URL 是否写成了https://taotoken.net/api/带尾斜杠某些客户端对尾斜杠敏感。如果用的是 Cline 或 Claude Code检查 settings 里的 Key 字段有没有被引号包裹导致多出字符。local proxy failed。这个报错通常出现在客户端配置了本地代理但代理没启动或者 Base URL 指向了本地地址。排查方法确认TAOTOKEN_BASE_URL是https://taotoken.net/api不是http://localhost:xxxx检查系统环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY指向失效地址临时清掉再试unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxyreading choices 相关报错。典型表现是KeyError: choices或AttributeError: NoneType object has no attribute choices。这说明响应体里没有choices字段通常是模型 ID 写错了或者请求体格式不对。检查TAOTOKEN_MODEL是否和控制台模型列表一致检查 messages 数组格式role 只能是system、user、assistant。另外如果返回的是流式响应但你按非流式解析也会拿不到 choices确认stream参数没被误开。OAuth 相关报错。如果你用 Claude Code 或类似工具报 OAuth 失败通常是因为工具默认走官方登录流程而你要用统一 Key 接入。这时需要在工具的配置里显式指定 Base URL 和 API Key覆盖默认的 OAuth 路径。以 Claude Code 为例检查~/.claude/settings.json或项目级配置确保ANTHROPIC_BASE_URL指向https://taotoken.net/apiANTHROPIC_API_KEY填你的 Key。如果工具同时支持 OAuth 和 API Key 两种模式优先选 API Key 模式。Codex auth.json 配置。如果你用 Codex 类工具认证信息在auth.json里格式大致如下{ base_url: https://taotoken.net/api, api_key: sk-你的实际Key, model: claude-sonnet-4-5 }三件套 Base URL、Key、Model ID 缺一不可。改完auth.json后重启工具让配置生效。Skill 没被 Planner 选中。这不是报错但很常见。原因是SKILL.md里的description和triggers写得不够具体Planner 读不懂。把 description 写成一句明确的能力描述triggers 覆盖用户可能说的同义词。比如「体检报告」「体检数据」「化验单」都列上命中率会明显提升。步骤间数据传丢。如果第二步拿不到第一步的输出检查渐进式上下文构建逻辑。字典通道优先通过context[parse_report_skill]取结构化数据文本通道兜底把前置步骤文本拼入参考信息。两条通道至少保证一条通链路才不会断。6. 语义一致 CTA把统一 Key 接入你的 Agent Skills 项目链路跑通之后下一步就是把它接到真实项目里。回顾一下整个流程的关键点Skill 是一个目录靠SKILL.md的 YAML front matter 声明身份Executor 按优先级检测三种执行模式上下文分三层Planner 读用户输入层和 Skill 配置层Executor 读写工作记忆层Synthesizer 读用户输入层和工作记忆层渐进式上下文披露让每一步只看到最小必要信息token 消耗线性增长而非指数增长。模型调用这一层统一 Key 的价值在于收敛。你的 Planner、Executor、Synthesizer 全部通过settings.invoke()走同一个入口换模型只改环境变量不用翻遍代码找硬编码的 Key。Base URL 固定https://taotoken.net/apiKey 在控制台创建Model ID 按需选择。如果你在接入过程中遇到鉴权或配置问题可以直接查接入文档地址是https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各客户端的详细配置示例。想先验证模型是否可用可以去模型对话页面试一条请求地址是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。长期做编码或 Agent 项目的话Coding Plan 页面在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite可以按需了解。最后留一个实用技巧在 Coordinator 里加一行审计日志记录每次 read/write 操作的时间、层、key 和来源。出了 bug看一眼日志就知道谁在什么时间读了什么、写了什么。当用户问「为什么建议我少吃海鲜」你能追溯到完整因果链——parse_report 发现尿酸偏高assess_risk 判定代谢风险中等generate_advice 生成了限嘌呤饮食建议。这不是锦上添花是生产环境的刚需。