1. 从零构建 Agent Skill为什么你的 Prompt 总是复用不起来如果你最近在用 Claude、GPT 这类助手做事大概率踩过这些坑每次对话都要重新讲规则、项目里写了一堆自定义指令却没法复用、各种长 Prompt 到处复制粘贴时间久了谁也不记得最新版本是哪份。Agent Skill 就是来解决这个问题的。它是一套可复用的知识包让模型在遇到相关需求时自动触发某种专业能力。翻译成人话就是你把一套专业能力流程、规范、脚本、模板封装成一个模块模型遇到相关需求时自动加载用你预先设计好的方法来处理问题而不是临场自由发挥。这篇文章面向需要把 Agent 能力沉淀为工程资产的开发者。我会带你从空目录开始搭出一个能被 Cline MCP、Windsurf BYOK 等工具直接加载的 Skill 包交付 SKILL.md 模板、references 目录约定、scripts 调用示例并给出把 endpoint 改到 TaoToken 的配置片段与一次完整加载验证动作。Skill 和 MCP、项目指令、系统提示的定位差异用一张表说清楚能力维度SkillMCP项目指令系统提示跨对话复用支持支持不支持不支持自动触发支持不支持不支持支持能否执行代码支持支持不支持不支持渐进加载信息支持不支持不支持不支持核心定位专业技能与业务流程接外部系统/工具当前项目的上下文人设与基础行为规则一句话总结MCP 更像「接外部工具的接口层」Skill 更像「带流程和示例的专业应用层」。适合做 Skill 的场景有几个共同特点经常反复做固定格式的报告、代码审查流程、有领域门槛专利解读、合同风险识别、有明确流程多步骤、需要判断分支、涉及工具或脚本跑脚本、处理文件、调接口。不适合的场景也很清楚一次性需求、简单事实查询、严重依赖实时数据且更适合直接用 MCP 的任务。设计高质量 Skill 需要遵循四个核心原则。第一是渐进式披露把信息分成三层——元信息name description永远加载、SKILL.md 正文触发时加载建议 500 行以内、附加资源references/scripts/assets按需加载。第二是把上下文当公共资源每个 token 都要问一句「值吗」能用可跑示例替代长篇解释就替代。第三是按任务脆弱性调节自由度创意任务给方向高风险任务写严格步骤和具体命令。第四是记住读者是模型不是人多用祈使句假设模型有基础技能只补它不知道的业务规则和流程。2. TaoToken 前置准备统一 Key 接入与模型选型在开始搭 Skill 之前先把模型接入层准备好。我试过用 TaoToken 作为统一入口好处是一个 Key 就能覆盖 Claude、GPT 等主流模型切换模型不用改代码对 Skill 这种需要反复调试触发逻辑的场景特别友好。TaoToken 的定位是 AI 模型统一接入平台提供 OpenAI 兼容的 API 接口。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key。拿到 Key 之后你需要确认三件套Base URL、API Key、Model ID。这三样是后面所有配置的基础。Base URL 统一用https://taotoken.net/api注意这个地址不加 UTM 参数直接写进配置文件即可。API Key 在控制台的 API Keys 页面生成格式通常是sk-开头的一串字符。Model ID 根据你要用的模型选择比如claude-sonnet-4-20250514、gpt-4o等具体可用列表在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以查到。如果你打算长期做编码类 Agent 开发建议了解一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它针对高频编码场景做了额度优化比按量计费更划算。对于 Claude Code 用户TaoToken 提供了 Anthropic 兼容接口配置方式略有不同。你需要在环境变量里设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY具体可以参考 Claude Code 接入文档 https://taotoken.net/doc/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite。这里要提醒一点TaoToken 是合规的 API 聚合服务不是灰色中转。所有请求都走官方渠道你不用担心稳定性和合规问题。准备好 Key 之后先用一个最简单的 curl 请求验证连通性curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }如果返回的 JSON 里choices[0].message.content包含 OK说明接入层没问题。这一步很重要因为后面 Skill 调试时如果触发失败你需要先排除是模型接入的问题还是 Skill 本身的问题。3. 可复制配置SKILL.md 模板与目录结构这一章是核心交付。我会给出完整的 SKILL.md 模板、references 目录约定、scripts 调用示例以及把 endpoint 改到 TaoToken 的配置片段。先看目录结构。一个完整的 Skill 包长这样patent-analyzer/ ├── SKILL.md # 必需核心文件 ├── references/ # 可选详细参考文档 │ ├── claim-parsing.md # 权利要求解读 │ ├── infringement.md # 侵权判断规则 │ └── api.md # 接口参考 ├── scripts/ # 可选可执行脚本 │ ├── search.py # 专利检索 │ ├── analyze.py # 专利分析 │ └── validate.py # 结果校验 ├── assets/ # 可选模板资源 │ └── report-template.md └── LICENSE.txt # 推荐许可证SKILL.md 的 frontmatter 是整个 Skill 的触发开关写法有严格规范。name 必须全小写、用短横线连接、不超过 64 字符、不能包含品牌词。description 是触发的核心建议用「做什么 何时触发 触发关键词」的黄金公式。--- name: patent-analyzer description: | 专利检索、分析与侵权判断工具。当用户提供技术关键词、专利号或产品描述 需要检索专利、解读权利要求或判断侵权风险时使用。 Use when user asks to search patents, analyze claims, or assess infringement. 触发方式 Triggers: 检索专利, 分析权利要求, 侵权判断, patent search --- # Patent Analyzer ## Overview 本 Skill 提供专利领域的检索、分析和侵权判断能力覆盖从关键词检索到权利要求解读的完整流程。 ## When to Use - 用户提供技术关键词要求检索相关专利 - 用户提供专利号或 PDF要求分析权利要求 - 用户提供产品描述和专利号要求判断侵权风险 ## Quick Start 最简单的调用方式 bash python scripts/search.py 区块链共识机制 --limit 10WorkflowStep 1: 判断任务类型检索类 → 走 Method 1分析类 → 走 Method 2侵权判断 → 走 Method 3Step 2: 执行对应流程[各方法的详细步骤]Reference Filesclaim-parsing.md - 权利要求解读规则infringement.md - 侵权判断标准api.md - 接口调用参考Error Handling检索无结果建议放宽关键词或更换同义词专利号格式错误检查是否为 8-12 位数字或字母组合接下来是把 endpoint 改到 TaoToken 的配置片段。根据你使用的工具不同配置位置也不一样。 如果你用的是 Cline MCP需要在 MCP 配置文件里加上 TaoToken 的 endpoint。Cline 的 MCP 配置通常放在 ~/.cline/mcp_settings.json 或项目根目录的 .cline/mcp.json json { mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }如果你用的是 Windsurf BYOK配置在~/.windsurf/settings.json{ windsurf.providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, models: [claude-sonnet-4-20250514, gpt-4o] } } }如果你用的是 Codex配置在~/.codex/auth.json{ openai: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 } }注意三件套必须写全Base URL 是https://taotoken.net/apiAPI Key 是你的sk-开头密钥Model ID 根据实际需求选择。缺任何一个都会导致 401 或 model not found 错误。scripts 目录下的脚本要遵循「黑盒工具」原则通过--help就能知道用途和参数单一职责幂等输出清晰。这是一个标准的 Python 脚本模板#!/usr/bin/env python3 专利检索脚本。 Usage: python search.py keyword [--limit N] [--output FILE] Examples: python search.py 区块链共识机制 --limit 10 python search.py 锂电池 --output result.json import argparse import sys import json def search_patents(keyword, limit): # 实际检索逻辑这里用模拟数据 return [{id: fCN{i:08d}, title: f{keyword}相关专利{i}} for i in range(limit)] def main(): parser argparse.ArgumentParser(description专利检索工具) parser.add_argument(keyword, help检索关键词) parser.add_argument(--limit, typeint, default10, help返回数量) parser.add_argument(-o, --output, help输出文件路径) args parser.parse_args() try: results search_patents(args.keyword, args.limit) output json.dumps(results, ensure_asciiFalse, indent2) if args.output: with open(args.output, w, encodingutf-8) as f: f.write(output) print(f✓ 已保存 {len(results)} 条结果到 {args.output}) else: print(output) sys.exit(0) except Exception as e: print(f✗ 错误: {e}, filesys.stderr) sys.exit(1) if __name__ __main__: main()references 目录下的文件是写给模型看的「长文档」每个文件要自包含、不依赖其他文件、长度控制在 100-500 行、超过 100 行加个小目录。推荐结构--- name: claim-parsing description: 权利要求解读规则与示例 --- # 权利要求解读 ## Overview 本文件说明如何解读专利权利要求包括独立权利要求和从属权利要求的区分。 ## 独立权利要求 [解读规则 示例] ## 从属权利要求 [解读规则 示例] ## Common Patterns [常见模式] ## Troubleshooting [常见问题]4. 验证请求一次完整的 Skill 加载与触发测试配置写完之后必须做一次完整的加载验证。这一步不能省因为 Skill 的触发逻辑和普通 Prompt 不一样它依赖 description 的语义匹配很容易出现「配置都对但就是不触发」的情况。验证分三步加载验证、触发验证、执行验证。加载验证是确认工具能识别到 Skill 包。以 Cline MCP 为例重启 Cline 后在对话里输入「列出可用的 MCP 工具」如果配置正确你应该能看到taotoken相关的工具列表。如果看不到检查 MCP 配置文件的 JSON 格式是否正确以及npx命令是否能正常执行。触发验证是确认 description 能正确匹配用户意图。这一步最容易被忽略但恰恰是 Skill 能否自动触发的关键。你可以用几种不同的说法测试测试 1: 帮我检索关于区块链共识机制的专利 测试 2: 我想看看锂电池相关的专利有哪些 测试 3: search patents about quantum computing如果 Skill 被正确触发模型会调用patent-analyzer并执行scripts/search.py。如果没有触发说明 description 里的触发关键词覆盖不够需要补充同义词。执行验证是确认脚本能正常跑通。你可以直接在终端里跑一遍cd patent-analyzer python scripts/search.py 区块链共识机制 --limit 5预期输出[ {id: CN00000001, title: 区块链共识机制相关专利0}, {id: CN00000002, title: 区块链共识机制相关专利1}, {id: CN00000003, title: 区块链共识机制相关专利2}, {id: CN00000004, title: 区块链共识机制相关专利3}, {id: CN00000005, title: 区块链共识机制相关专利4} ]如果脚本报错先检查 Python 版本建议 3.8和依赖是否安装。如果输出为空检查关键词是否过于生僻。完整的验证流程走一遍之后你还可以用 TaoToken 的模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 做一次端到端测试把 SKILL.md 的内容作为 system prompt 贴进去然后输入触发语句看模型是否能按照 Workflow 的步骤执行。这里有个小技巧验证触发时把 description 单独拿出来做一次语义匹配测试。你可以问模型「以下哪些用户输入会触发这个 Skill」把 description 和几条测试语句一起贴进去让模型判断。如果模型判断的结果和你的预期不一致说明 description 需要调整。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一章对照真实报错给出排查路径。这些错误我在调试 Skill 接入时基本都踩过一遍。401 Unauthorized这是最常见的错误通常有三个原因API Key 写错、Base URL 写错、Key 已过期。排查步骤先确认 Key 是否以sk-开头有没有多余空格。然后确认 Base URL 是https://taotoken.net/api注意结尾没有多余的斜杠。最后去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态是否正常。如果三件套都确认无误还是 401用 curl 直接测试curl -v https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}看返回的 headers 里www-authenticate字段能定位到具体是 Key 无效还是权限不足。local proxy failed这个错误通常出现在 Cline MCP 或 Windsurf BYOK 场景意思是本地代理启动失败。原因可能是端口被占用、代理进程没启动、或者配置文件路径不对。排查步骤先检查配置文件路径是否正确。Cline 的 MCP 配置在~/.cline/mcp_settings.jsonWindsurf 在~/.windsurf/settings.json。然后检查端口是否被占用MCP server 默认用 3000 端口如果被占用可以改成 3001。最后确认npx命令能正常执行有些环境需要先npm install -g npx。如果还是失败把 MCP server 的日志级别调到 debug看具体报错。Cline 的日志在~/.cline/logs/目录下。reading choices 报错这个错误通常是响应格式不符合预期导致的。比如你期望返回 JSON但模型返回了 Markdown 代码块包裹的 JSON解析就失败了。排查步骤先确认请求里的response_format参数是否正确设置。如果用的是 OpenAI 兼容接口可以加response_format: {type: json_object}。然后在 Skill 的 SKILL.md 里明确要求输出格式比如「输出必须是纯 JSON不要用代码块包裹」。如果模型还是返回代码块可以在 scripts 里加一层清洗逻辑import re def clean_json(text): # 去掉 markdown 代码块标记 text re.sub(r^json\s*, , text) text re.sub(r\s*$, , text) return json.loads(text)OAuth 相关报错如果你用的是 Claude Code 接入可能会遇到 OAuth 报错。这通常是因为 Claude Code 默认走 Anthropic 官方 OAuth 流程而 TaoToken 用的是 API Key 认证。排查步骤确认环境变量设置正确export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key然后在 Claude Code 的配置文件里禁用 OAuth强制走 API Key。具体配置参考 Claude Code 接入文档 https://taotoken.net/doc/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite。如果还是报 OAuth 错误检查是否有残留的 OAuth token 缓存清理~/.claude/目录下的缓存文件后重试。模型返回空内容有时候请求成功但choices[0].message.content是空的。这通常是 max_tokens 设置太小或者模型在思考阶段被截断。把max_tokens调到 1024 以上再试。Skill 不触发配置都对但 Skill 就是不触发九成是 description 的问题。检查 description 里有没有覆盖用户可能说的原话触发关键词是否足够具体。一个实用的方法是把 description 贴给模型问它「以下用户输入哪些会触发这个 Skill」根据模型的判断来调整。6. 把 Skill 当成产品来迭代CTA 与长期维护搭完第一个 Skill 之后你会发现真正的挑战不是写 SKILL.md而是持续迭代。一个好的 Agent Skill 本质上是一个可维护、可扩展的「小产品」而不是一段高级 Prompt。迭代的核心是建立反馈闭环。每次 Skill 触发失败或执行出错都记录下来定期回顾。我建议在项目里维护一个ITERATION.md格式如下## 迭代记录 ### 问题1: Description 触发不准确 现象: 用户说检索专利时没有触发 解决: 在 description 中添加检索、搜索关键词 ### 问题2: 流程中途中断 现象: 模型执行到第3步就停止了 解决: 在 SKILL.md 中添加明确的步骤编号和继续下一步提示 ### 问题3: 脚本报错信息不清晰 现象: 用户不知道如何解决报错 解决: 改进脚本的错误信息添加解决建议发布前的质量检查清单我整理成四块Frontmatter 检查name 符合命名规则、description 清楚描述「做什么」和「何时触发」、字数不超过 1024 字符。SKILL.md 检查有 Quick Start、有清晰的工作流程、示例代码能直接跑、所有引用的文件都真实存在、总行数不超过 500 行。附加文件检查references 里的文件自包含、scripts 里的脚本都带--help、脚本有基础错误处理、没有多余文件README、CHANGELOG 等。功能与维护性自查内容是否精简、触发是否准确、执行是否可靠、后续扩展是否容易。常见反模式要绕开描述太模糊、一次性塞太多内容、不写触发条件、代码示例不可执行、脚本没帮助信息、创建一堆没用的说明文件。最后说下 CTA 分流。如果你在排障或接入阶段遇到问题优先看 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。如果你想先验证模型效果再决定用哪个去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试。如果你是长期做编码类 Agent 开发Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 的额度优化更划算。把 Skill 当成产品来维护你会发现后面很多复杂需求不用从头想 Prompt 了直接往这个 Skill 上加场景就能稳定复用。这才是从「玩工具」到「做产品」的真正分界线。