1. 从一次“技能失控”说起SKILLS 开发到底解决什么问题你可能遇到过这种场景同一个提示词今天让模型整理会议纪要效果很好明天换个会话就完全跑偏或者团队里三个人各自维护一套“会议总结”提示词改来改去最后没人知道哪版是对的。这不是模型变笨了而是缺少一个可复用、可版本管理、可被 agents 自动调度的技能模块。SKILLS 开发要解决的正是把“一次性提示词”升级成“可加载的技能包”这件事。SKILLS 本质上是一个文件夹约定一个SKILL.md作为入口说明书配合agents/、scripts/、references/、assets/四类资源目录让模型在触发时知道“什么时候用、按什么流程做、调用哪些脚本、参考哪些资料”。它适合三类人想把个人提示词沉淀成资产的独立开发者、需要给多个 agents 统一行为规范的团队、以及希望把确定性步骤如 PDF 旋转、日期归一化交给脚本而不是靠模型自由发挥的工程同学。我试过把一套会议纪要技能从“散装提示词”重构成 SKILLS 结构最直观的变化是触发准确率上来了输出格式稳定了脚本负责的日期解析不再随机出错。下面这套流程你可以直接照着搭出第一个自定义 SKILLS。2. TaoToken 前置准备给 SKILLS 一个稳定的模型入口SKILLS 本身是文件结构但它的触发和执行最终要落到模型调用上。如果你在本地调试 agents 调度或者用 Claude Code、Cline 这类工具加载技能就需要一个统一的模型接入点。TaoToken 在这里扮演的是“模型网关”角色你拿到一个 Base URL 和一个 Key就能在配置里切换不同模型而不用为每个工具单独维护一套鉴权。先做三件事。第一打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并进入控制台。第二在控制台里创建 API Key建议按项目命名比如skills-dev-local方便后续排查是哪个环境在调用。第三记下两个地址API 基址用 https://taotoken.net/api这个不加 UTM模型对话入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里有个容易踩的坑很多人把 Key 直接写进SKILL.md的 frontmatter 里这是错的。SKILL.md是给模型读的说明书不应该包含任何密钥。正确的做法是把 Key 放在环境变量或工具的配置文件里SKILL.md只描述“需要调用模型时使用已配置的入口”。如果你用的是 Claude Code 或 Cline它们的配置里会有 Base URL、API Key、Model ID 三个字段这三个要写全缺一个就会出现 401 或模型找不到的错误。对于长期做技能开发和 agents 调度的同学可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合需要反复调试、多轮验证的场景。而如果你只是想先验证某个技能的输出效果用模型对话页面就够了。3. 可复制配置SKILL.md 模板与目录结构落地这一节是核心我给你一套可以直接复制、改个名字就能用的结构。先看目录meeting-note-summarizer/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── scripts/ │ └── normalize_dates.py ├── references/ │ ├── examples.md │ └── style-guide.md └── assets/ └── template.docxSKILL.md分两大部分YAML frontmatter 和 Markdown 正文。frontmatter 里最关键的是name和description。name要求小写、连字符连接、不要带 “skill” 这个词比如meeting-note-summarizer。description是触发依据要写清楚“做什么”和“什么时候用”不能太泛。下面是一个可复制的模板--- name: meeting-note-summarizer description: summarize meeting notes and transcripts into structured decisions, action items, owners, deadlines, and open questions. use when the user provides raw meeting content, transcripts, or notes and wants a clean, organized summary. --- # Overview 将原始会议记录、逐字稿或零散笔记整理为结构化输出。优先提取明确结论、行动项、负责人、截止时间和未解决问题。 ## Workflow 1. 阅读输入判断类型完整逐字稿、简要笔记、已整理纪要。 2. 提取关键信息决定、行动项、风险、未确认问题。 3. 结构化行动项识别 task、owner、deadline。 4. 信息缺失时标注 not specified不要猜测。 5. 按输出要求生成最终结果。 ## Resources - 输出示例见 [references/examples.md](references/examples.md)。 - 风格规则见 [references/style-guide.md](references/style-guide.md)。 - 日期归一化使用 [scripts/normalize_dates.py](scripts/normalize_dates.py)。 ## Output Requirements Use the following section order: 1. Summary 2. Decisions 3. Action Items 4. Risks 5. Open Questions - Summary 控制在 3 到 5 句。 - Action Items 每项包含 task、owner、deadline。 - 缺失信息标注 not specified。 - 不要虚构事实。agents/openai.yaml负责界面展示通常包含显示名、简介、图标颜色name: Meeting Note Summarizer description: 将会议记录整理为结构化纪要 icon: calendar color: #4A90D9scripts/放确定性步骤。比如日期归一化写成 Python 脚本比让模型自由发挥可靠得多import re from datetime import datetime def normalize_date(text): patterns [ (r(\d{4})[年/-](\d{1,2})[月/-](\d{1,2}), %Y-%m-%d), (r(\d{1,2})[月/-](\d{1,2}), %m-%d), ] for pattern, fmt in patterns: match re.search(pattern, text) if match: return datetime.strptime(match.group(0), fmt).strftime(%Y-%m-%d) return not specifiedreferences/放按需加载的资料比如表结构说明、输出规范、业务规则。关键点是不要把所有内容堆进SKILL.md而是用条件说明告诉模型什么时候读哪个文件。例如## Resources - 当输入是完整逐字稿时参考 [references/transcript-rules.md](references/transcript-rules.md)。 - 当用户要求简短摘要时参考 [references/summary-template.md](references/summary-template.md)。 - 仅当需要日期归一化时使用 [scripts/normalize_dates.py](scripts/normalize_dates.py)。这样模型不会一次性加载所有资源而是按条件触发既省 token 又提高准确率。4. 验证请求本地加载与成功结果确认配置写完后必须验证技能能被正确加载和触发。如果你用的是支持 SKILLS 的本地工具通常有一个技能目录扫描机制。以 Claude Code 为例把技能文件夹放到约定的 skills 目录下然后在配置里确认 Base URL、API Key、Model ID 三件套齐全。配置文件通常长这样{ base_url: https://taotoken.net/api, api_key: sk-your-key-here, model: claude-sonnet-4-20250514 }注意base_url用 https://taotoken.net/api 不要加多余路径。保存后重启工具让它重新扫描技能目录。验证是否加载成功可以输入一句触发语比如“帮我把这段会议记录整理成纪要”观察模型是否按SKILL.md里的 Workflow 执行。一个成功的验证结果应该满足三点第一输出结构严格按Output Requirements里的顺序Summary、Decisions、Action Items、Risks、Open Questions 一个不少第二行动项里每项都有task、owner、deadline缺失的标注not specified第三如果输入里有日期脚本被调用后日期格式统一为YYYY-MM-DD。如果验证时模型没有按预期触发先检查description是否足够具体。太泛的描述比如“处理会议内容”会导致触发不稳定要写成“summarize meeting notes and transcripts into structured decisions, action items, owners, deadlines, and open questions”。另外SKILL.md的正文不要用来决定“是否触发”触发只由 frontmatter 的description决定正文只规定“触发后怎么干”。5. 本篇常见错排查401、local proxy failed 与 reading choices调试 SKILLS 时报错基本集中在接入层和解析层。下面按真实报错对照排查。401 Unauthorized最常见。原因通常是 API Key 没写对、Key 过期、或者把 Key 写进了SKILL.md而不是工具配置。检查三件套Base URL 是否为 https://taotoken.net/api Key 是否与控制台一致Model ID 是否拼写正确。如果用的是 Claude Code确认配置文件路径没有被其他项目覆盖。local proxy failed这个报错通常出现在本地工具尝试通过代理转发请求时。先确认你的工具配置里没有多余的代理设置Base URL 直接指向 https://taotoken.net/api 即可。如果工具本身有网络层配置检查是否误开了本地转发。这个错误和技能文件本身无关是接入配置问题。reading choices 相关报错当模型返回结构不符合预期工具在解析choices字段时可能报错。这往往是因为SKILL.md的Output Requirements写得太模糊模型输出了非结构化内容。解决办法是把输出格式写死比如明确要求“Use the following section order”并用有序列表固定顺序。如果用了scripts/确认脚本返回的是纯文本或 JSON不要返回带额外日志的内容。OAuth 相关报错部分工具用 OAuth 流程获取临时凭证。如果报 OAuth 错误先检查工具版本是否支持当前接入方式然后确认回调地址没有被防火墙拦截。这种情况下改用 API Key 直连通常更省事Base URL 和 Key 配好即可。技能不触发不是报错但很常见。检查description是否包含用户可能说的关键词比如“会议记录”“逐字稿”“纪要”。如果用户说“整理一下这个讨论”而你的 description 只写了“meeting notes”就可能不触发。把同义表达补进去。脚本不执行确认SKILL.md的Resources里用 Markdown 链接语法正确指向了脚本路径比如[scripts/normalize_dates.py](scripts/normalize_dates.py)。路径是相对技能根目录的不要写成绝对路径。6. 语义一致 CTA把技能沉淀成可复用资产走到这里你已经有了一个能加载、能触发、能输出稳定结构的 SKILLS 模块。接下来要做的是把它变成团队可复用的资产。建议把技能目录纳入 Git 管理SKILL.md的每次修改都走 commit这样出问题能回滚。references/里的业务规则如果经常变可以拆成独立文件按条件加载避免每次改规则都动主文件。如果你在调试 agents 调度时需要频繁切换模型用模型对话入口快速验证输出https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期做技能开发和 Agent 编排的Coding Plan 更适合反复调试的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后一个实用技巧给每个技能写一个最小的验证用例放在references/examples.md里包含输入和期望输出。每次改完SKILL.md用这个用例跑一遍比凭感觉判断可靠得多。技能开发不是一次写完就结束而是像代码一样持续迭代。