：用SKILL.md做Skill技能封装与渐进式披露，TaoToken统一Key接入实践)
1. 从「临时调工具」到「装一套能力」Skill 到底解决什么问题如果你最近在折腾 Agent大概率遇到过这种尴尬明明给模型配了一堆工具它还是把任务做得七零八落。让它生成一份周报格式每次都不一样让它审查代码这次提了命名规范下次又忘了让它处理 Word 文档它把表格底纹渲染成黑块你还得手动去修。问题不在于模型不够聪明而在于你每次都在用「一次性口语指令」重新教育它。Function Calling 解决了「模型能主动请求调用外部函数」MCP 解决了「模型能标准化连接数据库、API、本地文件」但这两者都没解决一个更根本的问题成熟的工作流和避坑经验怎么沉淀成可复用、可触发、可验证的能力单元。你不可能每次对话都把三千字的操作规范塞进系统提示词那样 token 成本会爆炸模型注意力也会被稀释。Skill 就是冲着这个痛点来的。一个 Skill 本质上是一个包含SKILL.md文件的文件夹里面装着元数据name、description和「如何执行任务的指令」还可以捆绑脚本、参考资料、模板等资源。它把一整套成熟工作流、避坑指南、独门秘籍全塞进一个文件夹里让 Agent 从「临时调工具」走向「标准化能力复用」。这篇文章面向的是已经接触过 Agent 开发、想进一步做能力封装的开发者。我会从技能目录结构讲起拆解元数据声明和按需加载的触发链路给出可复制的SKILL.md模板与目录配置并演示通过 TaoToken 统一 Key/API 通道接入模型完成一次技能加载与渐进披露的验证动作。目标很明确让你能独立搭出一个可运行的技能封装样例。Skill 不是「又一种提示词」而是一个可插拔的能力文件夹。SKILL.md是指令层scripts / references / assets 是能力层。Agent 的差异不在「会不会说」而在「挂了哪些 Skill、怎么用」。2. TaoToken 前置准备统一 Key 与 API 通道配置在动手写 Skill 之前得先把模型接入通道准备好。Skill 本身只是「说明书 资源包」真正执行任务时还是需要模型来读取指令、匹配 description、调用脚本。我选择用 TaoToken 作为统一接入层原因是它把多家模型的 API 通道收敛成一个 Base URL 和一个 Key切换模型时不用改代码这对做 Skill 验证特别方便——你可以用同一个 Skill 在不同模型上跑看触发效果是否一致。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用于代码里的 Base URL。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key。建议给这个 Key 起个能识别的名字比如skill-test方便后续排查问题时定位。创建完成后复制 Key它只会完整显示一次。拿到 Key 之后先别急着写 Skill用最简方式验证通道是否通。我习惯用 curl 先打一发确认 Base URL 和 Key 都没问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 回复两个字通了} ], max_tokens: 32 }如果返回的 JSON 里choices[0].message.content是「通了」说明通道正常。如果报 401先检查 Key 有没有复制完整、有没有多余空格如果报 model not found说明模型 ID 写错了去模型列表页确认一下当前可用的模型标识。这里有个细节值得注意Skill 的渐进式披露机制依赖模型能正确读取SKILL.md头部的 YAML 元数据并做意图匹配。不同模型对结构化文本的解析能力有差异所以建议在正式封装前先用同一个 Skill 在至少两个模型上跑一遍触发测试。TaoToken 的统一 Key 让你不用为每个模型单独配环境变量切换时只改model字段即可。如果你打算长期做 Agent 开发、频繁跑 Skill 验证可以考虑用 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这样后续写 Python 脚本调用时直接读环境变量既安全又方便迁移。如果你用的是 Claude Code 这类客户端它支持在 settings 里配置 Base URL 和 Key具体路径和字段名参考官方接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 可复制配置SKILL.md 模板与目录结构现在进入核心部分。一个 Skill 的物理形态就是一个文件夹标准结构如下my-skill/ ├── SKILL.md # 核心文件指令 元数据 ├── scripts/ # 可选该技能专属的可执行代码 ├── references/ # 可选技术文档、领域知识参考 └── assets/ # 可选模板、静态资源SKILL.md是唯一必需的文件它由两部分组成头部的 YAML Frontmatter元数据和正文指令。元数据字段的规范如下字段必需说明name是Skill 名称最长 64 字符只能用小写字母、数字和-不能以-开头或结尾description是功能与使用场景说明最长 1024 字符不能为空license否许可证名称或指向随 Skill 附带的许可证文件compatibility否环境与依赖说明最长 500 字符metadata否自定义键值对如作者、版本号allowed-tools否允许使用的工具列表空格分隔实验性功能下面是一个可直接复制使用的SKILL.md模板我以一个「日志分析」技能为例--- name: log-analyzer description: 分析应用日志文件提取错误模式、统计错误频率、定位异常时间窗口。当用户提及日志分析、错误排查、异常统计、log 解析时使用。不适用于二进制日志或需要实时流处理的场景。 license: MIT compatibility: 需要 Python 3.9依赖 pandas 和 regex 库 metadata: author: your-name version: 1.0.0 allowed-tools: Read Write Bash --- # 日志分析技能 ## 核心判断 拿到日志文件后先判断格式纯文本行式日志用 scripts/parse_text_log.pyJSON 结构化日志用 scripts/parse_json_log.py。不要试图用同一种解析器处理所有格式。 ## 执行步骤 1. 读取日志文件前 100 行识别时间戳格式和日志级别标记。 2. 根据格式选择对应解析脚本运行后输出标准化 DataFrame。 3. 按错误级别过滤统计各错误码出现频次。 4. 对频次 Top 5 的错误提取前后各 3 行上下文。 5. 生成分析报告包含错误分布表和异常时间窗口。 ## 检查点 完成第 3 步后先确认错误码统计总数与原始日志行数比例是否合理。如果错误占比超过 50%大概率是日志级别解析错误回到第 1 步重新识别格式。 ## 参考文件 需要输出报告模板时读取 references/report-template.md。 需要了解常见错误码含义时读取 references/error-codes.md。这个模板体现了几个关键设计原则。description写得足够具体既包含「做什么」分析日志、提取错误模式、统计频率也包含「何时用」用户提及日志分析、错误排查等触发词还显式排除了不适用的场景二进制日志、实时流处理。这样模型在发现阶段做意图匹配时能准确判断该不该激活这个 Skill。正文部分把「核心判断」放在最前面因为这是决定后续流程走向的分支点。执行步骤用编号列出每步都是可操作的动词开头。检查点放在关键步骤之后防止模型在错误的基础上继续往下跑。参考文件用「需要 XX 时读取 XX」的句式实现按需加载。scripts/目录放具体执行脚本。比如parse_text_log.pyimport re import sys import pandas as pd def parse_text_log(filepath): pattern re.compile( r(?Ptimestamp\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\s r(?PlevelINFO|WARN|ERROR|DEBUG)\s r(?Pmessage.) ) records [] with open(filepath, r, encodingutf-8) as f: for line in f: m pattern.match(line.strip()) if m: records.append(m.groupdict()) return pd.DataFrame(records) if __name__ __main__: df parse_text_log(sys.argv[1]) print(df.to_string())references/目录放领域知识。比如error-codes.md里列出你们系统特有的错误码含义这些是模型不可能自己知道的私有知识正是 Skill 该承载的内容。assets/目录放静态资源比如报告模板、JSON Schema、对比示例图。整个配置的核心逻辑是SKILL.md主文件保持轻量重活和知识外置到附属目录模型用到什么才加载什么。这就是渐进式披露的物理基础。4. 验证请求跑通一次技能加载与渐进披露配置写好了接下来验证它是否真的能被模型正确加载和触发。我写一个 Python 脚本来模拟 Agent 的技能发现、激活、执行三个阶段。先安装依赖pip install openai pyyaml然后写验证脚本verify_skill.pyimport os import yaml from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] /v1 ) def load_skill_metadata(skill_dir): 阶段一发现——只读取 YAML 元数据 skill_md os.path.join(skill_dir, SKILL.md) with open(skill_md, r, encodingutf-8) as f: content f.read() # 提取 frontmatter if content.startswith(---): parts content.split(---, 2) meta yaml.safe_load(parts[1]) body parts[2].strip() return meta, body return {}, content def build_index(skills_root): 扫描所有 Skill构建轻量索引 index [] for name in os.listdir(skills_root): skill_dir os.path.join(skills_root, name) if os.path.isdir(skill_dir): meta, _ load_skill_metadata(skill_dir) if meta: index.append({ name: meta.get(name), description: meta.get(description), path: skill_dir }) return index def match_skill(index, user_query): 阶段二激活——用模型判断该触发哪个 Skill index_text \n.join( f- {s[name]}: {s[description]} for s in index ) prompt f你是一个技能路由器。根据用户请求从以下技能索引中选择最匹配的一个。 只返回技能名称不要解释。 技能索引 {index_text} 用户请求{user_query} resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: prompt}], max_tokens64 ) return resp.choices[0].message.content.strip() def execute_skill(skill_path, user_query): 阶段三执行——加载完整 SKILL.md 正文 meta, body load_skill_metadata(skill_path) prompt f你正在执行技能「{meta[name]}」。 以下是该技能的完整指令 {body} 用户请求{user_query} 请按照指令执行需要读取参考文件时明确说明要读哪个文件。 resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: prompt}], max_tokens1024 ) return resp.choices[0].message.content if __name__ __main__: skills_root ./skills index build_index(skills_root) print( 阶段一技能索引 ) for s in index: print(f {s[name]}: {s[description][:60]}...) query 帮我分析一下 app.log 里的错误分布 print(f\n 用户请求{query} ) matched match_skill(index, query) print(f\n 阶段二匹配到技能「{matched}」 ) skill_path os.path.join(skills_root, matched) result execute_skill(skill_path, query) print(f\n 阶段三执行结果 ) print(result)把之前写的log-analyzer技能放到./skills/log-analyzer/目录下然后运行python verify_skill.py预期输出分三段。第一段打印技能索引你会看到log-analyzer的 name 和 description 前 60 字符。第二段是模型根据用户请求匹配到的技能名应该是log-analyzer。第三段是模型加载完整SKILL.md正文后的执行结果它会按照指令里的步骤描述分析流程并说明需要读取references/error-codes.md来查错误码含义。这个验证过程完整走通了渐进式披露的三个阶段发现阶段只加载了 YAML 元数据token 消耗极低激活阶段模型根据 description 做意图匹配执行阶段才把完整正文注入上下文。你可以试着在skills/目录下再放两三个技能观察模型是否能在多个技能中准确路由。如果想更直观地看模型对话效果可以打开模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 把SKILL.md正文粘贴进去手动模拟一次技能执行对比不同模型的指令遵循能力。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节整理我在实际接入和验证过程中踩过的坑按报错信息对照排查。401 Unauthorized。最常见的原因是 Key 没传对。检查三处环境变量TAOTOKEN_API_KEY是否真的导出成功用echo $TAOTOKEN_API_KEY确认代码里Bearer后面有没有多余空格Key 是否已经过期或被删除。如果用的是 Claude Code 这类客户端检查 settings 里的ANTHROPIC_AUTH_TOKEN或对应字段是否填的是 TaoToken 的 Key而不是其他平台的。local proxy failed / connection refused。这个报错通常出现在客户端配置了本地代理端口但代理没启动或者 Base URL 写成了localhost。检查你的 Base URL 是不是https://taotoken.net/api不要带尾部斜杠也不要在后面加/v1OpenAI SDK 会自动拼/v1如果你手动加了会变成/v1/v1。如果你在 settings.json 里配置确认字段名和路径与官方文档一致。reading choices of undefined。这是 OpenAI SDK 的典型报错意思是返回体里没有choices字段。原因通常是 Base URL 配错了请求打到了非 API 端点返回了 HTML 页面而不是 JSON。检查base_url是否指向https://taotoken.net/api/v1以及model字段是否填了当前可用的模型 ID。如果模型 ID 不存在有些网关会返回错误结构SDK 解析时就报这个。OAuth 相关报错。如果你用的是 Claude Code 或 Codex 这类需要登录的客户端可能会遇到 OAuth token 过期或认证方式冲突。这类客户端通常支持两种认证OAuth 登录和 API Key。用 TaoToken 接入时应该走 API Key 方式在配置里明确指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY或对应字段不要同时启用 OAuth。如果之前登录过官方账号先清理掉旧的凭证缓存。技能不触发。这不是报错但比报错更让人头疼。如果模型没有匹配到你的 Skill先检查description是否包含了用户可能说的触发词。比如用户说「帮我看看日志哪里报错了」而你的 description 只写了「日志分析」没有「报错」「错误」这类词模型可能匹配不上。解决办法是把 description 写成「做什么 何时用 用户会怎么说」的结构。脚本执行权限问题。scripts/下的 Python 脚本如果被 Agent 直接调用确保有执行权限chmod x并且 shebang 行正确。如果脚本依赖第三方库在compatibility字段里写清楚避免 Agent 在缺依赖的环境里跑失败。排查时建议先用 curl 确认通道本身没问题再排查 Skill 配置。通道问题占报错的七成以上而通道问题里又有七成是 Base URL 或 Key 写错。把这两个变量确认清楚大部分问题就消失了。6. 语义一致收口把 Skill 接入你的 Agent 工作流到这里你已经有了一个可运行的技能封装样例目录结构清晰SKILL.md模板可复制验证脚本跑通了发现、激活、执行三个阶段常见报错也有了对照排查表。接下来要做的是把这个模式复制到你自己的场景里。我建议从你最常重复的那件事开始封装。判断标准很简单如果某个任务你每周至少做一次流程基本固定输出有格式要求那就值得做成 Skill。比如周报生成、代码审查清单、测试报告模板、API 文档解析。反过来偶发的、一次性的、没有格式要求的任务直接写 Prompt 就行做成 Skill 反而是过度设计。封装时记住几个要点。description是路由开关决定 Skill 会不会被触发要写清楚触发词和排除条件。主文件只写模型不知道的私有知识通用常识删掉。重活外置到scripts/知识外置到references/模板外置到assets/。复杂流程在关键步骤后加检查点。先跑起来再慢慢打磨。如果你在接入过程中需要查具体的 API 参数或客户端配置字段接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要管理多个 Key 或查看用量控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。API Keys 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Skill 的价值不在于「写了一个 Markdown 文件」而在于你把专家经验用最省的 token 沉淀成了可触发、可复用、可验证的 SOP。渐进式披露让几百个 Skill 同时挂机也不撑爆上下文这才是 Agent 工程化真正可行的基石。你打算先给自己的 Agent 封装哪个技能从那个你每周都在重复、每次都做得不太一样的任务开始就对了。 
长河君 · 2026/10/17 19:33:32 · 阅读 1.2k 大模型技术全景(十四)：用SKILL.md做Skill技能封装与渐进式披露，TaoToken统一Key接入实践
1. 从「临时调工具」到「装一套能力」Skill 到底解决什么问题如果你最近在折腾 Agent大概率遇到过这种尴尬明明给模型配了一堆工具它还是把任务做得七零八落。让它生成一份周报格式每次都不一样让它审查代码这次提了命名规范下次又忘了让它处理 Word 文档它把表格底纹渲染成黑块你还得手动去修。问题不在于模型不够聪明而在于你每次都在用「一次性口语指令」重新教育它。Function Calling 解决了「模型能主动请求调用外部函数」MCP 解决了「模型能标准化连接数据库、API、本地文件」但这两者都没解决一个更根本的问题成熟的工作流和避坑经验怎么沉淀成可复用、可触发、可验证的能力单元。你不可能每次对话都把三千字的操作规范塞进系统提示词那样 token 成本会爆炸模型注意力也会被稀释。Skill 就是冲着这个痛点来的。一个 Skill 本质上是一个包含SKILL.md文件的文件夹里面装着元数据name、description和「如何执行任务的指令」还可以捆绑脚本、参考资料、模板等资源。它把一整套成熟工作流、避坑指南、独门秘籍全塞进一个文件夹里让 Agent 从「临时调工具」走向「标准化能力复用」。这篇文章面向的是已经接触过 Agent 开发、想进一步做能力封装的开发者。我会从技能目录结构讲起拆解元数据声明和按需加载的触发链路给出可复制的SKILL.md模板与目录配置并演示通过 TaoToken 统一 Key/API 通道接入模型完成一次技能加载与渐进披露的验证动作。目标很明确让你能独立搭出一个可运行的技能封装样例。Skill 不是「又一种提示词」而是一个可插拔的能力文件夹。SKILL.md是指令层scripts / references / assets 是能力层。Agent 的差异不在「会不会说」而在「挂了哪些 Skill、怎么用」。2. TaoToken 前置准备统一 Key 与 API 通道配置在动手写 Skill 之前得先把模型接入通道准备好。Skill 本身只是「说明书 资源包」真正执行任务时还是需要模型来读取指令、匹配 description、调用脚本。我选择用 TaoToken 作为统一接入层原因是它把多家模型的 API 通道收敛成一个 Base URL 和一个 Key切换模型时不用改代码这对做 Skill 验证特别方便——你可以用同一个 Skill 在不同模型上跑看触发效果是否一致。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用于代码里的 Base URL。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key。建议给这个 Key 起个能识别的名字比如skill-test方便后续排查问题时定位。创建完成后复制 Key它只会完整显示一次。拿到 Key 之后先别急着写 Skill用最简方式验证通道是否通。我习惯用 curl 先打一发确认 Base URL 和 Key 都没问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 回复两个字通了} ], max_tokens: 32 }如果返回的 JSON 里choices[0].message.content是「通了」说明通道正常。如果报 401先检查 Key 有没有复制完整、有没有多余空格如果报 model not found说明模型 ID 写错了去模型列表页确认一下当前可用的模型标识。这里有个细节值得注意Skill 的渐进式披露机制依赖模型能正确读取SKILL.md头部的 YAML 元数据并做意图匹配。不同模型对结构化文本的解析能力有差异所以建议在正式封装前先用同一个 Skill 在至少两个模型上跑一遍触发测试。TaoToken 的统一 Key 让你不用为每个模型单独配环境变量切换时只改model字段即可。如果你打算长期做 Agent 开发、频繁跑 Skill 验证可以考虑用 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这样后续写 Python 脚本调用时直接读环境变量既安全又方便迁移。如果你用的是 Claude Code 这类客户端它支持在 settings 里配置 Base URL 和 Key具体路径和字段名参考官方接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 可复制配置SKILL.md 模板与目录结构现在进入核心部分。一个 Skill 的物理形态就是一个文件夹标准结构如下my-skill/ ├── SKILL.md # 核心文件指令 元数据 ├── scripts/ # 可选该技能专属的可执行代码 ├── references/ # 可选技术文档、领域知识参考 └── assets/ # 可选模板、静态资源SKILL.md是唯一必需的文件它由两部分组成头部的 YAML Frontmatter元数据和正文指令。元数据字段的规范如下字段必需说明name是Skill 名称最长 64 字符只能用小写字母、数字和-不能以-开头或结尾description是功能与使用场景说明最长 1024 字符不能为空license否许可证名称或指向随 Skill 附带的许可证文件compatibility否环境与依赖说明最长 500 字符metadata否自定义键值对如作者、版本号allowed-tools否允许使用的工具列表空格分隔实验性功能下面是一个可直接复制使用的SKILL.md模板我以一个「日志分析」技能为例--- name: log-analyzer description: 分析应用日志文件提取错误模式、统计错误频率、定位异常时间窗口。当用户提及日志分析、错误排查、异常统计、log 解析时使用。不适用于二进制日志或需要实时流处理的场景。 license: MIT compatibility: 需要 Python 3.9依赖 pandas 和 regex 库 metadata: author: your-name version: 1.0.0 allowed-tools: Read Write Bash --- # 日志分析技能 ## 核心判断 拿到日志文件后先判断格式纯文本行式日志用 scripts/parse_text_log.pyJSON 结构化日志用 scripts/parse_json_log.py。不要试图用同一种解析器处理所有格式。 ## 执行步骤 1. 读取日志文件前 100 行识别时间戳格式和日志级别标记。 2. 根据格式选择对应解析脚本运行后输出标准化 DataFrame。 3. 按错误级别过滤统计各错误码出现频次。 4. 对频次 Top 5 的错误提取前后各 3 行上下文。 5. 生成分析报告包含错误分布表和异常时间窗口。 ## 检查点 完成第 3 步后先确认错误码统计总数与原始日志行数比例是否合理。如果错误占比超过 50%大概率是日志级别解析错误回到第 1 步重新识别格式。 ## 参考文件 需要输出报告模板时读取 references/report-template.md。 需要了解常见错误码含义时读取 references/error-codes.md。这个模板体现了几个关键设计原则。description写得足够具体既包含「做什么」分析日志、提取错误模式、统计频率也包含「何时用」用户提及日志分析、错误排查等触发词还显式排除了不适用的场景二进制日志、实时流处理。这样模型在发现阶段做意图匹配时能准确判断该不该激活这个 Skill。正文部分把「核心判断」放在最前面因为这是决定后续流程走向的分支点。执行步骤用编号列出每步都是可操作的动词开头。检查点放在关键步骤之后防止模型在错误的基础上继续往下跑。参考文件用「需要 XX 时读取 XX」的句式实现按需加载。scripts/目录放具体执行脚本。比如parse_text_log.pyimport re import sys import pandas as pd def parse_text_log(filepath): pattern re.compile( r(?Ptimestamp\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\s r(?PlevelINFO|WARN|ERROR|DEBUG)\s r(?Pmessage.) ) records [] with open(filepath, r, encodingutf-8) as f: for line in f: m pattern.match(line.strip()) if m: records.append(m.groupdict()) return pd.DataFrame(records) if __name__ __main__: df parse_text_log(sys.argv[1]) print(df.to_string())references/目录放领域知识。比如error-codes.md里列出你们系统特有的错误码含义这些是模型不可能自己知道的私有知识正是 Skill 该承载的内容。assets/目录放静态资源比如报告模板、JSON Schema、对比示例图。整个配置的核心逻辑是SKILL.md主文件保持轻量重活和知识外置到附属目录模型用到什么才加载什么。这就是渐进式披露的物理基础。4. 验证请求跑通一次技能加载与渐进披露配置写好了接下来验证它是否真的能被模型正确加载和触发。我写一个 Python 脚本来模拟 Agent 的技能发现、激活、执行三个阶段。先安装依赖pip install openai pyyaml然后写验证脚本verify_skill.pyimport os import yaml from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] /v1 ) def load_skill_metadata(skill_dir): 阶段一发现——只读取 YAML 元数据 skill_md os.path.join(skill_dir, SKILL.md) with open(skill_md, r, encodingutf-8) as f: content f.read() # 提取 frontmatter if content.startswith(---): parts content.split(---, 2) meta yaml.safe_load(parts[1]) body parts[2].strip() return meta, body return {}, content def build_index(skills_root): 扫描所有 Skill构建轻量索引 index [] for name in os.listdir(skills_root): skill_dir os.path.join(skills_root, name) if os.path.isdir(skill_dir): meta, _ load_skill_metadata(skill_dir) if meta: index.append({ name: meta.get(name), description: meta.get(description), path: skill_dir }) return index def match_skill(index, user_query): 阶段二激活——用模型判断该触发哪个 Skill index_text \n.join( f- {s[name]}: {s[description]} for s in index ) prompt f你是一个技能路由器。根据用户请求从以下技能索引中选择最匹配的一个。 只返回技能名称不要解释。 技能索引 {index_text} 用户请求{user_query} resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: prompt}], max_tokens64 ) return resp.choices[0].message.content.strip() def execute_skill(skill_path, user_query): 阶段三执行——加载完整 SKILL.md 正文 meta, body load_skill_metadata(skill_path) prompt f你正在执行技能「{meta[name]}」。 以下是该技能的完整指令 {body} 用户请求{user_query} 请按照指令执行需要读取参考文件时明确说明要读哪个文件。 resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: prompt}], max_tokens1024 ) return resp.choices[0].message.content if __name__ __main__: skills_root ./skills index build_index(skills_root) print( 阶段一技能索引 ) for s in index: print(f {s[name]}: {s[description][:60]}...) query 帮我分析一下 app.log 里的错误分布 print(f\n 用户请求{query} ) matched match_skill(index, query) print(f\n 阶段二匹配到技能「{matched}」 ) skill_path os.path.join(skills_root, matched) result execute_skill(skill_path, query) print(f\n 阶段三执行结果 ) print(result)把之前写的log-analyzer技能放到./skills/log-analyzer/目录下然后运行python verify_skill.py预期输出分三段。第一段打印技能索引你会看到log-analyzer的 name 和 description 前 60 字符。第二段是模型根据用户请求匹配到的技能名应该是log-analyzer。第三段是模型加载完整SKILL.md正文后的执行结果它会按照指令里的步骤描述分析流程并说明需要读取references/error-codes.md来查错误码含义。这个验证过程完整走通了渐进式披露的三个阶段发现阶段只加载了 YAML 元数据token 消耗极低激活阶段模型根据 description 做意图匹配执行阶段才把完整正文注入上下文。你可以试着在skills/目录下再放两三个技能观察模型是否能在多个技能中准确路由。如果想更直观地看模型对话效果可以打开模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 把SKILL.md正文粘贴进去手动模拟一次技能执行对比不同模型的指令遵循能力。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节整理我在实际接入和验证过程中踩过的坑按报错信息对照排查。401 Unauthorized。最常见的原因是 Key 没传对。检查三处环境变量TAOTOKEN_API_KEY是否真的导出成功用echo $TAOTOKEN_API_KEY确认代码里Bearer后面有没有多余空格Key 是否已经过期或被删除。如果用的是 Claude Code 这类客户端检查 settings 里的ANTHROPIC_AUTH_TOKEN或对应字段是否填的是 TaoToken 的 Key而不是其他平台的。local proxy failed / connection refused。这个报错通常出现在客户端配置了本地代理端口但代理没启动或者 Base URL 写成了localhost。检查你的 Base URL 是不是https://taotoken.net/api不要带尾部斜杠也不要在后面加/v1OpenAI SDK 会自动拼/v1如果你手动加了会变成/v1/v1。如果你在 settings.json 里配置确认字段名和路径与官方文档一致。reading choices of undefined。这是 OpenAI SDK 的典型报错意思是返回体里没有choices字段。原因通常是 Base URL 配错了请求打到了非 API 端点返回了 HTML 页面而不是 JSON。检查base_url是否指向https://taotoken.net/api/v1以及model字段是否填了当前可用的模型 ID。如果模型 ID 不存在有些网关会返回错误结构SDK 解析时就报这个。OAuth 相关报错。如果你用的是 Claude Code 或 Codex 这类需要登录的客户端可能会遇到 OAuth token 过期或认证方式冲突。这类客户端通常支持两种认证OAuth 登录和 API Key。用 TaoToken 接入时应该走 API Key 方式在配置里明确指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY或对应字段不要同时启用 OAuth。如果之前登录过官方账号先清理掉旧的凭证缓存。技能不触发。这不是报错但比报错更让人头疼。如果模型没有匹配到你的 Skill先检查description是否包含了用户可能说的触发词。比如用户说「帮我看看日志哪里报错了」而你的 description 只写了「日志分析」没有「报错」「错误」这类词模型可能匹配不上。解决办法是把 description 写成「做什么 何时用 用户会怎么说」的结构。脚本执行权限问题。scripts/下的 Python 脚本如果被 Agent 直接调用确保有执行权限chmod x并且 shebang 行正确。如果脚本依赖第三方库在compatibility字段里写清楚避免 Agent 在缺依赖的环境里跑失败。排查时建议先用 curl 确认通道本身没问题再排查 Skill 配置。通道问题占报错的七成以上而通道问题里又有七成是 Base URL 或 Key 写错。把这两个变量确认清楚大部分问题就消失了。6. 语义一致收口把 Skill 接入你的 Agent 工作流到这里你已经有了一个可运行的技能封装样例目录结构清晰SKILL.md模板可复制验证脚本跑通了发现、激活、执行三个阶段常见报错也有了对照排查表。接下来要做的是把这个模式复制到你自己的场景里。我建议从你最常重复的那件事开始封装。判断标准很简单如果某个任务你每周至少做一次流程基本固定输出有格式要求那就值得做成 Skill。比如周报生成、代码审查清单、测试报告模板、API 文档解析。反过来偶发的、一次性的、没有格式要求的任务直接写 Prompt 就行做成 Skill 反而是过度设计。封装时记住几个要点。description是路由开关决定 Skill 会不会被触发要写清楚触发词和排除条件。主文件只写模型不知道的私有知识通用常识删掉。重活外置到scripts/知识外置到references/模板外置到assets/。复杂流程在关键步骤后加检查点。先跑起来再慢慢打磨。如果你在接入过程中需要查具体的 API 参数或客户端配置字段接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要管理多个 Key 或查看用量控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。API Keys 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Skill 的价值不在于「写了一个 Markdown 文件」而在于你把专家经验用最省的 token 沉淀成了可触发、可复用、可验证的 SOP。渐进式披露让几百个 Skill 同时挂机也不撑爆上下文这才是 Agent 工程化真正可行的基石。你打算先给自己的 Agent 封装哪个技能从那个你每周都在重复、每次都做得不太一样的任务开始就对了。