从零写一个 Claude Skill：文件夹结构、SKILL.md 写法和测试全流程

一篇手把手教程，讲清如何为 Claude 和 Claude Code 构建自己的 Skill：从选任务、建文件夹、写 front matter，到写出让模型愿意加载的 description、加脚本、测试和分享。步骤具体、有示例代码和常见坑，读完就能照着做一个。

什么样的任务值得做成 Skill

• 好 Skill 来自重复：那些你不止一次向 Claude 解释、有固定做法、一句话说不清的任务
• 适合的场景：按团队格式从 merged PR 写 release notes、按 checklist 审 PR、从固定数据源出周报、按设计系统写 UI
• 不需要 Skill 的：单一偏好应放进 CLAUDE.md 或自定义指令；Agent 够不着的系统则该用 MCP server

建文件夹和写 front matter

• Skill 就是一个以 Skill 名命名的文件夹，里面放 SKILL.md；名字只能小写字母、数字和连字符，最长 64 字符
• 个人 Skill 放 ~/.claude/skills/，项目级放仓库的 .claude/skills/；Codex 读 ~/.agents/skills/，Gemini CLI 读 ~/.gemini/skills/
• YAML 必填两个字段：name 必须与文件夹名完全一致，description 最长 1024 字符，要说明做什么、何时用
• Claude Code 扩展字段：disable-model-invocation: true 让 Skill 只能手动 /调用；allowed-tools 可列出免确认的工具

description 决定 Skill 会不会被加载

• Skill 未加载前，模型只能看到名字和 description，所以这一步最关键也最容易被草率带过
• 三个习惯：用动词开头写清做什么；加一句 Use when...，包含用户实际会打的词和同义词（release notes、changelog、what shipped）；明确边界，避免被错误任务触发
• 对比示例："PDF helpers" 太空泛，"Fills, merges and splits PDF files... Use when the user asks to fill a form..." 才能被正确匹配

写指令正文和脚本

• 正文用平铺直叙的 Markdown，像给一个能干但没见过项目的同事做简报；编号步骤优于段落，具体例子优于抽象规则
• 正文控制在约 5000 token（Claude Code 文档建议 500 行以内），超出的内容移到 references/ 参考文件，按需加载
• 判断类任务靠指令就够；输出必须精确的场景（解析文件格式、固定命令序列、校验）用 scripts/ 里的脚本更可靠
• 脚本要短、可读，因为它们以 Agent 权限运行；目录里约三分之一的 Skill 只有一个 SKILL.md，没有脚本也完全没问题

测试、上传到 claude.ai 和分享

• 两步测试：先开新会话用同事的口吻提需求（不点名 Skill），看它是否自动加载，验证 description；再用 /release-notes 直接调用，验证指令本身
• 把每次偏离都改写成更清晰的步骤或例子，两三轮通常就能从「大致对」到「按我们的方式做」
• 加载失败的常见原因：文件夹嵌套过深、name 与文件夹不一致、YAML 格式错误
• claude.ai 用法：把 Skill 文件夹打成 ZIP（文件夹名须与 name 一致），在 Customize → Skills → Create skill 里上传；需要开启代码执行，Team/Enterprise 由管理员控制

一个真实案例

• 作者团队用一个编码了项目规划习惯的 Skill，把「规划一个目录站」这种模糊请求变成固定的十份文档流程
• 每次新项目都复用同一套：写哪些文档、按什么顺序、每份要包含什么、记录哪些决策——这正是 Skill 最擅长的用法