1. 为什么你的 Agent 总是“记不住”技能从提示词堆砌到 Agent Skills 工程化很多人做 LLM 应用开发时习惯把所有规则、示例、注意事项全塞进一个超长 system prompt。刚开始跑 demo 没问题一旦任务变多问题就来了上下文被撑爆、模型开始忽略后面的指令、改一处逻辑要翻几百行提示词。我试过在一个客服 Agent 里堆了 3000 字提示词结果它连“退货流程”和“换货流程”都分不清。Agent Skills 就是来解决这个问题的。它本质上是一种按需加载的提示词与资源打包格式平时 Agent 只看到每个技能的名字和一句话描述只有当任务真正匹配时才把完整的 SKILL.md 指令加载进上下文。这样既省 token又让模型注意力集中在当前任务上。你可以把它理解成给 Agent 装“插件”。大模型本身只有三种核心能力输入、输出、触发工具function call。MCP、RAG、Skills 这些都是在 Agent 层围绕这三种能力做的工程封装。Skills 的特别之处在于它足够轻——一个文件夹加一个 SKILL.md 就能跑不需要起服务、不需要写注册代码。适合谁学如果你正在用 Claude Code、Cline、Cursor 这类支持 Agent Skills 的工具或者自己在写 Agent 框架想把零散提示词沉淀成可复用、可版本管理的技能包那这套规范就是为你准备的。下面我会从目录结构、元数据字段、触发条件模板一路写到本地加载和调用验证每一步都能直接复制跟做。2. TaoToken 前置准备给 Agent Skills 一个稳定的模型调用入口Agent Skills 本身是文件格式规范但技能被激活后最终还是要调用大模型来执行指令。如果你用的是 Claude Code 这类工具它需要配置一个兼容 Anthropic 接口的 Base URL 和 API Key。TaoToken 在这里的角色就是提供统一的模型调用入口让你不用分别去对接多家模型厂商。先明确三件套这是后面所有配置的基础配置项值说明Base URLhttps://taotoken.net/api兼容 Anthropic/OpenAI 接口规范API Key在控制台创建形如sk-xxx注意保密Model ID如claude-sonnet-4-20250514按你实际使用的模型填写获取 Key 的步骤很简单打开 TaoToken 控制台登录后在 API Keys 页面点创建复制生成的 Key。这个 Key 后面会写进 Claude Code 的 settings 文件或环境变量里。如果你还没决定用哪个模型可以先去 模型对话 页面试几个确认响应速度和效果符合预期再写进配置。对于长期跑编码类 Agent 的场景Coding Plan 会更划算适合需要频繁调用模型的技能包开发。这里要提醒一点Skills 的 SKILL.md 里写的是“怎么做”模型调用是“谁来做”。两者分开配置技能包才能在不同模型之间迁移。你完全可以把同一个技能包用在 Claude Code 和 Cline 上只要它们都支持 Agent Skills 格式。配置完成后建议先用一个最小请求验证连通性再往下写技能。验证方法在第四节会详细展开。3. SKILL.md 目录结构与元数据字段可复制的配置模板这一节是核心。Agent Skills 的规范其实很简洁但字段限制和目录约定必须严格遵守否则工具扫描时可能直接忽略你的技能。3.1 目录结构一个技能就是一个文件夹最少只需要一个 SKILL.mdmy-skill/ ├── SKILL.md # 必须元数据 指令 ├── scripts/ # 可选可执行代码 ├── references/ # 可选参考文档 └── assets/ # 可选模板、资源文件SKILL.md 是入口Agent 启动时只读它的 YAML 前置数据name description。当任务匹配 description 时才加载 Markdown 正文。scripts 和 references 里的内容不会自动进上下文需要正文里显式引用才会被读取。3.2 YAML 前置数据字段必填字段只有两个但可选字段决定了技能的可维护性--- name: pdf-processing description: 从 PDF 文件中提取文本和表格填写表单合并文档。当用户需要处理 PDF 文件时使用此技能。 license: Apache-2.0 compatibility: 需要 Python 3.10依赖 pdfplumber 和 pypdf metadata: author: example-org version: 1.0 allowed-tools: Bash(python:*) Read Write ---字段约束对照表字段必填限制条件name是最多 64 字符仅小写字母、数字、短横线不能以短横线开头或结尾description是最多 1024 字符非空必须说明“做什么”和“何时用”license否许可证名称或指向捆绑许可证文件的引用compatibility否最多 500 字符说明环境要求metadata否任意键值对存作者、版本等allowed-tools否空格分隔的预批准工具列表实验性字段description 是最关键的字段。它决定了 Agent 在“发现阶段”能否正确判断该不该激活这个技能。写法上建议包含动作 对象 触发场景比如“从 PDF 提取文本和表格”是动作和对象“当用户需要处理 PDF 文件时”是触发场景。3.3 正文结构模板YAML 之后的 Markdown 正文没有格式限制但为了可维护建议按固定结构写# PDF 处理 ## 何时使用此技能 当用户需要从 PDF 提取文本、表格或填写 PDF 表单、合并多个 PDF 时使用。 ## 如何提取文本 1. 确认文件路径存在 2. 使用 pdfplumber 打开文件 3. 遍历每一页调用 extract_text() 4. 将结果写入输出文件 ## 如何填写表单 ...正文里可以引用 scripts 目录下的脚本比如“执行scripts/extract.py完成提取”。Agent 在执行阶段会按需读取这些文件。3.4 在 Claude Code 中配置技能目录Claude Code 默认会扫描~/.claude/skills/目录。你可以把技能包放在这里或者通过 settings 指定额外路径。settings 文件通常位于~/.claude/settings.json{ skills: { directories: [ ~/.claude/skills, ./project-skills ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意 Base URL、API Key、Model ID 三件套要写全。如果你用的是 Cline 或 CC Switch配置位置不同但字段名类似核心都是把请求指向https://taotoken.net/api。4. 本地加载与调用验证从 skills-ref validate 到实际触发写完技能包别急着丢给 Agent 用。先做两步验证格式校验和实际触发测试。4.1 用 skills-ref 校验格式skills-ref 是一个技能校验工具可以通过 pip 安装pip install skills-ref安装后进入技能包上级目录执行skills-ref validate ./my-skill如果格式正确会输出类似✓ my-skill/SKILL.md is valid name: pdf-processing description: 从 PDF 文件中提取文本和表格...常见报错及原因报错信息原因修复name must match ^[a-z0-9-]$name 含大写或下划线改成小写字母和短横线description is required缺少 description补上描述name exceeds 64 charactersname 太长缩短到 64 字符内SKILL.md not found路径不对确认目录下有 SKILL.md4.2 验证模型调用连通性技能最终要调模型所以先确认 Base URL 和 Key 能通。用 curl 发一个最小请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }正常返回会包含content: [{type: text, text: OK}]。如果返回 401说明 Key 不对如果返回local proxy failed说明 Base URL 写错或网络不通。4.3 触发技能测试在 Claude Code 里输入一个匹配 description 的任务比如“帮我从这个 PDF 里提取表格”。观察 Agent 是否加载了 SKILL.md。你可以在对话中让它输出当前激活的技能名来确认。如果技能没被触发大概率是 description 写得不够具体。把“处理 PDF”改成“从 PDF 文件中提取文本和表格填写表单合并文档”触发率会明显提升。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来对照遇到问题直接查表。5.1 401 Unauthorized{error: {type: authentication_error, message: invalid x-api-key}}原因通常是 Key 复制不完整、Key 已删除、或者请求头字段名写错。Anthropic 接口用x-api-keyOpenAI 兼容接口用Authorization: Bearer。检查你的配置里用的是哪种。5.2 local proxy failedError: local proxy failed to connect to upstream这个报错说明请求根本没发出去。检查 Base URL 是否写成https://taotoken.net/api注意不要多写/v1或少写/api。另外确认本机没有残留的代理环境变量干扰比如HTTP_PROXY。5.3 reading choices 相关报错TypeError: Cannot read properties of undefined (reading choices)这是 OpenAI 兼容接口的典型报错说明返回体结构不符合预期。常见原因是 Base URL 指向了 Anthropic 原生接口但客户端按 OpenAI 格式解析。解决方法是确认客户端类型Claude Code 用 Anthropic 格式Cline 用 OpenAI 兼容格式两者 Base URL 路径可能不同。5.4 OAuth 相关报错OAuth token expired or invalid如果你用的是 Claude Code 的 OAuth 登录模式它可能绕过了你配置的 API Key。需要在 settings 里显式设置ANTHROPIC_API_KEY并关闭 OAuth 自动登录。或者用claude config set命令切换认证方式。5.5 技能不触发如果格式校验通过、模型也通但技能就是不激活检查三点description 是否包含用户可能说的关键词技能目录是否在扫描路径内SKILL.md 文件名是否大小写正确必须全大写。6. 把技能包用起来从单文件到可复用资产写到这里你已经有了一个能通过校验、能被 Agent 加载的技能包。接下来最重要的是养成“沉淀”习惯每次在对话里调好一段提示词就把它抽成 SKILL.md放进技能目录。积累十几个技能后你的 Agent 会从“什么都要现问”变成“按需调用专家”。对于需要长期跑编码任务的场景建议把技能包和 Coding Plan 搭配使用模型调用成本更可控。创建和管理 Key 在 API Keys 页面接口细节可以查 接入文档。如果你用 Claude CodeClaudeCodeAnthropic 这个 deep link 有专门的配置说明。最后一个实用技巧给技能包建一个 git 仓库每个技能一个文件夹用 tag 标版本。这样换工具、换模型时技能资产不会丢。