1. 从硬编码 Agent 到 Skill 机制我踩过的能力扩展坑如果你正在做 AI 应用开发大概率遇到过这个场景Agent 一开始只处理三五个任务代码写得挺清爽等业务方不断加需求Agent 类里塞满了 if-else工具列表从 10 个涨到 50 个每次请求光工具描述就吃掉几千 token改一个能力还得动核心代码、重新发版。这就是典型的“能力固化 工具爆炸 知识孤岛”三连击。Skill 机制要解决的就是这件事把特定领域的知识、工具调用和推理步骤封装成独立可加载的模块Agent 按需取用不用把所有能力都塞进一次请求里。它适合谁适合正在把 Agent 从 demo 推向生产、被 token 成本和扩展效率卡住的开发者。这篇我会以 TaoToken 统一 Key 作为模型接入通道把 Skill 注册、触发、调用的配置骨架完整跑一遍给出可复制的settings.json和config.toml最后用一次真实请求验证整条调用链。全程不涉及任何网络工具只讲代码和配置。2. TaoToken 前置统一 Key 与接入通道准备Skill 机制本身是应用层的设计但它最终要调用大模型来执行 Skill 指令。如果每个 Skill 各自维护一套模型接入配置Key 管理会立刻失控。所以我用 TaoToken 作为统一入口一个 Key 打通所有 Skill 的模型调用。你需要先拿到 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的接口路径所以现有 SDK 基本不用改只换 base_url 和 key 即可。模型对话、Coding Plan、控制台、API Keys、接入文档都有对应的 deep link后面 CTA 会分流给出。这里有个容易忽略的点Skill 执行时往往需要多轮工具调用属于长上下文、多轮次场景。如果你打算长期跑编码类或 Agent 类 Skill建议了解下 Coding Plan它在高频调用下比按量计费更可控。接入文档里有完整的参数说明配置前扫一眼能省不少排障时间。3. 可复制配置settings.json 与 config.toml 骨架先给目录结构Skill 和配置分离方便版本管理project/ ├── config/ │ ├── settings.json │ └── config.toml ├── skills/ │ ├── valuation_analysis/ │ │ └── skill.md │ └── risk_assessment/ │ └── skill.md └── app/ └── skill_registry.py3.1 settings.json模型接入与 Skill 加载开关{ llm: { provider: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet-4-5, timeout_seconds: 60, max_retries: 2 }, skills: { skills_dir: ./skills, auto_reload: true, lazy_load: true, max_parallel_skills: 4, default_version: latest }, logging: { level: INFO, trace_skill_calls: true } }关键参数说明api_key_env指向环境变量不要把 Key 硬编码进文件lazy_load打开后只有被触发的 Skill 才加载完整指令这是省 token 的核心max_parallel_skills控制并行组合时的并发上限避免打爆模型侧限流。3.2 config.tomlSkill 触发与调用链参数[skill.registry] scan_interval_seconds 30 enable_dependency_resolution true enable_version_check true [skill.trigger] mode semantic similarity_threshold 0.72 fallback_skill general_analysis max_candidate_skills 5 [skill.execution] pipeline_timeout_seconds 120 retry_on_tool_error true cache_ttl_seconds 300 [skill.composition] enable_pipeline true enable_parallel true enable_conditional true enable_loop false loop_max_iterations 5trigger.mode设为semantic表示用语义相似度匹配 Skill而不是关键词硬匹配similarity_threshold是触发门槛太低会误触发太高会漏触发0.7 到 0.75 是实测比较稳的区间。composition里我先关掉 loop因为循环组合在生产环境容易失控等调用链稳定后再开。3.3 skill.md一个最小可用的 Skill 定义--- name: valuation_analysis version: 1.0.0 description: 对标的进行多维度估值分析输出合理价格区间 tags: [valuation, fundamental] dependencies: [] input_schema: target_code: string output_schema: fair_price_range: object confidence: float tools: - get_financial_report - calculate_pe_ratio --- # 估值分析 Skill ## 执行步骤 1. 获取最近四个季度财务数据 2. 计算 PE、PB 相对估值 3. 对比行业均值给出合理区间 4. 输出置信度 ## 注意事项 现金流不稳定的标的慎用 DCF 法。YAML 前置元数据负责注册和触发Markdown 正文是给模型看的执行指令。两者分离改指令不用动注册逻辑。4. 验证请求跑通 Skill 调用链配置就绪后写一个最小验证脚本确认 Skill 能被注册、触发、执行。import os import json import yaml from pathlib import Path from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) def load_skill(skill_dir: Path): content (skill_dir / skill.md).read_text(encodingutf-8) _, frontmatter, body content.split(---, 2) meta yaml.safe_load(frontmatter) return {meta: meta, instructions: body.strip()} def execute_skill(skill, context: dict): prompt f# Skill: {skill[meta][name]} {skill[instructions]} ## 当前上下文 {json.dumps(context, ensure_asciiFalse)} resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: prompt}], temperature0.2, ) return resp.choices[0].message.content if __name__ __main__: skill load_skill(Path(./skills/valuation_analysis)) print(已加载 Skill:, skill[meta][name], skill[meta][version]) result execute_skill(skill, {target_code: 600519}) print(执行结果:, result[:200])运行后你应该看到类似输出已加载 Skill: valuation_analysis 1.0.0 执行结果: 根据最近四个季度财务数据PE 相对估值...如果这一步通了说明 TaoToken 通道、Skill 加载、模型调用三段链路都正常。接下来把execute_skill换成注册表批量管理就能支撑多 Skill 组合。4.1 注册表与触发匹配class SkillRegistry: def __init__(self, skills_dir: Path): self.skills {} for d in skills_dir.iterdir(): if d.is_dir() and (d / skill.md).exists(): s load_skill(d) self.skills[s[meta][name]] s def match(self, query: str, top_k: int 3): scored [] for name, s in self.skills.items(): desc s[meta][description] score len(set(query) set(desc)) / max(len(set(query)), 1) scored.append((score, name)) scored.sort(reverseTrue) return [n for _, n in scored[:top_k]]这是简化版匹配生产环境换成向量相似度即可接口不变。触发后把命中的 Skill 指令拼进 prompt就完成了“按需加载”。5. 本篇常见错排查报错一401 Unauthorized。九成是 Key 没读到。检查TAOTOKEN_API_KEY是否在当前 shell 导出echo $TAOTOKEN_API_KEY确认非空。注意 base_url 结尾不要多加/v1TaoToken 的路径按文档给的形式写。报错二Skill 加载为空。skills_dir路径是相对当前工作目录的脚本从别处启动就会扫不到。改成绝对路径或在启动时打印Path(skills_dir).resolve()确认。报错三YAML 解析失败。skill.md必须以---开头且前置元数据里冒号后要有空格。中文描述里如果含冒号用引号包起来。报错四触发总是命中 fallback。similarity_threshold设太高或 Skill 的description写得太泛。把描述改成具体动作 对象比如“对股票进行 PE/PB 估值”比“分析股票”更容易被匹配。报错五并行执行超时。max_parallel_skills调小或给每个 Skill 单独设超时。模型侧并发有限制时串行反而更稳。报错六token 消耗没降下来。检查lazy_load是否真的生效以及是否把全部 Skill 指令拼进了 system prompt。按需加载的关键是只拼命中的那一个。6. 下一步把调用链接到你的 Agent到这里Skill 注册、触发、执行、排障的骨架已经完整。你可以先把SkillRegistry接进现有 Agent 的决策循环用户输入进来先走match拿到候选 Skill再执行并把结果回填上下文。跑通单 Skill 后再按config.toml里的组合开关逐步打开 pipeline 和 parallel。接入过程中如果卡在 Key 或通道配置直接看接入文档对照参数想先验证模型返回是否符合预期用模型对话页面手动发一条 Skill 指令最快如果你打算把这条链路长期跑在编码或 Agent 场景Coding Plan 的额度模型更适合高频调用。配置文件和 skill.md 模板可以直接复制到项目里改先跑通一个 Skill再复制成生态。 
长河君 · 2026/9/27 19:42:50 · 阅读 1.2k 【AI应用开发实战】27_Skill机制与AI能力扩展：用TaoToken统一Key打通Agent技能调用链
1. 从硬编码 Agent 到 Skill 机制我踩过的能力扩展坑如果你正在做 AI 应用开发大概率遇到过这个场景Agent 一开始只处理三五个任务代码写得挺清爽等业务方不断加需求Agent 类里塞满了 if-else工具列表从 10 个涨到 50 个每次请求光工具描述就吃掉几千 token改一个能力还得动核心代码、重新发版。这就是典型的“能力固化 工具爆炸 知识孤岛”三连击。Skill 机制要解决的就是这件事把特定领域的知识、工具调用和推理步骤封装成独立可加载的模块Agent 按需取用不用把所有能力都塞进一次请求里。它适合谁适合正在把 Agent 从 demo 推向生产、被 token 成本和扩展效率卡住的开发者。这篇我会以 TaoToken 统一 Key 作为模型接入通道把 Skill 注册、触发、调用的配置骨架完整跑一遍给出可复制的settings.json和config.toml最后用一次真实请求验证整条调用链。全程不涉及任何网络工具只讲代码和配置。2. TaoToken 前置统一 Key 与接入通道准备Skill 机制本身是应用层的设计但它最终要调用大模型来执行 Skill 指令。如果每个 Skill 各自维护一套模型接入配置Key 管理会立刻失控。所以我用 TaoToken 作为统一入口一个 Key 打通所有 Skill 的模型调用。你需要先拿到 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的接口路径所以现有 SDK 基本不用改只换 base_url 和 key 即可。模型对话、Coding Plan、控制台、API Keys、接入文档都有对应的 deep link后面 CTA 会分流给出。这里有个容易忽略的点Skill 执行时往往需要多轮工具调用属于长上下文、多轮次场景。如果你打算长期跑编码类或 Agent 类 Skill建议了解下 Coding Plan它在高频调用下比按量计费更可控。接入文档里有完整的参数说明配置前扫一眼能省不少排障时间。3. 可复制配置settings.json 与 config.toml 骨架先给目录结构Skill 和配置分离方便版本管理project/ ├── config/ │ ├── settings.json │ └── config.toml ├── skills/ │ ├── valuation_analysis/ │ │ └── skill.md │ └── risk_assessment/ │ └── skill.md └── app/ └── skill_registry.py3.1 settings.json模型接入与 Skill 加载开关{ llm: { provider: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet-4-5, timeout_seconds: 60, max_retries: 2 }, skills: { skills_dir: ./skills, auto_reload: true, lazy_load: true, max_parallel_skills: 4, default_version: latest }, logging: { level: INFO, trace_skill_calls: true } }关键参数说明api_key_env指向环境变量不要把 Key 硬编码进文件lazy_load打开后只有被触发的 Skill 才加载完整指令这是省 token 的核心max_parallel_skills控制并行组合时的并发上限避免打爆模型侧限流。3.2 config.tomlSkill 触发与调用链参数[skill.registry] scan_interval_seconds 30 enable_dependency_resolution true enable_version_check true [skill.trigger] mode semantic similarity_threshold 0.72 fallback_skill general_analysis max_candidate_skills 5 [skill.execution] pipeline_timeout_seconds 120 retry_on_tool_error true cache_ttl_seconds 300 [skill.composition] enable_pipeline true enable_parallel true enable_conditional true enable_loop false loop_max_iterations 5trigger.mode设为semantic表示用语义相似度匹配 Skill而不是关键词硬匹配similarity_threshold是触发门槛太低会误触发太高会漏触发0.7 到 0.75 是实测比较稳的区间。composition里我先关掉 loop因为循环组合在生产环境容易失控等调用链稳定后再开。3.3 skill.md一个最小可用的 Skill 定义--- name: valuation_analysis version: 1.0.0 description: 对标的进行多维度估值分析输出合理价格区间 tags: [valuation, fundamental] dependencies: [] input_schema: target_code: string output_schema: fair_price_range: object confidence: float tools: - get_financial_report - calculate_pe_ratio --- # 估值分析 Skill ## 执行步骤 1. 获取最近四个季度财务数据 2. 计算 PE、PB 相对估值 3. 对比行业均值给出合理区间 4. 输出置信度 ## 注意事项 现金流不稳定的标的慎用 DCF 法。YAML 前置元数据负责注册和触发Markdown 正文是给模型看的执行指令。两者分离改指令不用动注册逻辑。4. 验证请求跑通 Skill 调用链配置就绪后写一个最小验证脚本确认 Skill 能被注册、触发、执行。import os import json import yaml from pathlib import Path from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) def load_skill(skill_dir: Path): content (skill_dir / skill.md).read_text(encodingutf-8) _, frontmatter, body content.split(---, 2) meta yaml.safe_load(frontmatter) return {meta: meta, instructions: body.strip()} def execute_skill(skill, context: dict): prompt f# Skill: {skill[meta][name]} {skill[instructions]} ## 当前上下文 {json.dumps(context, ensure_asciiFalse)} resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: prompt}], temperature0.2, ) return resp.choices[0].message.content if __name__ __main__: skill load_skill(Path(./skills/valuation_analysis)) print(已加载 Skill:, skill[meta][name], skill[meta][version]) result execute_skill(skill, {target_code: 600519}) print(执行结果:, result[:200])运行后你应该看到类似输出已加载 Skill: valuation_analysis 1.0.0 执行结果: 根据最近四个季度财务数据PE 相对估值...如果这一步通了说明 TaoToken 通道、Skill 加载、模型调用三段链路都正常。接下来把execute_skill换成注册表批量管理就能支撑多 Skill 组合。4.1 注册表与触发匹配class SkillRegistry: def __init__(self, skills_dir: Path): self.skills {} for d in skills_dir.iterdir(): if d.is_dir() and (d / skill.md).exists(): s load_skill(d) self.skills[s[meta][name]] s def match(self, query: str, top_k: int 3): scored [] for name, s in self.skills.items(): desc s[meta][description] score len(set(query) set(desc)) / max(len(set(query)), 1) scored.append((score, name)) scored.sort(reverseTrue) return [n for _, n in scored[:top_k]]这是简化版匹配生产环境换成向量相似度即可接口不变。触发后把命中的 Skill 指令拼进 prompt就完成了“按需加载”。5. 本篇常见错排查报错一401 Unauthorized。九成是 Key 没读到。检查TAOTOKEN_API_KEY是否在当前 shell 导出echo $TAOTOKEN_API_KEY确认非空。注意 base_url 结尾不要多加/v1TaoToken 的路径按文档给的形式写。报错二Skill 加载为空。skills_dir路径是相对当前工作目录的脚本从别处启动就会扫不到。改成绝对路径或在启动时打印Path(skills_dir).resolve()确认。报错三YAML 解析失败。skill.md必须以---开头且前置元数据里冒号后要有空格。中文描述里如果含冒号用引号包起来。报错四触发总是命中 fallback。similarity_threshold设太高或 Skill 的description写得太泛。把描述改成具体动作 对象比如“对股票进行 PE/PB 估值”比“分析股票”更容易被匹配。报错五并行执行超时。max_parallel_skills调小或给每个 Skill 单独设超时。模型侧并发有限制时串行反而更稳。报错六token 消耗没降下来。检查lazy_load是否真的生效以及是否把全部 Skill 指令拼进了 system prompt。按需加载的关键是只拼命中的那一个。6. 下一步把调用链接到你的 Agent到这里Skill 注册、触发、执行、排障的骨架已经完整。你可以先把SkillRegistry接进现有 Agent 的决策循环用户输入进来先走match拿到候选 Skill再执行并把结果回填上下文。跑通单 Skill 后再按config.toml里的组合开关逐步打开 pipeline 和 parallel。接入过程中如果卡在 Key 或通道配置直接看接入文档对照参数想先验证模型返回是否符合预期用模型对话页面手动发一条 Skill 指令最快如果你打算把这条链路长期跑在编码或 Agent 场景Coding Plan 的额度模型更适合高频调用。配置文件和 skill.md 模板可以直接复制到项目里改先跑通一个 Skill再复制成生态。