1. 从一次“技能不触发”的翻车说起：AIGC 场景下 skills 到底是什么

你可能已经用过不少 Agent 工具，也见过别人把一堆提示词塞进系统消息里，结果模型该调用工具的时候不调用，该走流程的时候自由发挥。我最近在做一个数据分析类的 Agent 项目时就遇到这个问题：明明写了一段“处理 CSV 文件”的说明，用户说“帮我把这份销售表按地区汇总一下”，Agent 却直接开始手写 Python 代码，完全没走我预设的流程。后来排查发现，问题不在模型能力，而在于我根本没有用对 skills 这套机制。

skills 是 AIGC 时代给 Agent 扩展专业能力的一种轻量开放格式。你可以把它理解成“给 Agent 装的一个技能包”：一个文件夹，里面必须有一个SKILL.md，可选再放脚本、参考资料和资源文件。Agent 启动时只加载每个技能的名称和描述，判断当前任务是否相关；一旦匹配，才把完整的SKILL.md指令加载进来执行。这个机制叫渐进式披露（Progressive Disclosure），好处是既省上下文，又能按需调用。

它适合谁？如果你正在用 Claude Code、Cursor、VS Code Copilot Agent 模式、OpenAI Codex 这类支持 skills 的工具，或者你在团队里想把“某类任务的正确做法”沉淀成可版本控制的知识资产，那这套东西就非常值得掌握。本文会从零拆解SKILL.md的结构、description的撰写要点，给出可复制的模板和示例，并演示一次技能注册与触发验证的完整动作。核心检索词就三个：skills、SKILL.md、description，记住这三个，后面所有内容都围绕它们展开。

很多人第一次写 skills 会犯一个错：把SKILL.md当成一篇技术文档来写，恨不得把领域知识全塞进去。结果就是文件超过 500 行，Agent 加载慢、触发率还低。正确的思路是把它当成“给一个聪明但没做过这件事的新同事的操作手册”——只写模型不知道的、容易做错的、必须按顺序来的东西。下面我们先把前置环境和工具准备好，再进入可复制的配置环节。

2. 前置准备：TaoToken 接入与 skills 运行环境搭建

在真正写SKILL.md之前，你需要一个能稳定调用模型的入口，以及一个支持 skills 的 Agent 运行环境。我实测下来，用 TaoToken 作为模型接入层比较省心，它兼容 OpenAI 风格的接口，配置简单，适合用来做技能触发验证。下面把接入步骤和 skills 目录规范一起讲清楚。

2.1 TaoToken 接入配置

TaoToken 的 API 地址是https://taotoken.net/api，你需要在控制台创建一个 API Key。创建路径是：登录后进入控制台，找到 API Keys 页面，新建一个 Key 并复制保存。这个 Key 后面会用在环境变量里，不要直接写进代码提交到仓库。

配置方式有两种，选你顺手的一种即可。第一种是环境变量，适合本地开发和脚本调用：

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

第二种是写进工具的配置文件。如果你用的是 Claude Code 这类工具，通常会在项目根目录或用户目录下有一个 settings 文件。以常见的settings.json为例，配置片段如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key" } }

注意这里的 Base URL 和 Key 要成对出现，Model ID 根据你实际使用的模型填写，比如claude-sonnet-4-20250514这类标识。三件套（Base URL + Key + Model ID）缺一不可，少一个就会出现 401 或模型找不到的报错。

2.2 skills 目录规范

skills 的默认存放路径是项目根目录下的.agents/skills/<skill-name>/SKILL.md。也就是说，每个技能一个文件夹，文件夹名必须和SKILL.md里的name字段完全一致。这一点非常关键，后面排错时会反复用到。

一个完整的技能目录结构长这样：

.agents/ └── skills/ └── csv-analysis/ ├── SKILL.md # 必须，指令 + 元数据 ├── scripts/ # 可选，可执行代码 │ └── summarize.py ├── references/ # 可选，详细文档 │ └── REFERENCE.md └── assets/ # 可选，模板和资源 └── report-template.md

SKILL.md是唯一必须存在的文件，其余目录按需添加。scripts 放可执行代码，references 放详细技术参考，assets 放模板、图表、数据对照表等静态资源。记住一个原则：主SKILL.md保持在 500 行以内，详细内容拆到 references 里，用相对路径引用。

2.3 验证环境是否就绪

配置完成后，先用一个最简单的请求确认模型能通。你可以用 curl 测试：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回里有正常的choices内容，说明接入层没问题。如果报 401，检查 Key 是否复制完整；如果报模型不存在，检查 Model ID 拼写。这一步过了，再进入 skills 的编写，否则后面触发失败你分不清是模型问题还是技能问题。

