1. 从“只会聊天”到“能动手干活”Skills 到底解决了什么问题很多人第一次接触 AI 助手时都会经历一个落差聊起来头头是道真让它干点活就露馅了。你问它“帮我看看项目里哪个文件引用了这个废弃函数”它只能凭训练数据里的印象给你编一段你让它“把这段配置里的超时时间改成 30 秒”它给你一段看起来对但路径完全不对的代码。这不是模型不聪明而是它被关在一个纯文本的盒子里看不见你的文件、连不上你的接口、跑不了你的脚本。Skills技能就是给这个盒子开的一扇门。你可以把它理解成给 AI 助手装的“插件”或者“外挂”模型负责判断“现在该干什么”Skill 负责“真的去干”。搜索网页、读取本地文件、执行一段 Python、调用一个 HTTP 接口、往数据库里写一条记录这些都属于 Skill 的范畴。它和 OpenAI Function Calling 说的是同一件事的两面——Function Calling 是模型侧的“调用协议”Skills 是工程侧的“能力封装”。那它到底适合谁如果你刚接触 AI 助手只会复制粘贴对话Skills 能让你第一次感受到“AI 真的动了我的文件”如果你在写自己的 AI 应用Skills 是你把大模型接进真实业务系统的标准姿势如果你在用 Claude Code 这类编程助手你其实已经在用它内置的 Skills 了只是没意识到。这篇教程就按“先搞懂概念再跑通一个自定义 Skill最后用统一 Key 验证调用”的顺序走一遍代码和配置都能直接复制。需要先明确一个边界Skills 不是让模型变聪明而是让模型有“手”。模型依然可能判断错该调哪个 Skill所以输入校验、权限最小化、超时处理这些工程细节才是决定你的 Skill 能不能上生产的关键。下面从概念到落地一步步拆。2. 前置准备用 TaoToken 统一 Key 打通 Skill 的调用链路在写第一个 Skill 之前得先解决一个现实问题你的 Skill 后端要调用大模型 API而不同模型的 Key、Base URL、计费方式各不相同。今天用这个模型测 Function Calling明天换那个模型对比效果光是管理 Key 和环境变量就够烦的。我试过把 Key 硬编码在脚本里结果换环境时到处找踩过的坑就是——统一入口比什么都重要。TaoToken 在这里扮演的角色是“统一 API 入口”。它提供兼容 OpenAI 风格的接口你拿一个 Key就能在同一个 Base URL 下调用不同模型Skill 后端不用为每个模型改一遍代码。对刚接触的开发者来说这能省掉大量“配置地狱”的时间。先拿 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时建议给 Key 起个能认出来的名字比如skill-demo-dev方便后面区分测试和生产。拿到 Key 之后记下两个东西Base URL 是https://taotoken.net/api注意这个地址不加 UTM 参数直接用于代码里的base_url以及你的 Key 字符串。接下来所有 Skill 后端调用模型都走这两个值。如果你用的是 Claude Code它本身内置了文件读写、代码搜索、终端执行这些 Skills但模型调用同样需要一个入口。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有 Base URL、Key、Model ID 三件套的完整配置方式。这里先把三件套列清楚后面配置片段会反复用到配置项值说明Base URLhttps://taotoken.net/api兼容 OpenAI 风格的接口根地址API Key控制台创建的 Key形如sk-开头注意保密Model ID按需选择在模型对话页可查看可用模型模型对话页面在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 你可以先在那里手动发一条消息确认 Key 能用、模型能回再去写代码。这一步别跳过很多后面的 401 报错根源就是 Key 没生效或者复制时带了空格。环境变量建议这样设置Linux/macOS 用exportWindows 用setexport TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api把 Key 放环境变量而不是写进代码是为了后面 Skill 注册表能安全地读取。到这里前置准备就完成了一个 Key、一个 Base URL、一个能用的模型。接下来进入真正的 Skill 定义。3. 可复制配置从 JSON Schema 到 Skill 目录结构Skills 的核心是“接口描述 后端实现”。接口描述告诉模型“有这么个能力参数长这样”后端实现负责“真的执行”。这一节给出可以直接复制的 JSON Schema 片段、目录结构以及 Claude Code 的 settings 配置。先看目录结构。一个可维护的 Skill 项目建议这样组织my-skills/ ├── skills/ │ └── get_weather/ │ ├── schema.json # Skill 的接口描述 │ └── handler.py # Skill 的后端实现 ├── registry.py # Skill 注册表 ├── config.toml # 模型调用配置 └── .env # 环境变量不要提交到 gitschema.json就是给模型看的“说明书”。以天气查询为例注意description要写清楚“什么时候该用”模型靠它判断触发时机{ name: get_weather, description: 查询指定城市的当前天气。当用户询问某地天气、温度、是否下雨时调用。, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海、深圳 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认摄氏度 } }, required: [city] } }handler.py是后端实现。注意这里不直接调真实天气 API而是留出接口位置方便你替换import os import requests def get_weather(city: str, unit: str celsius): # 实际项目中替换为真实天气 API api_key os.environ.get(WEATHER_API_KEY, ) url fhttps://api.example.com/v1/weather resp requests.get( url, params{city: city, unit: unit}, headers{Authorization: fBearer {api_key}}, timeout10, ) resp.raise_for_status() return resp.json()config.toml放模型调用配置Base URL 和 Key 从环境变量读Model ID 按需改[model] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_id gpt-4o-mini timeout 30 [skill] schema_dir skills max_retries 2如果你用 Claude Code它的 settings 文件里同样要写全三件套。以项目级.claude/settings.json为例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-3-5-sonnet } }注意ANTHROPIC_BASE_URL后面不要带斜杠也不要带 UTM 参数否则会出现local proxy failed之类的连接错误。Claude Code 的详细接入步骤在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有 OAuth 和 API Key 两种方式的区别按你的场景选。注册表registry.py把 schema 和 handler 绑起来模型返回调用请求时你用它来分发import json import importlib class SkillRegistry: def __init__(self, schema_dirskills): self.schema_dir schema_dir self.skills {} def load(self, name): schema_path f{self.schema_dir}/{name}/schema.json with open(schema_path, r, encodingutf-8) as f: schema json.load(f) module importlib.import_module(f{self.schema_dir}.{name}.handler) func getattr(module, name) self.skills[name] {schema: schema, func: func} def execute(self, name, **kwargs): if name not in self.skills: raise ValueError(fSkill {name} not found) return self.skills[name][func](**kwargs)到这里配置部分就齐了目录结构、schema、handler、config.toml、Claude Code settings、注册表。每一段都能直接复制改掉 Key 和 Model ID 就能跑。下一节验证请求。4. 验证请求跑通第一个自定义 Skill 的完整调用配置写好了得验证它真的能跑。这一节用一个最小可运行的脚本把“模型判断 → 返回调用请求 → 执行 Skill → 结果回注”整条链路走一遍。代码基于 OpenAI 风格的接口Base URL 指向 TaoToken。先装依赖pip install openai requests然后写验证脚本verify_skill.pyimport json import os from openai import OpenAI from registry import SkillRegistry client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api, ) registry SkillRegistry() registry.load(get_weather) tools [registry.skills[get_weather][schema]] messages [ {role: user, content: 北京现在天气怎么样} ] resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto, ) msg resp.choices[0].message print(模型返回:, msg) if msg.tool_calls: call msg.tool_calls[0] args json.loads(call.function.arguments) print(解析参数:, args) result registry.execute(call.function.name, **args) print(Skill 执行结果:, result) else: print(模型没有触发 Skill直接回答:, msg.content)运行python verify_skill.py预期输出分三种情况。第一种模型判断需要调用 Skill你会看到tool_calls里有get_weather参数是{city: 北京}然后 Skill 执行返回一段 JSON。第二种模型觉得不需要调用直接回答这时msg.content有内容。第三种报错。第三种才是重点下一节专门讲。如果一切正常你会看到类似这样的结构模型返回: ChatCompletionMessage(contentNone, tool_calls[...]) 解析参数: {city: 北京} Skill 执行结果: {city: 北京, temp: 22, unit: celsius}注意tool_choiceauto是让模型自己决定要不要调。如果你想强制测试 Skill 链路可以改成tool_choice{type: function, function: {name: get_weather}}这样模型一定会返回调用请求方便你确认解析和执行环节没问题。验证完单次调用建议再测一次多轮把 Skill 结果作为role: tool的消息追加回messages再请求一次模型看它能不能基于结果生成自然语言回答。这一步能暴露“结果格式不对导致模型读不懂”的问题。完整链路跑通说明你的 Skill 从定义到执行都成立了。5. 常见报错排查401、local proxy failed、reading choices 怎么解Skills 跑不通九成问题出在配置和调用格式上。这一节按真实报错对照排查每条都给原因和修法。401 Unauthorized。最常见。原因通常是 Key 没读到、Key 复制时带了空格、或者环境变量名写错。先确认echo $TAOTOKEN_API_KEY有值再确认代码里读的环境变量名和export的一致。如果用的是 Claude Code检查 settings.json 里ANTHROPIC_API_KEY是否写全注意 JSON 里不能有尾逗号。还有一种情况是 Key 被禁用或额度用尽去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看一眼状态。local proxy failed。这个报错多出现在 Claude Code 或本地代理配置场景。原因一般是 Base URL 写错比如多加了斜杠、带了 UTM 参数、或者写成了https://taotoken.net/api/。正确写法是https://taotoken.net/api结尾不带斜杠。另外检查系统里有没有残留的代理环境变量HTTP_PROXY、HTTPS_PROXY它们会拦截请求导致连接失败。清掉再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXYreading choices of undefined。这个报错说明你拿到的响应结构里没有choices字段通常是请求本身失败了但代码没检查状态码。先打印完整响应print(resp)如果resp里是错误信息多半是模型 ID 写错、或者tools参数格式不对。检查model字段是不是控制台里真实存在的 Model ID检查tools里每个元素的type是不是functionfunction下有没有name、description、parameters。少一个字段接口就可能返回非预期结构。OAuth 相关报错。Claude Code 支持 OAuth 和 API Key 两种接入方式如果你混用了会出现认证冲突。用 API Key 方式时确保没有残留的 OAuth token 文件。接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有两种方式的清理步骤按文档走一遍。Skill 没被触发。不是报错但很常见。模型没调 Skill通常是description写得太模糊。把“查询天气”改成“当用户询问某地天气、温度、是否下雨时调用”触发率会明显上升。另外required字段要准确缺了必填参数模型可能干脆不调。排查顺序建议先确认 Key 和 Base URL再确认模型 ID再确认 tools 格式最后看 description。大部分问题在前两步就能定位。6. 从验证到长期使用把 Skill 接进日常编码流单次验证通过只是起点。真正让 Skills 产生价值是把它接进你每天的编码流程里。如果你主要用 Claude Code 做开发内置的文件操作、代码搜索、终端执行这些 Skills 已经能覆盖大量场景你只需要把模型调用入口配好就能在对话里直接让它改文件、跑测试、查 diff。Claude Code 的接入和配置在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按文档把三件套写进 settings 即可。如果你要长期跑编码任务或者 Agent 类工作流调用量会明显上升这时候可以看看 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合持续性的编码场景。日常想快速验证某个模型对 Skill 的触发效果用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 手动试几条 prompt 就够了不用每次都写脚本。最后给几个实用习惯。第一Skill 的description当成 prompt 来写它直接决定触发准确率。第二handler 里一定要加timeout外部接口卡住会拖垮整个对话。第三敏感操作比如删文件、发请求先让模型返回调用请求、你确认后再执行别让它自动跑。第四把每次调用的输入输出记下来出问题时这是唯一的线索。Skills 的本质是给模型装手手稳不稳取决于你这些工程细节做没做到位。