1. 为什么技能骨架要在写代码前定好很多人第一次做 Claude 技能习惯直接打开编辑器写脚本结果写到一半发现触发词没想清楚、文件放错位置、YAML 字段漏了最后技能加载不出来只能推倒重来。我试过最省事的做法其实是先把「规划与设计」这一步做扎实用一份 SKILL.md 加一段 YAML 前置元数据把技能的用途、触发条件、执行步骤全部写清楚再动手补脚本。这一章要解决的就是这件事。它适合已经在本地折腾 Claude 技能包、想让技能可复用、可被自动触发的开发者。核心检索词就三个Claude 技能构建、Planning and Design、SKILL.md 与 YAML。读完你能拿到一份可直接复制的骨架并且用 TaoToken 统一 Key 跑通一次技能加载与调用验证确认结构没问题再进入编码阶段。规划阶段真正要产出的不是代码而是三样东西2 到 3 个具体用例、一份成功标准、一份符合硬性规则的文件结构。下面按这个顺序拆开讲每一步都给可复制的配置。2. TaoToken 前置统一 Key 与 API 通道技能在本地加载和调用时最终都要走一次模型请求来验证触发是否正常。如果每个技能各自配一套 Key管理起来会很乱。我的做法是用 TaoToken 作为统一入口一个 Key 覆盖模型对话和后续的编码类调用技能包里只引用环境变量不硬编码密钥。你需要先拿到 Key。打开控制台页面创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_planning_console创建完成后进入 API Keys 页面复制密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_planning_apikeys接口地址统一用https://taotoken.net/api注意这个地址不带任何查询参数。把 Key 写进本地环境变量技能脚本里只读变量export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意不要把 Key 直接写进 SKILL.md 或 scripts 里的代码。技能包经常会被复制、分享硬编码密钥等于泄露。用环境变量是最低成本的隔离方式。如果你后续要做长期编码类技能或 Agent 工作流可以了解 Coding Plan它更适合高频调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_planning_codingplan3. 可复制配置SKILL.md 与 YAML 骨架3.1 文件结构先定死规划阶段第一件事是把目录结构画出来。Claude 技能对结构有硬性要求写错一个字母就加载失败。标准结构如下your-skill-name/ ├── SKILL.md # 必选主指令文件 ├── scripts/ # 可选可执行代码 │ └── process_data.py ├── references/ # 可选参考文档 │ └── api-guide.md └── assets/ # 可选模板/字体/图标 └── report-template.md三条硬性规则必须记住。第一主文件名严格是SKILL.md大小写敏感skill.md、SKILL.MD都不行。第二技能文件夹名只能用短横线命名法比如notion-project-setup禁止空格、下划线、大写字母。第三技能文件夹内不能放README.md文档统一写进 SKILL.md 或 references 目录。3.2 YAML 前置元数据YAML frontmatter 是 Claude 判断是否加载技能的唯一依据也是渐进式披露的第一层。最简必填格式只有两个字段--- name: figma-design-handoff description: 分析 Figma 设计文件并生成开发交接文档。当用户上传 .fig 文件、询问「设计规格」「组件文档」或「设计转代码交接」时使用。 ---字段要求逐条对照字段是否必填规则name必填仅 kebab-case无空格大写必须与文件夹名完全一致description必填用途加触发条件字符数不超过 1024禁止 XML 尖括号license可选开源技能标注常用 MIT、Apache-2.0compatibility可选1 到 500 字符标注环境要求与依赖metadata可选自定义键值对建议含 author、version、mcp-server安全限制是强制的元数据里禁止出现 XML 尖括号技能名称禁止包含claude、anthropic这类官方保留词。原因是元数据会被加载进系统提示词恶意内容可能造成指令注入。3.3 description 的写法决定触发率description 不是随便写一句用途就行它要同时承担「说明技能做什么」和「告诉 Claude 什么时候加载」两个职责。标准结构是技能用途加触发场景加核心能力。优质示例description: 管理 Linear 项目工作流覆盖冲刺规划、任务创建、状态跟踪。当用户提及「冲刺」「Linear 任务」「项目规划」或要求「创建工单」时使用。劣质示例要避开三种坑。过于模糊的比如「协助处理项目相关工作」缺少触发条件的比如「生成复杂多页文档系统」技术化但没有触发词的比如「实现带层级关系的项目实体模型」。这三种写法都会让技能在需要时加载不出来。3.4 SKILL.md 正文模板正文按步骤写每步包含执行动作、代码示例、预期结果。骨架如下# Figma 设计交接 ## 操作指令 ### 步骤1读取设计文件 调用脚本解析 .fig 文件提取图层与组件信息。 bash python scripts/parse_figma.py --file design.fig预期输出返回图层树 JSON包含组件名与尺寸。步骤2生成交接文档基于图层树生成 Markdown 交接文档引用 assets 中的模板。python scripts/gen_handoff.py --input layers.json --template assets/report-template.md预期输出生成 handoff.md包含组件规格与代码片段。步骤3错误处理若文件解析失败检查 .fig 版本是否受支持并提示用户重新导出。正文里引用参考文件时用相对路径指向 references 目录不要复制大段内容进 SKILL.md保持主文件精简。 ## 4. 验证请求跑通一次技能加载与调用 骨架写完后先别急着写复杂脚本用一次最小请求验证结构是否正确。下面这段 Python 读取环境变量向 TaoToken 接口发一次请求模拟技能被触发时的调用路径 python import os import requests api_key os.environ[TAOTOKEN_API_KEY] base_url os.environ[TAOTOKEN_BASE_URL] payload { model: claude-sonnet-4-20250514, messages: [ { role: user, content: 请根据技能描述判断是否加载 figma-design-handoff 技能并说明触发理由。 } ] } resp requests.post( f{base_url}/v1/messages, headers{ Authorization: fBearer {api_key}, Content-Type: application/json }, jsonpayload, timeout60 ) print(resp.status_code) print(resp.json())运行后如果返回 200并且响应里明确提到技能名称和触发条件说明 YAML 元数据被正确读取。如果返回 401检查 Key 是否写对返回 404检查 base_url 是否误加了路径后缀。想直接在网页端验证模型对技能描述的理解可以用模型对话页面发同样的提示词https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_planning_chat这一步的意义在于在写任何业务脚本之前先确认「技能能不能被正确识别」。识别不了后面写再多代码也没用。5. 本篇常见错排查5.1 技能加载不出来先查文件名。SKILL.md大小写必须完全一致文件夹名必须是 kebab-case。再查 YAML 是否闭合---开头和结尾都不能少。最后查 description 里有没有 XML 尖括号有的话会被安全规则拦截。5.2 触发率低description 里缺少用户常用话术。把用户可能说的原话写进去比如「设计规格」「组件文档」「设计转代码交接」而不是只写「处理设计文件」。触发词越贴近真实表达自动加载越准。5.3 请求返回 401 或 403Key 没读到或者写错了。确认环境变量名和代码里读的名字一致确认 Key 没有多余空格。TaoToken 的接口地址是https://taotoken.net/api不要在后面拼多余的路径。5.4 文件夹里放了 README.md技能文件夹内禁止 README.md这是硬性规则。把说明内容合并进 SKILL.md或者放到 references 目录里。GitHub 仓库级别的 README 可以保留但技能目录内不行。5.5 名称里带了保留词技能名不能包含claude、anthropic。改成业务相关的名字比如design-handoff、sprint-planner既避开保留词又更贴近用途。6. 下一步把规划落到接入文档规划与设计做完你手里应该有一份通过验证的 SKILL.md 骨架、一段可复制的 YAML、一次成功的加载请求。接下来进入编码阶段前建议先把接入细节对照文档过一遍确认参数和路径没有遗漏https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_planning_doc如果你用的是 Claude Code 这类编码工具接入方式略有不同可以参考对应的接入说明https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_planning_claudecode技能构建最容易返工的地方从来不是代码而是规划阶段没把触发条件和文件结构定清楚。把这一章的骨架先跑通后面写脚本就是填空。