3. 可复制配置：SKILL.md 模板与 description 撰写要点

这一节是全文的核心，我会给出一个可以直接复制使用的SKILL.md模板，并逐字段说明description怎么写才能让 Agent 正确触发。你可以把下面的模板保存成.agents/skills/csv-analysis/SKILL.md，然后按自己的场景改。

3.1 完整 SKILL.md 模板

--- name: csv-analysis description: Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use when the user mentions CSV, spreadsheet, tabular data, data cleaning, or asks to summarize/aggregate a data file. license: MIT compatibility: Requires Python 3.10+ and uv metadata: author: your-org version: "1.0" allowed-tools: Bash(python:*) Read --- # CSV Analysis ## When to use this skill Use this skill when the user needs to work with CSV or tabular data files: summarizing, aggregating, cleaning, or generating charts. ## How to analyze 1. Read the CSV header and first 5 rows to understand the schema. 2. Identify column types: numeric, categorical, datetime. 3. Run `scripts/summarize.py` with the input file path. 4. Present results as a Markdown table, not raw text. ## Gotchas - Empty strings in numeric columns should be treated as missing, not zero. - Date columns may be in `YYYY/MM/DD` or `YYYY-MM-DD`; normalize before grouping. - The `/health` endpoint is unreliable; use `/ready` for status checks. ## Output template # Report ## Summary ... ## Findings - ... ## Recommendations 1. ...

这个模板里，name必须和文件夹名csv-analysis一致，只能用小写字母、数字和连字符，不能以连字符开头或结尾，也不能有连续连字符。description是最多 1024 字符的必填字段，它决定了技能是否被触发，是整个文件里最需要打磨的部分。

3.2 description 撰写四原则

第一，用命令式开头，比如Use this skill when...，直接告诉 Agent 什么场景该用。第二，面向用户意图，不要写实现细节。用户不会说“我要用 pdfplumber 提取文本”，他会说“帮我把这份 PDF 里的表格弄出来”，所以 description 要覆盖用户的目标表达。第三，稍微“激进”一点，即使用户没有明确说出关键词，只要语义相关也应该触发。第四，保持简洁，控制在 1024 字符以内，把最关键的触发词放在前面。

对比一下好坏示例。差的写法是description: Helps with CSV files.，太泛，Agent 无法判断何时该用。好的写法是description: Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use when the user mentions CSV, spreadsheet, tabular data, data cleaning, or asks to summarize/aggregate a data file.它既说清了功能，又列了触发关键词。

3.3 前置字段约束速查

主体内容是前置内容之后的 Markdown，格式自由，但推荐包含逐步说明、输入输出示例、常见边缘情况。Agent 激活技能时会加载整个文件，所以长内容要拆到 references 里，用相对路径引用，比如See [the reference guide](references/REFERENCE.md) for details.文件引用只保留在SKILL.md下一级，避免深层嵌套。

4. 验证请求：注册技能并触发一次真实调用

写完SKILL.md只是第一步，真正要确认的是 Agent 能不能识别并调用它。这一节我带你走一遍完整的验证流程，包括注册、触发测试和结果确认。

4.1 注册技能

把技能文件夹放到.agents/skills/下，确保目录名和name一致。以 VS Code 的 Copilot Agent 模式为例，打开项目后，在 Chat 面板切换到 Agent 模式，工具会自动扫描.agents/skills/目录。你可以在对话里输入/skills查看已加载的技能列表，如果看到csv-analysis，说明注册成功。

如果你用的是 Claude Code，它会在启动时扫描技能目录，你可以在对话中直接问“你现在有哪些 skills 可用”，模型会列出已发现的技能名称和描述。这一步只加载元数据，不加载完整指令，所以很快。

4.2 触发验证

注册成功后，输入一个应该触发该技能的用户请求，比如：

帮我把这份销售数据按地区汇总一下，文件是 sales.csv

观察 Agent 的行为。如果它先读取 CSV 的头部和样本行，然后调用scripts/summarize.py，最后用 Markdown 表格输出结果，说明技能被正确触发并执行了。如果它直接开始手写代码，说明 description 没有匹配上，需要回去调整触发词。

为了更系统地验证，你可以设计一组 eval query，用 JSON 记录每条查询和预期是否触发：

[ {"query": "把这份 CSV 按地区汇总", "should_trigger": true}, {"query": "帮我清理一下表格里的空值", "should_trigger": true}, {"query": "今天天气怎么样", "should_trigger": false}, {"query": "帮我改一下 Excel 里的公式", "should_trigger": false} ]

