用 TaoToken 统一 Key 跑通模拟 Claude Code Skills 机制的 demo 代码-平芜编程栈

1. 为什么我要用一份 demo 复刻 Claude Code 的 Skills 机制

Claude Code 的 Skills 机制，简单说就是：把「一类任务怎么做」写成一份可被运行时读取的描述文件，模型在收到用户输入后，先判断该不该用某个技能，再按技能里写好的执行方式去跑脚本或调工具。它解决的核心问题是——不用把几十个工具函数硬编码进主流程，而是让技能以文件形式独立存在，按需加载、按需触发。

这套机制适合谁？适合正在做 Agent 工具编排、想让本地脚本被大模型「自动挑出来执行」的开发者；也适合想理解 Claude Code 内部路由逻辑、但不想一上来就啃源码的人。我这次的做法是：用一份本地 Node/Python 可跑的 demo，把「技能描述文件 → 关键词路由 → 执行 → Trace 记录」这条链路完整走一遍，并且用 TaoToken 统一 Key 来接管模型调用，这样本地脚本和线上模型走的是同一套凭证，不用在多个平台之间来回切。

热词里提到的 Clade Code、Skills、demo、代码，本质都指向同一件事：把技能定义和执行解耦。下面我会先给目录结构，再给技能 JSON 配置，然后是可复制的运行命令，最后演示新增一个技能后怎么验证它被正确触发。全程你都可以跟着敲。

2. TaoToken 前置准备：统一 Key 与模型接入

在跑 demo 之前，先把模型调用这条线理顺。TaoToken 在这里扮演的角色是「统一入口」：你只需要一个 Key，就能在本地脚本里调用模型对话能力，不用为每个模型单独配一套鉴权。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

第一步，拿到 Key。进入控制台的 API Keys 页面创建：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。创建后复制那串以 sk- 开头的字符串，后面所有配置都用它。

第二步，确认你要用的模型 ID。demo 里我会用一个通用对话模型来做意图路由判断，你可以在模型对话页面先试一下：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。把模型 ID 记下来，比如常见的对话模型 ID，填到后面的配置里。

第三步，理解 Base URL 的写法。TaoToken 的 API 根地址是 https://taotoken.net/api ，在 OpenAI 兼容的 SDK 里，通常需要写成 https://taotoken.net/api/v1 这种形式（具体以接入文档为准）。接入文档在这里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。如果你用的是 Claude Code 这类工具，配置方式略有不同，可以参考 ClaudeCodeAnthropic 的接入说明：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。

这里有个关键点：demo 里的「技能路由」有两种实现方式。一种是纯关键词匹配，不依赖模型，跑起来最快；另一种是让模型读技能描述，判断该用哪个技能。我建议先用关键词版跑通，再切模型版。模型版就需要上面这套 Key 和 Base URL。

如果你打算长期跑编码类 Agent 任务，可以考虑 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它更适合高频调用场景，demo 阶段用按量 Key 就够了。

3. 可复制配置：目录结构、技能 JSON 与运行命令

这一节是全文最核心的部分，所有片段都可以直接复制。先给目录结构：

mini_skills_runtime/ ├── skills_runtime/ │ ├── __init__.py │ ├── models.py # 数据模型 │ ├── loader.py # 技能加载器 │ ├── router.py # 技能路由器 │ ├── executor.py # 技能执行器 │ ├── trace.py # Trace 管理器 │ └── metrics.py # 指标聚合 ├── skills/ │ ├── dir_filetype_stats/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── count_filetypes.sh │ └── add_filename_prefix/ │ ├── SKILL.md │ └── scripts/ │ └── add_prefix.py ├── demo.py ├── requirements.txt └── .env

技能描述文件我用 JSON 和 Markdown 两种形式都支持。先看 JSON 版，放在 skills/dir_filetype_stats/skill.json：

{ "name": "dir_filetype_stats", "description": "统计指定目录下各类型文件的数量", "when_to_use": "用户要求统计目录文件类型分布时", "when_not_to_use": "用户只是询问单个文件信息时", "keywords": ["统计", "文件类型", "目录", "filetype", "stats"], "inputs": { "dir": { "type": "string", "required": true, "description": "目标目录路径" } }, "outputs": { "result": { "type": "string", "description": "各类型文件数量统计" } }, "execution": { "type": "shell", "entry": "scripts/count_filetypes.sh" }, "safety": { "side_effects": "none", "requires_confirmation": false } }

对应的 SKILL.md 版本（两者选一即可，loader 会优先读 JSON）：

# Skill: dir_filetype_stats ## Description 统计指定目录下各类型文件的数量 ## When to Use 用户要求统计目录文件类型分布时 ## When NOT to Use 用户只是询问单个文件信息时 ## Inputs - dir: 目标目录路径 ## Outputs - result: 各类型文件数量统计 ## Execution - type: shell - entry: scripts/count_filetypes.sh ## Safety - side_effects: none - requires_confirmation: false

Shell 脚本 scripts/count_filetypes.sh：

#!/usr/bin/env bash set -euo pipefail TARGET_DIR="${1:-.}" find "$TARGET_DIR" -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn

Python 技能 add_filename_prefix 的 skill.json：

{ "name": "add_filename_prefix", "description": "给目录下所有文件添加统一前缀", "keywords": ["前缀", "重命名", "prefix", "rename"], "inputs": { "dir": { "type": "string", "required": true }, "prefix": { "type": "string", "required": true } }, "execution": { "type": "python", "entry": "scripts/add_prefix.py" }, "safety": { "side_effects": "filesystem", "requires_confirmation": true } }

