1. 从零写一个 Agent SkillSKILL.md 元数据到底怎么填Agent Skills 是给智能体加装「专业技能包」的轻量格式核心就是一个带SKILL.md的文件夹。它解决的问题很具体模型本身很聪明但不知道你团队的代码规范、不知道你司内部 API 怎么调、不知道某个报表的字段含义。技能就是把这些「程序性知识」按需喂给智能体。它适合三类人想让 Claude Code、Cursor 这类编码智能体记住自己项目套路的开发者想把团队知识封装成可版本控制知识包的工程团队以及想一次构建、多端复用的技能作者。你不需要改模型也不需要写复杂的插件协议只要会写 Markdown 加一点脚本就能让智能体识别并调用你的技能。我先把最容易踩坑的地方说清楚SKILL.md顶部的 YAML 前置元数据不是装饰它是智能体「发现」技能的唯一依据。启动时智能体只读name和description判断这个任务要不要激活这个技能。所以description写得好不好直接决定技能会不会被调用。很多人技能写完发现「智能体根本不用」九成是 description 太笼统。一个最小可用的技能目录长这样my-skill/ ├── SKILL.md # 必需元数据 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考资料 └── assets/ # 可选模板、资源文件SKILL.md的骨架--- name: pdf-processing description: 从 PDF 提取文本和表格填写表单合并文档。当用户需要处理 PDF 文件时使用。 --- # PDF Processing ## 什么时候用 用户提到 PDF、表单填写、文档合并时…… ## 怎么提取文本 1. 用 pdfplumber 打开文件……元数据字段里name和description必填其余可选。name规则很严1–64 字符只能小写字母、数字、连字符不能以连字符开头或结尾不能有连续连字符而且必须和父目录名一致。PDF-Processing、-pdf、pdf--processing都是无效的。description上限 1024 字符要写清「做什么」和「什么时候用」最好埋进用户可能说的关键词。可选字段里license写许可证名或路径compatibility写环境要求Python 版本、系统依赖metadata是任意键值对作者、版本allowed-tools是实验性的预批准工具列表空格分隔。这些字段智能体不一定全用但对团队协作和版本管理很有价值。技能的工作机制叫「渐进式披露」发现阶段只加载 name 和 description任务匹配时把完整SKILL.md读进上下文执行阶段按指令干活需要时才加载引用文件或跑脚本。这个设计让上下文不被一次性塞满响应也快。理解这一点你就知道为什么指令要分层写——高频步骤放正文长参考资料放references/。2. TaoToken 前置给技能接一个稳定的模型入口技能本身不产生智能它需要挂在一个能读SKILL.md的智能体上。我实测下来用 TaoToken 做统一入口比较省事一个 Key 就能在多个兼容智能体产品之间切换技能包不用改。TaoToken 的定位是模型调用入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它兼容 Anthropic 和 OpenAI 两种协议风格所以 Claude Code、Cline、Codex 这类工具都能接。先拿 Key。进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个复制出来。这个 Key 后面要填进各个工具的配置里。如果你只是想先验证模型通不通可以用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接发一条消息确认 Key 有效、额度正常。这一步能帮你排除掉后面「到底是技能写错了还是 Key 没配好」的扯皮。对于长期写代码、跑 Agent 的场景Coding Plan 更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。技能开发本身是个反复调试的过程会频繁触发模型调用用套餐比按量更可控。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各工具的完整配置示例。Claude Code 的接入说明单独放在 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 如果你用 Claude Code 跑技能直接看这个。这里要强调一个概念TaoToken 是模型调用入口不是编辑器也不是技能运行时。技能的执行者是智能体本身TaoToken 负责把请求送到模型。两者职责分清排障时就不会乱。3. 可复制配置SKILL.md 模板 脚本挂载 工具接入这一节给你能直接抄的东西。先写一个真实可用的技能查天气。目录结构weather-skill/ ├── SKILL.md └── scripts/ └── weather.pySKILL.md全文--- name: weather-skill description: 通过高德地图 API 查询指定城市的实时天气包括温度、天气状况、风力风向、湿度。当用户询问某城市天气、气温、是否下雨时使用。 license: Apache-2.0 compatibility: Python 3.8, 需要 requests 库需要网络访问 metadata: author: your-name version: 1.0.0 --- # 城市天气查询技能 ## 功能描述 查询指定城市的实时天气信息。 ## 使用方式 用户直接描述要查的天气例如 - 北京天气怎么样 - 上海今天多少度 ## 环境变量 使用前设置高德 API Key bash export AMAP_MAPS_API_KEYyour_api_key安装依赖pip install requests调用脚本python scripts/weather.py 北京输出格式城市、天气、温度、风力、湿度、发布时间。注意 name 是 weather-skill和父目录名一致。description 里埋了「天气、气温、是否下雨」这些用户可能说的词。 脚本 scripts/weather.py python #!/usr/bin/env python3 城市天气查询 - 使用高德 API import os import sys import requests def get_city_code(city_name: str, api_key: str): url https://restapi.amap.com/v3/config/district params {key: api_key, keywords: city_name, subdistrict: 0} resp requests.get(url, paramsparams, timeout5) resp.raise_for_status() data resp.json() if data.get(status) 1 and data.get(districts): return data[districts][0][adcode] return None def query_weather(city_code: str, api_key: str): url https://restapi.amap.com/v3/weather/weatherInfo params {key: api_key, city: city_code, extensions: base} resp requests.get(url, paramsparams, timeout5) resp.raise_for_status() data resp.json() if data.get(status) 1 and data.get(lives): return data[lives][0] return None def main(): if len(sys.argv) 2: print(用法python weather.py 城市名) sys.exit(1) city_name sys.argv[1] api_key os.environ.get(AMAP_MAPS_API_KEY) if not api_key: print(错误请设置环境变量 AMAP_MAPS_API_KEY) sys.exit(1) city_code get_city_code(city_name, api_key) if not city_code: print(f未找到城市{city_name}) sys.exit(1) weather query_weather(city_code, api_key) if not weather: print(f无法获取 {city_name} 的天气) sys.exit(1) print(f{weather[city]}天气{weather[weather]}) print(f温度{weather[temperature]}°C) print(f风力{weather[windpower]} {weather[winddirection]}风) print(f湿度{weather[humidity]}%) print(f发布时间{weather[reporttime]}) if __name__ __main__: main()脚本接口设计的关键让智能体能从SKILL.md里知道怎么调用、传什么参数。所以指令里必须写清python scripts/weather.py 北京这种调用形式。接下来把技能挂到智能体上。以 Claude Code 为例配置文件在~/.claude/settings.json接入 TaoToken 的片段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }三件套齐了Base URL、Key、Model ID。技能目录放到 Claude Code 能扫描的位置通常是项目下的.claude/skills/或用户级技能目录它启动时会读每个技能的 name 和 description。如果你用 Cline配置走 MCP 或自定义 provider同样填 Base URL、Key、Model ID 三项。Codex 则写进auth.json{ OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: 你的_TaoToken_Key, model: gpt-4o }不同工具字段名不一样但本质都是这三样。填错任何一项技能都不会被激活。4. 验证请求本地加载一次看技能是否被识别写完不等于能用必须验证。分两步先单独跑脚本再让智能体加载技能。第一步本地跑脚本确认逻辑没问题export AMAP_MAPS_API_KEY你的高德Key python scripts/weather.py 北京期望输出北京天气晴 温度15°C 风力3 北风 湿度45% 发布时间2026-03-03 10:00:00如果这一步就报错别急着怪智能体先把脚本调通。常见的是 Key 没设、requests 没装、城市名查不到 adcode。第二步验证智能体能否发现技能。启动 Claude Code问一句「北京天气怎么样」。观察它的行为如果技能被正确加载它会先读SKILL.md然后按指令调用scripts/weather.py 北京最后把结果整理给你。如果它直接瞎编一个天气说明技能没被识别。你也可以主动触发技能列表。在 Claude Code 里输入/skills或类似命令不同版本命令名可能不同看weather-skill在不在列表里。不在的话检查三件事目录名和name是否一致、SKILL.md是否在技能根目录、YAML 前置元数据格式是否正确---必须顶格。验证模型入口是否通可以单独发一条请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的_TaoToken_Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 100, messages: [{role: user, content: 说一句话证明你在}] }返回里有content字段就说明入口通了。这一步能把「模型不通」和「技能没加载」两个问题分开。实测下来技能加载失败最常见的原因是 description 写得太泛比如只写「处理文档」。智能体判断不出什么时候该用就永远不激活。把使用场景和关键词写进去命中率会明显提升。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障时先看报错别猜。下面几个是我踩过的坑。401 Unauthorized。九成是 Key 问题。检查ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY有没有填错、有没有多余空格、Key 是不是被删了。如果用的是 Claude Code注意它读的是ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY填错字段名会直接 401。去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个对比。local proxy failed。这个报错通常出现在工具试图走本地代理但代理没起来。检查你的配置里有没有残留的HTTP_PROXY、HTTPS_PROXY环境变量或者工具自带的代理开关。清掉这些让请求直连 Base URL。另外确认 Base URL 写的是https://taotoken.net/api不要多加路径。reading choices 相关报错。这类多半是响应格式和工具预期不匹配。比如工具按 OpenAI 格式解析但你填的模型走的是 Anthropic 协议。检查 Model ID 和协议是否配套Claude 系列走 Anthropic 格式GPT 系列走 OpenAI 格式。混用会解析失败。OAuth 报错。有些工具默认走 OAuth 登录流程但你用的是 API Key 模式。在配置里关掉 OAuth 或选择 API Key 认证方式。Claude Code 如果提示登录检查 settings.json 里的 env 是否生效必要时重启终端。技能不被调用。不是报错但很烦。按顺序查name和目录名是否一致description是否包含用户会说的关键词SKILL.md是否在技能根目录YAML 前置元数据是否被正确解析用---包裹顶格写。还有一个隐蔽问题技能目录层级放错了工具扫描不到。确认你放的是工具文档里指定的技能目录。脚本执行失败。智能体调用脚本时报「command not found」或权限错误。检查脚本有没有执行权限chmod x scripts/weather.py以及SKILL.md里写的调用路径是否和实际一致。相对路径是相对技能根目录不是相对当前工作目录。排障时建议开工具的详细日志能看到它到底加载了哪些技能、发了什么请求。日志里搜技能名能快速定位是发现阶段还是执行阶段出的问题。6. 语义一致 CTA把技能接进你的工作流技能写完之后真正的价值在于它被反复调用。如果你主要做编码和 Agent 任务建议用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 技能调试会频繁触发模型套餐更稳。需要新建或轮换 Key去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。各工具的完整接入步骤看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 用户直接看 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。想先验证模型响应用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条就行。最后给个实用建议技能不要一次写太大。一个技能解决一类任务description 精准脚本接口清晰。我见过有人把所有内部工具塞进一个技能结果智能体判断不出什么时候用反而一个都不触发。拆小、写准、勤验证比堆功能有用得多。