正例覆盖不同表达方式：正式、口语、有错别字、显式提到 CSV、隐式说“表格”。负例要选“近似但不该触发”的，比如“改 Excel 公式”和“CSV 导入数据库”就是强负样本，它们和数据处理相关，但不该走这个技能。

4.3 触发率计算

每条查询跑 3 次，统计触发次数，算出 trigger_rate。判断标准是：should_trigger为 true 的，触发率应大于 0.5；为 false 的，触发率应小于 0.5。如果某条正例触发率偏低，就把它的表达方式补进 description；如果某条负例误触发，就在 description 里排除这类场景。

可以用一个简单的 shell 脚本自动化这个过程：

check_triggered() { claude -p "$1" --output-format json | jq -e '.skills_used[]? | select(. == "csv-analysis")' > /dev/null echo $? }

返回 0 表示触发了，返回 1 表示没触发。把 eval query 逐条跑一遍，记录结果，就能得到一份可量化的触发报告。这套方法比凭感觉判断靠谱得多，也是防止 description 过拟合的关键。

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

技能写好了、环境也配了，但实际跑起来还是会遇到各种报错。这一节我把最常见的几类问题和排查路径整理出来，你可以对照自己的报错信息快速定位。

5.1 401 未授权

报错信息通常是401 Unauthorized或invalid api key。原因一般是 Key 没配、配错位置、或者复制时带了空格。排查步骤：先确认环境变量TAOTOKEN_API_KEY是否生效，用echo $TAOTOKEN_API_KEY看输出；再确认配置文件里的 Key 和 Base URL 是否成对；最后检查 Key 是否过期或被删除。如果用的是 Claude Code，注意ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL要同时设置，只设一个会走默认地址导致 401。

5.2 local proxy failed

这个报错通常出现在工具尝试连接本地代理但失败时。排查方向：检查是否有残留的代理环境变量，比如HTTP_PROXY、HTTPS_PROXY，如果有就清掉；确认 Base URL 写的是https://taotoken.net/api而不是带端口号的本地地址；检查网络是否能正常访问该域名。如果工具配置里写了localhost或127.0.0.1，改成正确的 API 地址。

5.3 reading choices 报错

reading 'choices'这类报错一般是响应结构不符合预期，常见于 Base URL 路径写错。比如把https://taotoken.net/api写成了https://taotoken.net/api/v1/chat这种不完整路径，或者多加了斜杠。正确做法是 Base URL 只写到/api，具体路径由工具自己拼接。另外检查 Model ID 是否拼写正确，模型不存在时也可能返回非标准结构。

5.4 OAuth 相关报错

如果你用的是 Claude Code 或 Codex 这类带 OAuth 登录的工具，可能会遇到OAuth token expired或authentication failed。这时候不要混用 OAuth 和 API Key 两种认证方式。用 API Key 接入时，确保没有残留的 OAuth 凭证文件；用 OAuth 时，重新登录刷新 token。两者选其一，不要同时配置。

5.5 技能不触发

如果环境没问题但技能就是不触发，按这个顺序查：第一，确认SKILL.md的name和文件夹名完全一致；第二，确认description里包含了用户可能说的关键词；第三，确认技能目录在.agents/skills/下而不是其他位置；第四，用/skills命令确认技能已被扫描到。如果技能列表里都没有，说明路径或文件名有问题；如果列表里有但不触发，说明 description 需要优化。

6. 语义一致 CTA：把技能沉淀成可复用的团队资产

写到这里，你已经掌握了从零构建一个 skill 的完整路径：理解渐进式披露机制、写好SKILL.md的元数据和主体、用 description 控制触发、通过 eval query 验证触发率、排查常见报错。接下来最重要的一步，是把它变成你日常开发流程的一部分。

我的建议是，每次你在 Agent 上纠正了一个错误、找到了一条更优路径，就把它写进对应技能的 Gotchas 或步骤里。技能不是一次写完就扔的文档，而是随着你踩坑不断迭代的活资产。一个团队如果能把 Code Review 规则、API 调用规范、数据处理流程都沉淀成 skills，新成员接入时就不需要反复问“这个该怎么做”，Agent 会按预设路径执行。

如果你还没有稳定的模型接入层，可以从 TaoToken 的 API Keys 页面创建一个 Key，配合接入文档把 Base URL 和 Model ID 配好，再开始写你的第一个SKILL.md。想先验证模型对话效果，可以直接用模型对话页面测试触发；如果你要长期做编码类 Agent 或复杂工作流，Coding Plan 会更适合持续迭代。把技能目录纳入版本控制，每次优化 description 后跑一遍 eval query，触发率稳定在 0.8 以上，这个技能就算真正可用了。