.env 文件，把 Key 和 Base URL 放进去：

TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api/v1 TAOTOKEN_MODEL=你的模型ID

requirements.txt：

openai>=1.0.0 python-dotenv>=1.0.0

安装依赖并运行：

pip install -r requirements.txt python demo.py --input "帮我统计当前目录的文件类型"

运行后你会看到：loader 扫描 skills 目录，router 根据关键词命中 dir_filetype_stats，executor 调用 shell 脚本，trace 记录每一步状态，metrics 输出延迟和成功率。

4. 验证请求与成功结果：新增技能如何被正确触发

跑通基础 demo 后，重点来了：新增一个技能，验证它是否被正确路由。我加一个「统计代码行数」的技能，目录结构：

skills/count_lines/ ├── skill.json └── scripts/ └── count_lines.py

skill.json：

{ "name": "count_lines", "description": "统计目录下代码文件的总行数", "keywords": ["行数", "代码行", "lines", "loc"], "inputs": { "dir": { "type": "string", "required": true } }, "execution": { "type": "python", "entry": "scripts/count_lines.py" }, "safety": { "side_effects": "none", "requires_confirmation": false } }

count_lines.py：

import sys from pathlib import Path target = Path(sys.argv[1] if len(sys.argv) > 1 else ".") exts = {".py", ".js", ".ts", ".go", ".java"} total = 0 for f in target.rglob("*"): if f.suffix in exts and f.is_file(): total += sum(1 for _ in f.open(encoding="utf-8", errors="ignore")) print(f"total lines: {total}")

重新运行：

python demo.py --input "统计一下这个项目的代码行数"

预期输出里应该出现routed to: count_lines，然后打印总行数。如果路由没命中，检查 keywords 是否和输入有交集。我实测下来，关键词匹配对中文分词比较敏感，建议把「行数」「代码行」都写进 keywords。

如果你想用模型来做路由判断，把 demo.py 里的 router 换成 LLM 版：

from openai import OpenAI import os client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) def llm_route(user_input, skills): desc = "\n".join(f"- {s['name']}: {s['description']}" for s in skills) resp = client.chat.completions.create( model=os.getenv("TAOTOKEN_MODEL"), messages=[ {"role": "system", "content": f"根据用户输入选择最合适的技能，只返回技能名。\n{desc}"}, {"role": "user", "content": user_input}, ], ) return resp.choices[0].message.content.strip()

这段代码里，resp.choices[0]就是模型返回结果，如果报reading 'choices'相关错误，通常是返回体结构不对，检查 base_url 是否带了 /v1。

5. 本篇常见错排查：401、local proxy failed 与 OAuth

跑 demo 时最容易撞上的几类报错，我按真实遇到的顺序列一下。

第一类，401 Unauthorized。原因通常是 Key 没读到，或者 .env 没被加载。检查两点：一是python-dotenv是否在代码开头调用了load_dotenv()；二是 Key 有没有多余空格。如果你用的是 Claude Code 类工具，401 也可能是 OAuth 凭证过期，需要重新走一遍授权流程，参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 里的说明。

第二类，local proxy failed。这个报错一般出现在你本地配了某个转发层，但转发层没起来，或者端口对不上。demo 里如果直接用 TaoToken 的 Base URL，是不需要本地转发的，把配置里多余的 proxy 字段删掉即可。

第三类，reading 'choices'或Cannot read properties of undefined。这是返回体解析问题，多半是 base_url 写成了https://taotoken.net/api而没加/v1，导致请求打到了非兼容端点。改成https://taotoken.net/api/v1再试。

第四类，技能没被触发。先看 loader 有没有把新技能加载进来，打印一下skills.keys()。如果技能在，但路由没命中，就是 keywords 覆盖不够。如果技能不在，检查 skill.json 是否放在技能目录根下，文件名是否拼错。

第五类，shell 脚本权限问题。count_filetypes.sh需要可执行权限，跑chmod +x scripts/count_filetypes.sh。Windows 下建议直接用 Python 版技能，避免 shell 兼容问题。

第六类，模型返回空。检查模型 ID 是否填对，以及该模型是否在你的账号权限范围内。可以在模型对话页面先手动发一条消息验证：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。

排障时建议把 trace 级别调到 DEBUG，这样每一步的状态转换、输入参数、返回摘要都会打出来，定位问题比看最终报错快得多。

6. 把 demo 用起来：从验证到长期编码

demo 跑通之后，你可以做三件事让它真正有用。第一，把技能目录挂到你的实际项目里，让 loader 扫描真实脚本，这样模型就能调用你已有的工具。第二，把关键词路由逐步替换成模型路由，命中率会明显提升，尤其是用户输入比较口语化的时候。第三，把 trace 和 metrics 接到你的日志系统，长期观察哪些技能被调用最多、哪些经常失败。

如果你打算把这套机制用在日常编码或 Agent 任务上，Coding Plan 会比按量 Key 更省心：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它适合高频、长时间的调用场景。

最后给一个实用技巧：技能描述里的when_not_to_use别偷懒，写清楚反而能减少误触发。我试过把「不要用于单个文件」写进去之后，路由准确率提升很明显。另外，新增技能后不用重启整个 runtime，loader 支持运行时重新扫描，改完 skill.json 直接再跑一次输入就行。