1. 从提示词堆砌到技能包Agent Skill 到底解决什么问题如果你正在做 LLM 应用落地大概率经历过这样的场景想让智能体处理一份 PDF 合同提示词里得写清楚「先用 PyPDF2 提取文本乱码就换 pdfplumber再不行转图片走 OCR」想让它按公司规范生成合同ReAct 模式下每次调用工具的顺序都不一样同一需求走出三条路径想固定业务流程Workflow 又把执行路径焊死在平台里终端用户只能「用」不能「改」。这些困境指向同一个问题提示词工程解决「激发」ReAct 解决「连接」Workflow 解决「编排」但三者都没能同时满足「专业化、标准化、可复用」。Agent Skill 就是在这个缝隙里长出来的能力模块——它把提示词、工具调用、执行步骤封装成一个文件夹按需加载随插随用。Agent Skill 是 Anthropic 提出的一种轻量级能力封装方式物理载体是一个文件夹文件夹名就是 Skill 名。核心文件是SKILL.md用 Markdown 写顶部是 YAML 格式的元数据至少包含 name 和 description下面是执行指令。可选目录有三个scripts/放可执行脚本references/放参考资料assets/放模板和静态资源。它的工作方式叫「渐进式披露」分三层加载。L1 是元数据智能体初始化时只读每个 Skill 的名称和描述占用上下文极小但「知道」自己有哪些技能。L2 是执行指令当 LLM 判断用户输入和某个 Skill 描述匹配后才把SKILL.md的完整指令读进上下文。L3 是动态内容执行过程中脚本运行结果、按需引用的参考文件才被加载。没被选中的 Skill指令内容根本不进上下文。这套机制的价值在于你不再需要把领域知识全塞进系统提示词也不用担心 ReAct 路径飘忽。Skill 里的工具调用链是预先定义的执行步骤是固定的但 Skill 本身由终端用户自己编排可以随时插拔。一句话概括平台提供执行引擎用户提供执行剧本。我试过把一个「合同生成」流程从提示词迁移到 Skill最直观的变化是上下文占用从 3000 token 降到 200 左右而且工具调用顺序稳定了。下面就从零搭一个最小闭环用 TaoToken 统一 Key 把模型通道接上。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写 Skill 之前先把模型通道打通。Agent Skill 本身不绑定模型供应商它只负责「编排」真正推理还得靠 LLM。TaoToken 在这里的角色是统一 Key 和 API 通道——你用一个 Key 就能访问多个模型Skill 里的脚本和智能体框架都走同一个 Base URL省去多供应商切换的麻烦。先注册并拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在「API Keys」页面创建一个新 Key。建议按项目命名比如agent-skill-demo方便后续排查。创建完 Key 后API 端点固定为 https://taotoken.net/api 注意这个地址不加 UTM 参数直接作为 Base URL 使用。模型 ID 可以在「模型对话」页面查看也可以直接调/v1/models接口拉列表。常用的模型 ID 比如claude-sonnet-4-20250514、gpt-4o等具体以控制台显示为准。环境变量建议这样设置避免把 Key 硬编码进脚本export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-20250514如果你用的是 Claude Code 或 Cline 这类工具配置方式略有不同。Claude Code 需要在~/.claude/settings.json里写env字段Cline 则在 MCP 配置里填 Base URL 和 Key。不管哪种方式三件套都是Base URL 填https://taotoken.net/apiKey 填你创建的那串Model ID 填控制台里选的模型。这里有个容易踩的坑Base URL 末尾不要加/v1TaoToken 的路径已经内置了版本段。如果你填成https://taotoken.net/api/v1请求会 404。另外 Key 不要提交到 Git用.env文件加.gitignore隔离。配置完成后先用一条 curl 验证通道是否通curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }返回里能看到choices[0].message.content就说明通道没问题。这一步过了再往下写 Skill 才有意义。3. 可复制配置SKILL.md 与 settings 片段现在写一个最小可运行的 Skill。目标场景用户输入一段需求Skill 负责判断是销售合同还是服务协议收集字段调用脚本生成文档。目录结构如下contract-generator/ ├── SKILL.md ├── scripts/ │ └── generate_contract.py ├── references/ │ └── field_mapping.csv └── assets/ └── templates/ ├── sales_contract_template.docx └── service_agreement_template.docxSKILL.md的完整内容可以直接复制--- name: contract-generator description: 专业合同生成器。当用户需要生成销售合同或服务协议时使用此技能。 --- # 合同生成器 ## 概述 自动化生成销售合同或服务协议文档支持模板填充和 PDF 导出。 ## 可用模板 - sales_contract_template.docx - 销售合同模板 - service_agreement_template.docx - 服务协议模板 ## 工作流程 ### 1. 选择模板 - 涉及产品销售 → sales_contract_template.docx - 涉及服务提供 → service_agreement_template.docx ### 2. 收集信息 参考 references/field_mapping.csv 获取必填字段向用户收集 - 合同双方信息 - 合同金额 - 服务/产品详情 - 签署日期 ### 3. 生成合同 运行生成脚本 bash python scripts/generate_contract.py --template 模板 --data 用户数据 --output 输出路径4. 导出 PDFbash scripts/export_to_pdf.sh 输入文件 输出文件参考文件文件用途references/clause_library.md标准条款库references/field_mapping.csv字段映射表注意事项生成的合同建议由法务审核后再正式使用。scripts/generate_contract.py 的最小实现用 TaoToken 做字段抽取 python import os import json import argparse import requests TAOTOKEN_BASE_URL os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) TAOTOKEN_API_KEY os.getenv(TAOTOKEN_API_KEY) TAOTOKEN_MODEL os.getenv(TAOTOKEN_MODEL, claude-sonnet-4-20250514) def extract_fields(raw_text: str) - dict: resp requests.post( f{TAOTOKEN_BASE_URL}/v1/chat/completions, headers{ Authorization: fBearer {TAOTOKEN_API_KEY}, Content-Type: application/json, }, json{ model: TAOTOKEN_MODEL, messages: [ {role: system, content: 从用户输入中抽取合同字段输出 JSON。}, {role: user, content: raw_text}, ], response_format: {type: json_object}, }, timeout60, ) resp.raise_for_status() return json.loads(resp.json()[choices][0][message][content]) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--template, requiredTrue) parser.add_argument(--data, requiredTrue) parser.add_argument(--output, requiredTrue) args parser.parse_args() fields extract_fields(args.data) print(f模板: {args.template}) print(f抽取字段: {json.dumps(fields, ensure_asciiFalse)}) print(f输出路径: {args.output})如果你用 Claude Code 加载这个 Skill~/.claude/settings.json里需要这样写{ env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: claude-sonnet-4-20250514 }, skills: { directory: ./skills } }Cline 的 MCP 配置则在cline_mcp_settings.json里{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }三件套对齐Base URL 都是https://taotoken.net/apiKey 都是控制台创建的那串Model ID 都是控制台选的模型。配置片段里的路径和原文一致直接复制改 Key 就能用。4. 端到端验证一次请求跑通 Skill 调用链配置写完后跑一次完整验证。先确认环境变量已加载source .env echo $TAOTOKEN_BASE_URL echo $TAOTOKEN_MODEL然后模拟智能体加载 Skill 的过程。第一步是「发现」阶段智能体只读元数据。你可以用一条请求模拟 LLM 判断是否匹配curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL, messages: [ {role: system, content: 可用技能contract-generator - 专业合同生成器。当用户需要生成销售合同或服务协议时使用此技能。}, {role: user, content: 帮我生成一份销售合同} ], max_tokens: 100 }如果返回里出现contract-generator或类似调用意图说明 L1 发现阶段正常。接着进入「激活」阶段把完整SKILL.md指令加载进上下文再发一次请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL, messages: [ {role: system, content: $(cat contract-generator/SKILL.md)}, {role: user, content: 帮我生成一份销售合同甲方是A公司乙方是B公司金额10万元签署日期2025-06-01} ], max_tokens: 500 }预期结果是 LLM 输出结构化操作请求比如选择sales_contract_template.docx列出需要收集的字段并给出运行generate_contract.py的命令。这就是「执行」阶段的起点。最后跑脚本本身python contract-generator/scripts/generate_contract.py \ --template sales_contract_template.docx \ --data 甲方A公司乙方B公司金额10万元签署日期2025-06-01 \ --output ./output/contract.docx成功的话终端会打印抽取的字段 JSON 和输出路径。如果output/contract.docx生成整条链路就通了TaoToken 提供模型推理Skill 提供编排逻辑脚本负责落地执行。验证时注意看返回的usage字段L1 阶段 token 消耗应该很小几十到一百L2 阶段会明显上升因为加载了完整指令L3 阶段取决于脚本返回内容。这个 token 曲线就是渐进式披露的直接证据。5. 常见报错排查401、local proxy failed 与 choices 读取失败接入过程中最容易撞上的几类报错逐个拆解。401 Unauthorized。返回体通常是{error: {message: Invalid API key}}。先检查环境变量有没有真正加载echo $TAOTOKEN_API_KEY看是否为空。如果 Key 是从控制台复制的注意有没有带多余空格或换行。还有一种情况是 Key 被禁用或额度耗尽去控制台「API Keys」页面确认状态。修复方式重新创建 Key更新.env重启终端或重新source。local proxy failed / connection refused。这个报错一般出现在本地智能体框架里比如 Cline 或 Claude Code 启动时。原因通常是 Base URL 填错或者本地网络无法直连。先确认TAOTOKEN_BASE_URL是https://taotoken.net/api没有多余路径。如果框架里有「代理」相关配置项清空它不要填任何本地代理地址。TaoToken 的通道是直连的不需要额外代理层。修复后重启框架进程。reading choices 失败 / KeyError: choices。脚本里resp.json()[choices]报 KeyError说明返回体结构不对。先打印原始返回print(resp.text)。常见原因是请求体里model字段为空或者messages格式不对。还有一种情况是response_format设了json_object但模型不支持返回了错误信息。修复方式确认TAOTOKEN_MODEL有值messages是列表且每项有role和content去掉不支持的参数再试。OAuth 相关报错。如果你用 Claude Code 且看到 OAuth 字样说明它还在走默认的 Anthropic 认证流程。需要在settings.json的env里显式覆盖ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY指向 TaoToken 的地址和 Key。有些版本还需要设ANTHROPIC_AUTH_TOKEN。改完重启 Claude Code再跑一次验证请求。Skill 未被触发。用户输入后 LLM 没有选择 Skill先检查SKILL.md的description是否足够具体。描述太泛比如「处理文档」会导致匹配失败。改成「当用户需要生成销售合同或服务协议时使用此技能」这种带触发条件的描述。另外确认元数据 YAML 格式正确---分隔符不能少name和description不能缺。脚本执行权限问题。bash scripts/export_to_pdf.sh报 Permission denied先chmod x scripts/export_to_pdf.sh。如果是 Windows 环境用 Git Bash 或 WSL 跑别用 CMD。排查顺序建议先 curl 验证通道再验证 Skill 元数据匹配最后验证脚本执行。每一层单独确认别跳步。6. 把 Skill 接进你的 LLM 应用下一步怎么走最小闭环跑通后你可以把 Skill 目录挂到自己的智能体框架里。如果是自研 Agent在初始化阶段扫描skills/目录读每个SKILL.md的 frontmatter 拼成元数据列表塞进系统提示词。用户输入后先让 LLM 做一次「技能选择」命中后再加载完整指令。执行阶段解析 LLM 输出的结构化请求调用对应脚本或工具把结果回填上下文。TaoToken 在这里的价值是统一通道。你的 Skill 脚本、智能体框架、验证请求都走同一个 Base URL 和 Key换模型只改TAOTOKEN_MODEL一个变量。模型对话页面可以快速试不同模型对同一 Skill 的匹配效果接入文档里有完整的参数说明和示例。如果你要长期跑编码类 AgentCoding Plan 提供了更稳定的配额和通道。下一步可以做的把references/里的条款库换成你自己的业务文档把scripts/里的生成逻辑换成真实模板引擎把assets/里的模板换成公司实际合同。Skill 的目录结构不变只换内容智能体的加载逻辑完全不用改。这就是「平台提供执行引擎用户提供执行剧本」的实际含义。最后留一个实用技巧给每个 Skill 写一个test_input.txt放一条典型用户输入配合 curl 做回归测试。每次改完SKILL.md跑一遍确认元数据匹配和指令加载都正常。这个习惯能帮你省下大量调试时间。