AIGC 时代从 0 理解并写好 skills：SKILL.md 与 description 的 Agent 落地指南

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_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://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.mdSKILL.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 前置字段约束速查字段必填约束name是1–64 字符小写字母数字和连字符与目录名一致description是1–1024 字符非空说明功能和使用场景license否许可证名称或文件引用compatibility否1–500 字符环境要求metadata否键值映射存额外属性allowed-tools否空格分隔的预批准工具列表实验性主体内容是前置内容之后的 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 以上这个技能就算真正可用了。