1. 从一次“重复教学”说起：Skills 到底解决什么问题
如果你刚开始接触 AI Agent，大概率遇到过这种场景：你花十分钟跟模型讲清楚“函数命名用驼峰、异常要统一包装、日志必须带 traceId”，它这次写得挺规范；换个新会话，同样的要求又得从头说一遍。更麻烦的是，团队里十个人可能写出十种风格的指令，Agent 的输出质量完全靠运气。
这就是 AI Agent 中 Skills 要解决的核心问题。Skills 可以理解成给 Agent 写的一份“操作手册”，本质是一份结构化的指令文件。当 Agent 碰到某类任务时，就去读对应的 Skill，按里面的步骤一步步执行，不用每次从头教它。它和 Prompt 的区别在于：Prompt 是你临时说的话，Skill 是固化下来、可复用、可版本管理的规范。它和 RAG 的区别在于：RAG 检索的是知识片段，目的是让模型“基于资料回答问题”；Skill 加载的是操作指令，目的是让模型“按固定流程执行任务”。一句话概括，RAG 给 AI 喂资料，Skill 给 AI 定规矩。
这篇面向刚接触 AI Agent 的开发者，从 Skills 与 Prompt、RAG 的区别切入，说明 Skills 在工具调用与任务编排中的定位，然后给出可复制的settings.json骨架与 TaoToken 统一 Key 配置，最后附一次最小调用验证步骤，帮你把第一个 Skill 真正跑起来。
2. 前置准备：用 TaoToken 统一 Key 管住你的 Agent 调用
在写 Skill 之前，先把“调用通道”理顺。做 Agent 项目时最烦的一件事是：不同模型、不同工具、不同脚本各配一套 Key，环境变量散落各处，换台机器就要重新配一遍。我的做法是用 TaoToken 做统一入口，一个 Key 打通模型对话和后续的 Agent 调用。
TaoToken 的定位是统一的模型调用入口，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个地址不加 UTM 参数，直接用于代码里的 base_url）。
你需要先拿到 Key。进入控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建后复制保存，后面所有配置都用它。如果你只是想先验证模型能不能通，可以打开模型对话页面直接试一句： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。
这里有个关键点：Skill 本身不负责“怎么连模型”，它只负责“连上之后怎么干活”。所以把 Key 和 base_url 统一好，Skill 才能专注在流程编排上。对于长期做编码类 Agent 的读者，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要持续调用、反复迭代 Skill 的场景。
3. 可复制配置：settings.json 骨架与 Skill 文件结构
3.1 settings.json 骨架
下面这份settings.json是我在 Agent 项目里常用的骨架，把模型入口、Key、Skill 目录都集中管理。你可以直接复制，把YOUR_TAOTOKEN_API_KEY换成上一步拿到的 Key。
{ "llm": { "provider": "taotoken", "base_url": "https://taotoken.net/api", "api_key": "YOUR_TAOTOKEN_API_KEY", "model": "claude-sonnet-4-5", "max_tokens": 4096, "temperature": 0.2 }, "agent": { "system_prompt_file": "./prompts/system.md", "skill_dir": "./skills", "max_skill_load": 2, "skill_match_mode": "semantic" }, "tools": { "enabled": ["read_file", "write_file", "run_shell"], "timeout_ms": 30000 } }几个参数说明一下。base_url固定填 TaoToken 的 API 地址，不要带 UTM 后缀。max_skill_load控制一次最多加载几个 Skill，设成 2 是为了避免上下文被撑满。skill_match_mode可以是keyword或semantic，前者靠关键词规则匹配，后者靠语义检索，小项目用 keyword 就够。
3.2 一个最小 Skill 文件
Skill 文件用 Markdown 写，放在./skills目录下。下面这个create-rule.md是“创建自定义规则文件”的 Skill，包含触发条件、操作步骤、输入输出规范、注意事项四个部分。
# Skill: create-rule ## 触发条件 当用户要求“创建规则文件”“生成项目规范”“新建 .cursorrules”时激活。 ## 操作步骤 1. 确认目标目录，默认为项目根目录。 2. 检查是否已存在同名规则文件，存在则提示覆盖。 3. 按模板生成文件内容，字段包括 name、scope、rules。 4. 写入文件并返回路径。 ## 输入输出 - 输入：{ "target_dir": "string", "rule_name": "string" } - 输出：{ "file_path": "string", "status": "created|overwritten" } ## 注意事项 - 不要写入项目根目录以外的路径。 - 文件内容超过 200 行时拆分为子文件。 - 写入前必须做一次路径合法性校验。这个文件就是一份“操作手册”。Agent 匹配到相关任务时，把这份文件内容注入上下文，模型就按步骤执行，不用你每次重复解释。
4. 验证请求：跑通第一个 Skill 的最小调用
配置写好后，用一段 Python 脚本验证。这段代码做三件事：读取 settings.json、加载 Skill 文件、把 Skill 内容拼进 system prompt 后发起一次请求。
import json import requests with open("settings.json", "r", encoding="utf-8") as f: cfg = json.load(f) llm = cfg["llm"] skill_path = f"{cfg['agent']['skill_dir']}/create-rule.md" with open(skill_path, "r", encoding="utf-8") as f: skill_content = f.read() system_prompt = ( "你是一个 AI Agent。以下是当前任务匹配到的 Skill，请严格按步骤执行：\n\n" + skill_content ) payload = { "model": llm["model"], "max_tokens": llm["max_tokens"], "temperature": llm["temperature"], "messages": [ {"role": "system", "content": system_prompt}, {"role": "user", "content": "帮我在 ./demo 目录创建一个名为 api-style 的规则文件"} ] } resp = requests.post( f"{llm['base_url']}/v1/messages", headers={ "Authorization": f"Bearer {llm['api_key']}", "Content-Type": "application/json" }, json=payload, timeout=60 ) print(resp.status_code) print(resp.json())运行后如果返回 200，并且输出里包含file_path和status字段，说明 Skill 已经被正确加载并驱动模型按流程执行。实测下来，关键不在模型多强，而在 Skill 文件写得够不够明确——步骤编号、输入输出格式、边界条件这三样写清楚，输出稳定性会明显提升。
如果你在验证时想先确认模型本身是否连通，可以回到模型对话页面发一句简单请求： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。确认通道没问题后，再排查 Skill 加载逻辑。
5. 本篇常见错排查
第一个高频错误是 401。多数情况是 Key 没填对，或者Authorization头里漏了Bearer前缀。检查 settings.json 里的api_key字段，确认没有多余空格。
第二个是 404。通常是base_url拼错，比如多加了/v1或者带了 UTM 参数。正确写法就是https://taotoken.net/api，路径部分由代码里的/v1/messages补全。
第三个是 Skill 没生效。表现是模型回答很泛，没按步骤走。原因一般是 Skill 文件路径不对，或者skill_dir配置和实际目录不一致。建议在加载后先打印skill_content的前 200 个字符，确认内容真的读进来了。
第四个是上下文超限。如果 Skill 文件写了好几千 token，再加上对话历史，很容易把窗口撑满。解决办法是控制单个 Skill 长度，把非核心内容拆成子文件按需加载，或者做分层加载——先加载摘要，Agent 判断需要细节时再加载完整版。
第五个是匹配错 Skill。当skill_match_mode设为 semantic 时，语义相近的 Skill 可能被误匹配。可以在 Skill 的触发条件里写更明确的激活信号，或者临时切回 keyword 模式做对比测试。
6. 把 Skill 接进你的 Agent 项目
Skill 管的是“怎么想”，Tool 管的是“怎么做”。判断一个任务该用 Skill 还是 Tool，看它是否需要跟外部系统打交道：只是让 AI 按特定流程思考和组织输出，用 Skill 就够；需要查数据库、调 API、操作文件系统，那就得上 Tool。两者经常配合，Skill 里会写明在某一步调用哪个 Tool。
落地第一个 Skill 后，建议把 Key 管理也固定下来。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。如果你用的是 Claude Code 这类编码 Agent，可以参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=ClaudeCodeAnthropic&utm_campaign=rewrite 里的接入方式，把统一 Key 配进去，后续新增 Skill 就不用再动调用层了。
写 Skill 和写 Prompt 一样需要迭代。一个 Skill 只解决一类问题，步骤用编号列表写清楚，输入输出格式明确定义，再附上正确和错误示例，比纯文字描述有效得多。写完不是终点，根据实际使用效果持续优化，才是让 Agent 输出质量可预期的关键。
