1. 为什么我要用 skill-creator 造一个自动生成 SKILL.md 的 SkillSkill 是 Anthropic 提出的一种模块化能力封装方式你可以把它理解成给 Claude 准备的“岗位入职手册”一个目录、一份 SKILL.md加上可选的脚本、参考资料和资源文件就能把某类任务的专业流程、领域知识和工具调用方式固化下来。它解决的问题很具体——上下文窗口是公共资源系统提示词、对话历史、其他 Skill 的元数据都在抢这块地方如果把所有领域知识都塞进主提示词Token 消耗会迅速失控。Skill 用三级加载机制缓解这个问题name 和 description 常驻上下文SKILL.md 正文只在触发后加载scripts/references/assets 则按需读取甚至直接执行而不进上下文。那为什么还要再套一层做一个“自动生成 SKILL.md 的 Skill”因为手写 SKILL.md 这件事本身有重复劳动。每次新建一个 Skill你都要想 name 怎么起、description 怎么写才能被正确触发、正文用祈使句还是说明句、哪些内容该拆到 references、哪些该做成 scripts。这些决策有固定套路完全可以交给一个 Skill 来代劳。我这次要做的 skill-creator输入是一段功能描述和使用场景输出是一份结构合规、字段完整、可以直接放进 skills 目录被 Claude 识别的 SKILL.md顺带把目录骨架也建好。这篇文章适合三类人一是刚接触 Skill、想知道 SKILL.md 到底长什么样的新手二是已经写过几个 Skill、想把手写流程自动化的开发者三是用 Claude Code 或 Cursor 做长期编码、希望把团队规范沉淀成 Skill 的工程师。全文会给出 skill-creator 的初始化命令、SKILL.md 模板字段、自动生成脚本的可复制配置以及通过 TaoToken 统一 Key 接入 Claude 后的实际运行与报错排查。你跟着做最后能拿到一个可复用的 skill-creator并且知道它每一步为什么这么设计。需要先明确一个边界Skill 不是替代编辑器或 IDE 的东西它是给智能体用的能力包。skill-creator 生成的也是给 Claude 读的文件不是给人看的文档站。所以下面所有配置都围绕“让另一个 Claude 实例能高效执行任务”这个目标来写。2. TaoToken 前置统一 Key 接入 Claude 的准备与 skill-creator 目录规划在动手写 skill-creator 之前先把运行环境理顺。Skill 的调用依赖 Claude 能读到 skills 目录而 Claude 的请求要走一个稳定的入口。我用 TaoToken 做统一 Key 接入好处是 Base URL、Key、Model ID 三件套集中管理切换模型或换项目时不用到处改配置。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个就行。先说清楚 Skill 的目录约定。Claude Code 和 Cursor 都会在项目的 skills 目录下扫描子文件夹每个子文件夹是一个 Skill里面必须有 SKILL.md。skill-creator 自己也是一个 Skill所以它的目录结构是skills/ └── skill-creator/ ├── SKILL.md ├── scripts/ │ ├── init_skill.py │ └── generate_skill_md.py ├── references/ │ └── skill-spec.md └── assets/ └── skill-template.md这里有个容易踩的坑很多人把 SKILL.md 直接放在 skills 根目录结果 Claude 扫描不到。必须是 skills//SKILL.md 这种两级结构。skill-creator 的 name 字段就填 skill-creatordescription 要写清楚“当用户想要创建新 Skill 或更新现有 Skill 时使用”因为 description 是 Claude 判断是否触发的唯一依据正文里的“何时使用”对触发没有帮助正文只在触发后才加载。接下来准备 TaoToken 的接入配置。如果你用 Claude Code配置通常写在 settings.json 或环境变量里如果用 Cline 这类插件会有一个 MCP 或 provider 配置。核心三件套是配置项值说明Base URLhttps://taotoken.net/api不带 UTM末尾不要多加斜杠API Key在控制台创建形如 sk-xxx只显示一次Model ID按控制台可用列表填例如 claude-sonnet 系列标识API Key 的创建入口在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。我建议先把 Key 创建好、复制到安全的地方再去写 skill-creator否则脚本跑起来会卡在鉴权上。如果你还没决定用哪个模型可以先去 https://taotoken.net/models 用对话方式验证一下模型是否可用确认能正常返回再进入编码环节。还有一个前置动作确认你的 Claude 客户端版本支持 Skill。较新的 Claude Code 和 Cursor 都支持通过 /skill-name 唤起 Skill。如果你的版本里没有 skills 目录概念那 skill-creator 生成的文件也不会被加载这时候要先升级客户端。这一步别跳过我见过有人写了半天 SKILL.md结果客户端根本不扫这个目录。环境理顺后skill-creator 的定位就清晰了它是一个“元 Skill”本身不处理业务只负责把用户的自然语言描述转成合规的 SKILL.md 和目录骨架。它的 scripts 里放两个 Python 脚本references 里放 Skill 规范说明assets 里放模板文件。下面进入具体配置。3. 可复制配置skill-creator 的 SKILL.md 模板字段与自动生成脚本这一节是全文的核心给出可以直接复制粘贴的配置。先写 skill-creator 自己的 SKILL.md再写它用来生成其他 SKILL.md 的脚本。3.1 skill-creator 的 SKILL.md 头部与正文SKILL.md 的 YAML frontmatter 只允许 name 和 description 两个字段不要加别的。description 要把“做什么”和“何时用”都写进去因为这是触发依据。下面这份可以直接用--- name: skill-creator description: 生成合规 Skill 的指南与脚本。当用户想要创建新 Skill、更新现有 Skill或需要把某类工作流、领域知识、工具集成封装成 SKILL.md 时使用。支持从功能描述自动生成 SKILL.md、目录骨架和示例资源。 --- # Skill Creator ## 概述 本 Skill 用于把用户的自然语言描述转换为符合 Anthropic Skill 规范的目录结构和 SKILL.md 文件。 ## 使用流程 1. 收集用户对目标 Skill 的功能描述、使用场景和示例用法。 2. 运行 scripts/init_skill.py 初始化目录骨架。 3. 运行 scripts/generate_skill_md.py 生成 SKILL.md。 4. 根据 references/skill-spec.md 校验字段合规性。 5. 提示用户把生成目录放入 skills/ 下并重启客户端。 ## 生成 SKILL.md 的规则 - frontmatter 只包含 name 和 description。 - description 必须包含功能说明和触发条件。 - 正文使用祈使句控制在 500 行以内。 - 详细参考资料放 references/可执行逻辑放 scripts/输出模板放 assets/。 - 不生成 README.md、CHANGELOG.md 等辅助文档。注意正文里没有“何时使用此 Skill”这种段落因为那部分信息已经在 description 里了正文写它属于浪费上下文。3.2 初始化脚本 init_skill.py这个脚本负责建目录、写占位文件。路径参数用绝对路径更稳避免相对路径在不同工作目录下解析错乱。#!/usr/bin/env python3 import argparse import os from pathlib import Path TEMPLATE --- name: {name} description: TODO 填写功能说明与触发条件 --- # {title} ## 概述 TODO 描述这个 Skill 解决什么问题。 ## 使用流程 1. TODO def init_skill(name: str, out_dir: str) - None: root Path(out_dir).expanduser().resolve() / name if root.exists(): raise SystemExit(f目录已存在: {root}) for sub in (scripts, references, assets): (root / sub).mkdir(parentsTrue, exist_okTrue) (root / SKILL.md).write_text( TEMPLATE.format(namename, titlename.replace(-, ).title()), encodingutf-8, ) print(f已初始化: {root}) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(name, helpSkill 名称使用小写连字符) parser.add_argument(--path, default./skills, help输出目录) args parser.parse_args() init_skill(args.name, args.path)运行方式python3 scripts/init_skill.py article-title --path ./skills执行后会在 ./skills/article-title 下生成 SKILL.md 和三个空目录。这里有个细节脚本用raise SystemExit而不是直接覆盖是为了防止误删已有 Skill。如果你确实要重建先手动删目录。3.3 自动生成 SKILL.md 的脚本 generate_skill_md.py这个脚本接收功能描述、场景、示例拼出合规的 SKILL.md。它把 description 的构造逻辑单独抽出来确保“何时使用”一定进 description。#!/usr/bin/env python3 import argparse from pathlib import Path FRONTMATTER --- name: {name} description: {description} --- BODY # {title} ## 概述 {overview} ## 使用流程 {steps} ## 示例 {examples} def build_description(name: str, func: str, scene: str) - str: return ( f{func}。当用户需要{scene}时使用此 Skill f它通过封装专业流程和可复用资源来扩展 Claude 的能力。 ) def generate(name: str, func: str, scene: str, overview: str, steps: str, examples: str, out_dir: str) - None: root Path(out_dir).expanduser().resolve() / name root.mkdir(parentsTrue, exist_okTrue) desc build_description(name, func, scene) content FRONTMATTER.format(namename, descriptiondesc) content BODY.format( titlename.replace(-, ).title(), overviewoverview, stepssteps, examplesexamples, ) (root / SKILL.md).write_text(content, encodingutf-8) print(f已生成: {root / SKILL.md}) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(name) parser.add_argument(--func, requiredTrue, help功能说明) parser.add_argument(--scene, requiredTrue, help触发场景) parser.add_argument(--overview, defaultTODO 概述) parser.add_argument(--steps, default1. TODO) parser.add_argument(--examples, defaultTODO 示例) parser.add_argument(--path, default./skills) args parser.parse_args() generate(args.name, args.func, args.scene, args.overview, args.steps, args.examples, args.path)调用示例python3 scripts/generate_skill_md.py article-title \ --func 根据主题生成文章标题候选 \ --scene 需要为技术文章拟定标题 \ --overview 输入主题关键词输出 5 个候选标题。 \ --steps 1. 读取主题关键词\n2. 按风格生成候选\n3. 输出列表 \ --examples 输入: Skill 开发输出: 5 个标题 \ --path ./skills跑完后 ./skills/article-title/SKILL.md 就是一份字段完整、description 含触发条件的文件。你可以直接把它放进客户端的 skills 目录。3.4 通过 TaoToken 接入 Claude 的配置片段如果你用 Claude Codesettings 里配置 provider 的部分大致如下字段名以你客户端版本为准核心是 Base URL、Key、Model ID 三件套{ provider: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet } }如果你用 Cline 的 MCP 配置写法类似把 baseUrl 指向 https://taotoken.net/api apiKey 填控制台创建的 Keymodel 填可用模型标识。Codex 的 auth.json 则是把 Key 和 base URL 写进对应字段。三件套缺一不可只填 Key 不填 Base URL 会走到默认端点只填 Base URL 不填 Model ID 会报模型不存在。配置完成后把 skill-creator 目录放到 skills/ 下重启客户端输入 /skill-creator 应该能看到它被唤起。下一节验证实际请求。4. 验证请求在 Claude 中调用 skill-creator 并检查生成结果配置写完必须验证否则你不知道是 Skill 没被加载还是 Key 鉴权失败还是脚本报错。验证分三步先确认 Skill 被识别再确认脚本能跑最后确认生成的 SKILL.md 能被另一个 Skill 场景消费。第一步确认 Skill 被识别。重启客户端后在对话里输入 /skill-creator如果客户端支持 Skill 列表应该能看到它出现在候选里。如果看不到检查三件事目录是不是 skills/skill-creator/SKILL.md 两级结构frontmatter 的 name 是不是 skill-creatordescription 是不是非空。这三个任一不满足Skill 都不会被加载。第二步确认脚本能跑。在 skill-creator 目录下执行python3 scripts/init_skill.py demo-skill --path ./skills python3 scripts/generate_skill_md.py demo-skill \ --func 演示用功能 \ --scene 演示触发场景 \ --path ./skills预期输出是两行“已初始化”和“已生成”。如果报ModuleNotFoundError说明 Python 环境缺依赖这两个脚本只用标准库正常不会缺如果报权限错误检查输出目录是否可写。跑完后用cat ./skills/demo-skill/SKILL.md看一眼frontmatter 里 name 和 description 都在description 里包含“当用户需要……时使用此 Skill”。第三步确认生成的 Skill 能被消费。把 demo-skill 放进客户端的 skills 目录重启输入 /demo-skill看是否能唤起。这一步验证的是“生成的 SKILL.md 格式合规”如果唤起失败多半是 description 写得太泛Claude 判断不出触发时机。回到 generate_skill_md.py 的 build_description 函数把场景写得更具体。第四步验证 TaoToken 接入是否正常。在对话里发一条普通请求比如“你好确认一下连接”如果返回正常说明 Base URL、Key、Model ID 三件套生效。如果返回 401是 Key 问题如果返回模型不存在是 Model ID 问题如果返回连接超时是 Base URL 或网络问题。这一步和 Skill 验证要分开做否则出错时你分不清是 Skill 的问题还是接入的问题。我实测下来最容易出问题的是 description 的触发条件写得太模糊。比如只写“生成 SKILL.md”Claude 可能在你问“帮我写个文档”时也触发它。解决办法是在 description 里加限定词比如“当用户明确要求创建或更新 Skill 时使用”。这个细节直接决定 Skill 的可用性。验证通过后你就有了一个能自动生成 SKILL.md 的 skill-creator。接下来把它用到真实场景输入一段功能描述让它生成一个新 Skill再把新 Skill 放进目录测试。这个闭环跑通说明整条链路没问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照这一节按真实报错来排。Skill 开发和 TaoToken 接入叠在一起出错时信息容易混我按报错原文分类你对着找。401 Unauthorized。这是鉴权失败和 Skill 本身无关。检查 API Key 是否复制完整、是否有多余空格、是否已过期。TaoToken 的 Key 在控制台创建后只显示一次如果没保存只能重建。另外确认 Base URL 填的是 https://taotoken.net/api 如果误填成带 UTM 的官网地址鉴权会失败。Key 创建入口在 https://taotoken.net/api-keys 。local proxy failed / connection refused。这类报错通常是本地代理配置残留。检查环境变量里有没有 HTTP_PROXY、HTTPS_PROXY 指向一个已经关掉的本地端口。如果有清掉再试。注意这里说的是清理本地环境变量不是让你去配什么网络工具把不该有的代理项删掉即可。另外确认 Base URL 没有拼错末尾不要多加斜杠。reading choices 相关报错。这通常出现在响应体解析阶段说明请求发出去了、也返回了但返回结构不符合客户端预期。常见原因是 Model ID 填错客户端拿到的不是对话补全格式。去 https://taotoken.net/models 确认可用模型标识把配置里的 model 字段改成正确的。如果用的是 Cline 的 MCP 配置检查 MCP 返回格式是否被正确解析。OAuth 相关报错。如果你用的是 Claude Code 且走了 OAuth 流程报错可能是 token 刷新失败。这时候改用 API Key 方式接入更直接把三件套配好即可。OAuth 和 API Key 不要混用混用会导致鉴权头冲突。Skill 不触发。不是报错但很常见。检查 SKILL.md 的 frontmatter 是否只有 name 和 description多写字段可能导致解析失败检查 description 是否包含明确的触发条件检查目录层级是否是 skills//SKILL.md。如果都正常重启客户端再试有些版本需要重启才重新扫描 skills 目录。脚本执行报 FileNotFoundError。检查 --path 参数指向的目录是否存在init_skill.py 不会自动创建父目录之外的层级。用绝对路径最稳。生成的 SKILL.md 里 description 为空。检查 generate_skill_md.py 的 --func 和 --scene 是否都传了build_description 依赖这两个参数。如果只传一个拼出来的 description 会缺半句。排错时建议按“先接入、后 Skill”的顺序先用一条普通请求确认 TaoToken 三件套正常再验证 Skill 加载最后验证脚本生成。这样出错时能快速定位是哪一层的问题。接入相关的文档在 https://taotoken.net/doc 遇到鉴权或端点问题可以先查这里。6. 语义一致 CTA把 skill-creator 用起来按场景选入口skill-creator 跑通之后你的工作流会变成这样有新需求时先想清楚功能描述和触发场景跑一遍 generate_skill_md.py把生成的目录放进 skills/重启客户端用 /skill-name 唤起验证。整个过程几分钟比手写 SKILL.md 快很多而且字段合规性有保证。如果你主要在排障和接入阶段建议先把 API Key 和接入文档过一遍Key 在 https://taotoken.net/api-keys 创建接入细节看 https://taotoken.net/doc 。这两个入口能解决大部分 401 和端点配置问题。如果你想先验证模型是否可用、确认返回格式再写 Skill可以去 https://taotoken.net/models 用对话方式试一条请求确认 Base URL、Key、Model ID 三件套没问题再进入 Skill 开发。如果你是要长期做编码、把 Skill 当成 Agent 能力沉淀的开发者Coding Plan 更适合你入口在 https://taotoken.net/coding-plan 它面向持续编码和 Agent 场景配合 skill-creator 可以把团队规范、领域知识、工具集成逐步封装成可复用 Skill。最后给一个实用技巧skill-creator 生成的 SKILL.md 只是起点真正好用的 Skill 需要迭代。每次用 /skill-name 唤起后观察 Claude 是否按预期执行如果偏离回到 description 和正文调整措辞。description 决定触发正文决定执行质量两者分开调效率更高。把生成、验证、迭代这个循环跑顺你就能持续产出可用的 Skill而不是写完一个就搁置。
1. 为什么我要用 skill-creator 造一个自动生成 SKILL.md 的 SkillSkill 是 Anthropic 提出的一种模块化能力封装方式你可以把它理解成给 Claude 准备的“岗位入职手册”一个目录、一份 SKILL.md加上可选的脚本、参考资料和资源文件就能把某类任务的专业流程、领域知识和工具调用方式固化下来。它解决的问题很具体——上下文窗口是公共资源系统提示词、对话历史、其他 Skill 的元数据都在抢这块地方如果把所有领域知识都塞进主提示词Token 消耗会迅速失控。Skill 用三级加载机制缓解这个问题name 和 description 常驻上下文SKILL.md 正文只在触发后加载scripts/references/assets 则按需读取甚至直接执行而不进上下文。那为什么还要再套一层做一个“自动生成 SKILL.md 的 Skill”因为手写 SKILL.md 这件事本身有重复劳动。每次新建一个 Skill你都要想 name 怎么起、description 怎么写才能被正确触发、正文用祈使句还是说明句、哪些内容该拆到 references、哪些该做成 scripts。这些决策有固定套路完全可以交给一个 Skill 来代劳。我这次要做的 skill-creator输入是一段功能描述和使用场景输出是一份结构合规、字段完整、可以直接放进 skills 目录被 Claude 识别的 SKILL.md顺带把目录骨架也建好。这篇文章适合三类人一是刚接触 Skill、想知道 SKILL.md 到底长什么样的新手二是已经写过几个 Skill、想把手写流程自动化的开发者三是用 Claude Code 或 Cursor 做长期编码、希望把团队规范沉淀成 Skill 的工程师。全文会给出 skill-creator 的初始化命令、SKILL.md 模板字段、自动生成脚本的可复制配置以及通过 TaoToken 统一 Key 接入 Claude 后的实际运行与报错排查。你跟着做最后能拿到一个可复用的 skill-creator并且知道它每一步为什么这么设计。需要先明确一个边界Skill 不是替代编辑器或 IDE 的东西它是给智能体用的能力包。skill-creator 生成的也是给 Claude 读的文件不是给人看的文档站。所以下面所有配置都围绕“让另一个 Claude 实例能高效执行任务”这个目标来写。2. TaoToken 前置统一 Key 接入 Claude 的准备与 skill-creator 目录规划在动手写 skill-creator 之前先把运行环境理顺。Skill 的调用依赖 Claude 能读到 skills 目录而 Claude 的请求要走一个稳定的入口。我用 TaoToken 做统一 Key 接入好处是 Base URL、Key、Model ID 三件套集中管理切换模型或换项目时不用到处改配置。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个就行。先说清楚 Skill 的目录约定。Claude Code 和 Cursor 都会在项目的 skills 目录下扫描子文件夹每个子文件夹是一个 Skill里面必须有 SKILL.md。skill-creator 自己也是一个 Skill所以它的目录结构是skills/ └── skill-creator/ ├── SKILL.md ├── scripts/ │ ├── init_skill.py │ └── generate_skill_md.py ├── references/ │ └── skill-spec.md └── assets/ └── skill-template.md这里有个容易踩的坑很多人把 SKILL.md 直接放在 skills 根目录结果 Claude 扫描不到。必须是 skills//SKILL.md 这种两级结构。skill-creator 的 name 字段就填 skill-creatordescription 要写清楚“当用户想要创建新 Skill 或更新现有 Skill 时使用”因为 description 是 Claude 判断是否触发的唯一依据正文里的“何时使用”对触发没有帮助正文只在触发后才加载。接下来准备 TaoToken 的接入配置。如果你用 Claude Code配置通常写在 settings.json 或环境变量里如果用 Cline 这类插件会有一个 MCP 或 provider 配置。核心三件套是配置项值说明Base URLhttps://taotoken.net/api不带 UTM末尾不要多加斜杠API Key在控制台创建形如 sk-xxx只显示一次Model ID按控制台可用列表填例如 claude-sonnet 系列标识API Key 的创建入口在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。我建议先把 Key 创建好、复制到安全的地方再去写 skill-creator否则脚本跑起来会卡在鉴权上。如果你还没决定用哪个模型可以先去 https://taotoken.net/models 用对话方式验证一下模型是否可用确认能正常返回再进入编码环节。还有一个前置动作确认你的 Claude 客户端版本支持 Skill。较新的 Claude Code 和 Cursor 都支持通过 /skill-name 唤起 Skill。如果你的版本里没有 skills 目录概念那 skill-creator 生成的文件也不会被加载这时候要先升级客户端。这一步别跳过我见过有人写了半天 SKILL.md结果客户端根本不扫这个目录。环境理顺后skill-creator 的定位就清晰了它是一个“元 Skill”本身不处理业务只负责把用户的自然语言描述转成合规的 SKILL.md 和目录骨架。它的 scripts 里放两个 Python 脚本references 里放 Skill 规范说明assets 里放模板文件。下面进入具体配置。3. 可复制配置skill-creator 的 SKILL.md 模板字段与自动生成脚本这一节是全文的核心给出可以直接复制粘贴的配置。先写 skill-creator 自己的 SKILL.md再写它用来生成其他 SKILL.md 的脚本。3.1 skill-creator 的 SKILL.md 头部与正文SKILL.md 的 YAML frontmatter 只允许 name 和 description 两个字段不要加别的。description 要把“做什么”和“何时用”都写进去因为这是触发依据。下面这份可以直接用--- name: skill-creator description: 生成合规 Skill 的指南与脚本。当用户想要创建新 Skill、更新现有 Skill或需要把某类工作流、领域知识、工具集成封装成 SKILL.md 时使用。支持从功能描述自动生成 SKILL.md、目录骨架和示例资源。 --- # Skill Creator ## 概述 本 Skill 用于把用户的自然语言描述转换为符合 Anthropic Skill 规范的目录结构和 SKILL.md 文件。 ## 使用流程 1. 收集用户对目标 Skill 的功能描述、使用场景和示例用法。 2. 运行 scripts/init_skill.py 初始化目录骨架。 3. 运行 scripts/generate_skill_md.py 生成 SKILL.md。 4. 根据 references/skill-spec.md 校验字段合规性。 5. 提示用户把生成目录放入 skills/ 下并重启客户端。 ## 生成 SKILL.md 的规则 - frontmatter 只包含 name 和 description。 - description 必须包含功能说明和触发条件。 - 正文使用祈使句控制在 500 行以内。 - 详细参考资料放 references/可执行逻辑放 scripts/输出模板放 assets/。 - 不生成 README.md、CHANGELOG.md 等辅助文档。注意正文里没有“何时使用此 Skill”这种段落因为那部分信息已经在 description 里了正文写它属于浪费上下文。3.2 初始化脚本 init_skill.py这个脚本负责建目录、写占位文件。路径参数用绝对路径更稳避免相对路径在不同工作目录下解析错乱。#!/usr/bin/env python3 import argparse import os from pathlib import Path TEMPLATE --- name: {name} description: TODO 填写功能说明与触发条件 --- # {title} ## 概述 TODO 描述这个 Skill 解决什么问题。 ## 使用流程 1. TODO def init_skill(name: str, out_dir: str) - None: root Path(out_dir).expanduser().resolve() / name if root.exists(): raise SystemExit(f目录已存在: {root}) for sub in (scripts, references, assets): (root / sub).mkdir(parentsTrue, exist_okTrue) (root / SKILL.md).write_text( TEMPLATE.format(namename, titlename.replace(-, ).title()), encodingutf-8, ) print(f已初始化: {root}) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(name, helpSkill 名称使用小写连字符) parser.add_argument(--path, default./skills, help输出目录) args parser.parse_args() init_skill(args.name, args.path)运行方式python3 scripts/init_skill.py article-title --path ./skills执行后会在 ./skills/article-title 下生成 SKILL.md 和三个空目录。这里有个细节脚本用raise SystemExit而不是直接覆盖是为了防止误删已有 Skill。如果你确实要重建先手动删目录。3.3 自动生成 SKILL.md 的脚本 generate_skill_md.py这个脚本接收功能描述、场景、示例拼出合规的 SKILL.md。它把 description 的构造逻辑单独抽出来确保“何时使用”一定进 description。#!/usr/bin/env python3 import argparse from pathlib import Path FRONTMATTER --- name: {name} description: {description} --- BODY # {title} ## 概述 {overview} ## 使用流程 {steps} ## 示例 {examples} def build_description(name: str, func: str, scene: str) - str: return ( f{func}。当用户需要{scene}时使用此 Skill f它通过封装专业流程和可复用资源来扩展 Claude 的能力。 ) def generate(name: str, func: str, scene: str, overview: str, steps: str, examples: str, out_dir: str) - None: root Path(out_dir).expanduser().resolve() / name root.mkdir(parentsTrue, exist_okTrue) desc build_description(name, func, scene) content FRONTMATTER.format(namename, descriptiondesc) content BODY.format( titlename.replace(-, ).title(), overviewoverview, stepssteps, examplesexamples, ) (root / SKILL.md).write_text(content, encodingutf-8) print(f已生成: {root / SKILL.md}) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(name) parser.add_argument(--func, requiredTrue, help功能说明) parser.add_argument(--scene, requiredTrue, help触发场景) parser.add_argument(--overview, defaultTODO 概述) parser.add_argument(--steps, default1. TODO) parser.add_argument(--examples, defaultTODO 示例) parser.add_argument(--path, default./skills) args parser.parse_args() generate(args.name, args.func, args.scene, args.overview, args.steps, args.examples, args.path)调用示例python3 scripts/generate_skill_md.py article-title \ --func 根据主题生成文章标题候选 \ --scene 需要为技术文章拟定标题 \ --overview 输入主题关键词输出 5 个候选标题。 \ --steps 1. 读取主题关键词\n2. 按风格生成候选\n3. 输出列表 \ --examples 输入: Skill 开发输出: 5 个标题 \ --path ./skills跑完后 ./skills/article-title/SKILL.md 就是一份字段完整、description 含触发条件的文件。你可以直接把它放进客户端的 skills 目录。3.4 通过 TaoToken 接入 Claude 的配置片段如果你用 Claude Codesettings 里配置 provider 的部分大致如下字段名以你客户端版本为准核心是 Base URL、Key、Model ID 三件套{ provider: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet } }如果你用 Cline 的 MCP 配置写法类似把 baseUrl 指向 https://taotoken.net/api apiKey 填控制台创建的 Keymodel 填可用模型标识。Codex 的 auth.json 则是把 Key 和 base URL 写进对应字段。三件套缺一不可只填 Key 不填 Base URL 会走到默认端点只填 Base URL 不填 Model ID 会报模型不存在。配置完成后把 skill-creator 目录放到 skills/ 下重启客户端输入 /skill-creator 应该能看到它被唤起。下一节验证实际请求。4. 验证请求在 Claude 中调用 skill-creator 并检查生成结果配置写完必须验证否则你不知道是 Skill 没被加载还是 Key 鉴权失败还是脚本报错。验证分三步先确认 Skill 被识别再确认脚本能跑最后确认生成的 SKILL.md 能被另一个 Skill 场景消费。第一步确认 Skill 被识别。重启客户端后在对话里输入 /skill-creator如果客户端支持 Skill 列表应该能看到它出现在候选里。如果看不到检查三件事目录是不是 skills/skill-creator/SKILL.md 两级结构frontmatter 的 name 是不是 skill-creatordescription 是不是非空。这三个任一不满足Skill 都不会被加载。第二步确认脚本能跑。在 skill-creator 目录下执行python3 scripts/init_skill.py demo-skill --path ./skills python3 scripts/generate_skill_md.py demo-skill \ --func 演示用功能 \ --scene 演示触发场景 \ --path ./skills预期输出是两行“已初始化”和“已生成”。如果报ModuleNotFoundError说明 Python 环境缺依赖这两个脚本只用标准库正常不会缺如果报权限错误检查输出目录是否可写。跑完后用cat ./skills/demo-skill/SKILL.md看一眼frontmatter 里 name 和 description 都在description 里包含“当用户需要……时使用此 Skill”。第三步确认生成的 Skill 能被消费。把 demo-skill 放进客户端的 skills 目录重启输入 /demo-skill看是否能唤起。这一步验证的是“生成的 SKILL.md 格式合规”如果唤起失败多半是 description 写得太泛Claude 判断不出触发时机。回到 generate_skill_md.py 的 build_description 函数把场景写得更具体。第四步验证 TaoToken 接入是否正常。在对话里发一条普通请求比如“你好确认一下连接”如果返回正常说明 Base URL、Key、Model ID 三件套生效。如果返回 401是 Key 问题如果返回模型不存在是 Model ID 问题如果返回连接超时是 Base URL 或网络问题。这一步和 Skill 验证要分开做否则出错时你分不清是 Skill 的问题还是接入的问题。我实测下来最容易出问题的是 description 的触发条件写得太模糊。比如只写“生成 SKILL.md”Claude 可能在你问“帮我写个文档”时也触发它。解决办法是在 description 里加限定词比如“当用户明确要求创建或更新 Skill 时使用”。这个细节直接决定 Skill 的可用性。验证通过后你就有了一个能自动生成 SKILL.md 的 skill-creator。接下来把它用到真实场景输入一段功能描述让它生成一个新 Skill再把新 Skill 放进目录测试。这个闭环跑通说明整条链路没问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照这一节按真实报错来排。Skill 开发和 TaoToken 接入叠在一起出错时信息容易混我按报错原文分类你对着找。401 Unauthorized。这是鉴权失败和 Skill 本身无关。检查 API Key 是否复制完整、是否有多余空格、是否已过期。TaoToken 的 Key 在控制台创建后只显示一次如果没保存只能重建。另外确认 Base URL 填的是 https://taotoken.net/api 如果误填成带 UTM 的官网地址鉴权会失败。Key 创建入口在 https://taotoken.net/api-keys 。local proxy failed / connection refused。这类报错通常是本地代理配置残留。检查环境变量里有没有 HTTP_PROXY、HTTPS_PROXY 指向一个已经关掉的本地端口。如果有清掉再试。注意这里说的是清理本地环境变量不是让你去配什么网络工具把不该有的代理项删掉即可。另外确认 Base URL 没有拼错末尾不要多加斜杠。reading choices 相关报错。这通常出现在响应体解析阶段说明请求发出去了、也返回了但返回结构不符合客户端预期。常见原因是 Model ID 填错客户端拿到的不是对话补全格式。去 https://taotoken.net/models 确认可用模型标识把配置里的 model 字段改成正确的。如果用的是 Cline 的 MCP 配置检查 MCP 返回格式是否被正确解析。OAuth 相关报错。如果你用的是 Claude Code 且走了 OAuth 流程报错可能是 token 刷新失败。这时候改用 API Key 方式接入更直接把三件套配好即可。OAuth 和 API Key 不要混用混用会导致鉴权头冲突。Skill 不触发。不是报错但很常见。检查 SKILL.md 的 frontmatter 是否只有 name 和 description多写字段可能导致解析失败检查 description 是否包含明确的触发条件检查目录层级是否是 skills//SKILL.md。如果都正常重启客户端再试有些版本需要重启才重新扫描 skills 目录。脚本执行报 FileNotFoundError。检查 --path 参数指向的目录是否存在init_skill.py 不会自动创建父目录之外的层级。用绝对路径最稳。生成的 SKILL.md 里 description 为空。检查 generate_skill_md.py 的 --func 和 --scene 是否都传了build_description 依赖这两个参数。如果只传一个拼出来的 description 会缺半句。排错时建议按“先接入、后 Skill”的顺序先用一条普通请求确认 TaoToken 三件套正常再验证 Skill 加载最后验证脚本生成。这样出错时能快速定位是哪一层的问题。接入相关的文档在 https://taotoken.net/doc 遇到鉴权或端点问题可以先查这里。6. 语义一致 CTA把 skill-creator 用起来按场景选入口skill-creator 跑通之后你的工作流会变成这样有新需求时先想清楚功能描述和触发场景跑一遍 generate_skill_md.py把生成的目录放进 skills/重启客户端用 /skill-name 唤起验证。整个过程几分钟比手写 SKILL.md 快很多而且字段合规性有保证。如果你主要在排障和接入阶段建议先把 API Key 和接入文档过一遍Key 在 https://taotoken.net/api-keys 创建接入细节看 https://taotoken.net/doc 。这两个入口能解决大部分 401 和端点配置问题。如果你想先验证模型是否可用、确认返回格式再写 Skill可以去 https://taotoken.net/models 用对话方式试一条请求确认 Base URL、Key、Model ID 三件套没问题再进入 Skill 开发。如果你是要长期做编码、把 Skill 当成 Agent 能力沉淀的开发者Coding Plan 更适合你入口在 https://taotoken.net/coding-plan 它面向持续编码和 Agent 场景配合 skill-creator 可以把团队规范、领域知识、工具集成逐步封装成可复用 Skill。最后给一个实用技巧skill-creator 生成的 SKILL.md 只是起点真正好用的 Skill 需要迭代。每次用 /skill-name 唤起后观察 Claude 是否按预期执行如果偏离回到 description 和正文调整措辞。description 决定触发正文决定执行质量两者分开调效率更高。把生成、验证、迭代这个循环跑顺你就能持续产出可用的 Skill而不是写完一个就搁置。
