1. 为什么“写个技能”这件事值得单独造一个工具很多人第一次接触 Claude 的 Skill 机制时脑子里冒出来的第一个念头是不就是写个 Markdown 文件吗我手搓一个不就完了。我一开始也是这么想的直到我连续写了七八个 Skill 之后发现真正让人头疼的根本不是“写文件”这个动作而是怎么把一个模糊的需求拆成 Claude 能稳定执行的指令结构。Skill 的本质是一份给模型看的“操作手册”它由SKILL.md主文件和若干附属资源组成。主文件里最关键的字段是name和description前者决定技能叫什么后者决定 Claude 在什么场景下会想起调用它。问题就出在这个description上——写得太宽泛Claude 会在不该用的时候乱用写得太窄该用的时候它又想不起来。这个度靠拍脑袋是拍不准的。skill-creator这个工具的价值就在这里。它不是帮你“生成一个文件”而是帮你走完一整套从需求澄清到结构落地的流程。你可以把它理解成一个专门针对 Skill 开发的脚手架加质检员它会引导你把需求说清楚帮你判断这个技能到底该不该做成 Skill然后按照规范生成目录结构和初始内容最后还会做一轮校验。这篇文章适合三类人看一是刚上手 Claude、还没写过 Skill 的新手二是写过几个 Skill 但总觉得效果不稳定的中级用户三是想把团队内部流程沉淀成 Skill 的工程同学。我会把整个流程拆开讲包括每一步背后的逻辑、我踩过的坑以及那些文档里不会写的细节。2. skill-creator 到底在流程里扮演什么角色2.1 它解决的不是“写”而是“想清楚”大部分人以为 skill-creator 是个代码生成器输入一句话就吐出一个技能。实际用下来你会发现它更像一个结构化的需求访谈器。你运行它之后它不会立刻给你生成文件而是先问你几个问题这个技能要解决什么问题触发场景是什么有没有现成的参考资料需不需要附带脚本或模板这几个问题看着简单但每一个都直击要害。我见过太多人上来就说“我要做一个处理 Excel 的技能”结果聊到第三句就发现他真正想要的是“把固定格式的周报 Excel 转成 Markdown 摘要”。这两个需求的 Skill 结构完全不一样前者需要泛化的表格处理能力后者只需要一个针对特定列名的转换脚本。提示如果你在 skill-creator 的问答环节里答不上来“触发场景”那大概率说明这个需求还不适合做成 Skill先回去把需求想清楚再说。2.2 它和手写 SKILL.md 的核心差异手写和用工具走流程差别主要体现在三个地方。第一是目录结构的规范性。一个标准的 Skill 目录长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── helper.py ├── references/ │ └── api-doc.md └── assets/ └── template.docxSKILL.md是必须的其余三个目录按需存在。scripts放可执行脚本references放供 Claude 查阅的文档assets放模板、字体这类静态资源。手写的时候很容易漏掉某个目录或者把该放 references 的东西塞进了 assets导致 Claude 读取时找不到。第二是frontmatter 字段的完整性。SKILL.md开头那段用---包起来的部分叫 frontmatter里面至少要写name和description。这两个字段的写法有讲究name建议用小写加连字符description要同时说清楚“做什么”和“什么时候用”。第三是渐进式披露的设计。这是 Skill 机制里最容易被忽略的一点。Claude 不会一次性把所有文件都读进上下文而是先读SKILL.md需要的时候再去读 references 里的具体文档。所以SKILL.md应该写得精炼把详细内容外链到 references 里。skill-creator 在生成时会自动帮你做这个拆分。2.3 什么需求适合做成 Skill什么不适合这是我在实际使用中总结出来的判断标准分享给你需求特征适合做成 Skill不适合做成 Skill触发频率高频重复一次性任务流程稳定性步骤固定每次都不一样知识密度需要特定领域知识通用常识即可输出格式有明确格式要求自由发挥依赖资源需要脚本或模板纯文本对话举个例子“把会议录音转成结构化纪要”适合做成 Skill因为流程固定、格式明确、高频使用。而“帮我写一篇关于某个话题的文章”就不适合因为每次的话题和风格要求都不同做成 Skill 反而会限制发挥。3. 从零跑一遍完整流程我实际操作的每一步3.1 环境准备与工具获取skill-creator 本身也是一个 Skill这个设计挺有意思的——用 Skill 来造 Skill。获取方式通常是从官方仓库或者团队内部共享目录拿到它的源码目录然后放到你的 Claude 技能加载路径下。在 Claude Code 环境下技能一般放在项目根目录的.claude/skills/下或者用户级的~/.claude/skills/下。放好之后你可以通过对话让 Claude 列出当前可用的技能确认 skill-creator 已经被识别到。注意如果你用的是桌面版 Claude技能目录的位置和 Code 版不一样具体路径建议查一下当前版本的文档。我遇到过有人把技能放错目录然后纳闷为什么 Claude 一直说找不到技能。3.2 启动对话怎么描述你的需求启动 skill-creator 之后第一句话很关键。我的建议是用一句话说清楚“输入是什么、输出是什么”而不是描述一个模糊的愿望。对比一下这两种说法差的说法“我想做一个帮我处理文档的技能。”好的说法“我想做一个技能输入是一个包含多级标题的 Markdown 文档输出是把这个文档的标题层级重构成符合某个规范的格式并且生成一份目录。”后一种说法直接给出了输入类型、输出类型和核心操作skill-creator 就能据此判断需要哪些脚本、需要哪些参考文档。3.3 需求澄清阶段的几个关键问答这个阶段 skill-creator 会追问细节我挑几个最常被问到的问题说说怎么答。“这个技能的触发词是什么”这个问题是在帮你打磨description。你要给出几个典型的用户会说的话比如“帮我重构文档标题”“整理一下这个 Markdown 的层级”。这些短语会直接影响 Claude 判断何时调用这个技能。“需要附带可执行脚本吗”如果技能涉及确定性计算、格式转换、文件操作答案是需要的。纯文本处理类的技能可以不带脚本但一旦涉及“把 A 格式转成 B 格式”这种确定性任务写个 Python 脚本比让模型自由发挥靠谱得多。“有没有现成的参考资料”比如你公司内部的编码规范、API 文档、模板文件。有的话就放进 references 或 assets没有的话 skill-creator 会帮你生成一个占位文件你后续再填。3.4 生成结果的结构解读跑完流程后你会得到一个完整的技能目录。我拿一个实际生成的例子来说明每个部分的作用doc-restructurer/ ├── SKILL.md ├── scripts/ │ └── restructure.py └── references/ └── heading-spec.mdSKILL.md里的 frontmatter 大概长这样--- name: doc-restructurer description: 重构 Markdown 文档的标题层级。当用户需要整理文档结构、统一标题格式、生成目录时使用。 ---正文部分会写清楚执行步骤先读取文档识别当前标题层级对照references/heading-spec.md里的规范调用scripts/restructure.py做转换最后输出结果。scripts/restructure.py是一个可执行的 Python 脚本负责具体的文本处理逻辑。references/heading-spec.md里放的是标题规范的具体说明比如“一级标题用#二级用##最多不超过四级”这类规则。3.5 生成之后的第一次实测生成完不代表就完事了必须实测。我的做法是准备三个测试用例一个标准输入、一个边界输入比如标题层级跳跃的文档、一个异常输入比如根本没有标题的文档。实测的时候重点观察两件事一是 Claude 有没有在合适的时机调用这个技能二是调用之后输出是否符合预期。如果第一点不满足回去改description如果第二点不满足回去改脚本或参考文档。4. description 字段决定技能生死的那几行字4.1 为什么 description 比正文还重要这是我在踩了无数次坑之后才明白的道理Claude 决定要不要用某个技能几乎完全依赖description。正文写得再漂亮如果description没写好技能就是摆设。原因在于 Skill 的加载机制。Claude 在对话开始时只会把所有可用技能的name和description加载进上下文正文内容是按需读取的。所以description是唯一一个“永远在场”的字段它承担了全部的触发判断职责。4.2 一个好的 description 包含哪三个要素我总结了一个模板包含三个要素能力描述这个技能能做什么触发场景什么情况下应该用它边界说明什么情况下不该用它可选但推荐举个例子description: 将会议记录整理成结构化纪要包含议题、结论、待办事项三个部分。当用户提供会议录音转写文本或会议笔记需要生成正式纪要时使用。不适用于实时会议记录场景。这三句话分别对应了能力、场景和边界。实测下来带边界说明的description误触发率明显更低。4.3 常见写法对比宽泛 vs 精准写法示例问题过于宽泛“处理文档相关任务”几乎所有文档任务都会触发噪音大过于狭窄“处理 2024 年 Q3 销售周报”换个季度就失效只写能力“生成 Markdown 目录”不知道什么时候该用能力场景“生成 Markdown 目录。当用户需要为长文档添加导航目录时使用”相对合理能力场景边界上面那个三要素版本最推荐4.4 迭代 description 的实操方法我的做法是维护一个“触发测试集”里面放 10 到 20 条用户可能说的话其中一半应该触发这个技能一半不应该。每次改完description就拿这个测试集跑一遍看触发准确率有没有提升。这个测试集不用很正式一个 Markdown 表格就行用户输入期望触发实际触发“帮我把这份会议记录整理一下”是是“这个文档太长了加个目录”是是“帮我写个会议通知”否否跑几轮下来description的措辞就会越来越准。5. 脚本、参考文档与渐进式披露的配合5.1 什么逻辑该放进脚本什么该留给模型这是设计 Skill 时最核心的架构决策。我的原则是确定性的、可验证的逻辑放脚本需要理解和判断的逻辑留给模型。比如格式转换、数据校验、文件读写这类任务写脚本。因为脚本的输出是确定的不会因为模型状态波动而变化。而像“判断这段文字属于哪个议题”“总结这段话的核心观点”这类任务留给模型因为脚本写不出这种灵活性。5.2 references 目录的正确用法references目录是给 Claude 按需查阅的知识库。它的存在意义是避免把所有细节都塞进SKILL.md导致主文件臃肿。一个常见的错误是把references当成“随便放点文档的地方”。正确的用法是SKILL.md里明确写出“当需要 X 信息时查阅references/xxx.md”。这样 Claude 才知道什么时候该去读哪个文件。5.3 渐进式披露带来的上下文优化渐进式披露的好处是省上下文。假设你有一个技能主文件 500 字参考文档 5000 字。如果全部塞进主文件每次对话都要吃掉 5500 字的上下文。而用渐进式披露平时只吃 500 字需要的时候才去读那 5000 字。对于技能数量多的用户这个优化非常明显。我自己的技能库里有十几个技能如果每个都全量加载上下文早就爆了。5.4 一个完整技能目录的拆解示例拿一个“代码审查”技能举例code-reviewer/ ├── SKILL.md # 主文件写清流程和触发条件 ├── scripts/ │ ├── lint_runner.py # 跑静态检查 │ └── diff_parser.py # 解析代码 diff ├── references/ │ ├── review-checklist.md # 审查清单 │ └── style-guide.md # 团队编码规范 └── assets/ └── report-template.md # 审查报告模板SKILL.md里会写先跑lint_runner.py再解析 diff对照review-checklist.md逐项检查最后用report-template.md生成报告。每个文件各司其职Claude 按需读取。6. 实测中暴露的问题与我的修复思路6.1 技能不触发从 description 找原因技能不触发是最常见的问题。排查顺序是这样的先确认技能目录位置对不对再确认SKILL.md的 frontmatter 格式有没有问题最后看description的措辞。我遇到过一次技能死活不触发最后发现是 frontmatter 里的name字段用了大写字母而 Claude 匹配时对大小写敏感。改成小写加连字符之后立刻正常了。6.2 技能乱触发边界说明缺失乱触发通常是因为description写得太宽泛。修复方法是在description末尾加一句“不适用于 XXX 场景”。这句话的作用是给 Claude 一个排除条件。6.3 脚本执行失败路径与依赖问题脚本执行失败最常见的原因是路径问题。脚本里如果用相对路径要确认它是相对于技能目录还是相对于工作目录。我的习惯是在脚本开头统一把工作目录切换到脚本所在目录避免路径混乱。依赖问题也很常见。如果脚本用了第三方库要么在技能文档里写清楚依赖要么干脆用标准库重写。我倾向于后者因为少一个依赖就少一个出错点。6.4 输出不稳定把判断逻辑收进脚本如果同一个输入技能每次输出都不一样说明有本该确定性的逻辑留给了模型。修复方法是把这段逻辑抽出来写成脚本。比如“提取文档里所有二级标题”这种任务用正则表达式在脚本里做比让模型自己找靠谱得多。7. 把技能沉淀成可复用资产的几点心得7.1 命名与版本管理技能名建议用“领域-动作”的格式比如doc-restructurer、code-reviewer。这样一眼就能看出技能是干什么的。版本管理方面我习惯在SKILL.md的 frontmatter 里加一个version字段虽然 Claude 不读它但方便自己追踪。每次改动description或脚本逻辑就升一个版本号。7.2 团队共享时的注意事项团队共享技能时最大的问题是依赖不一致。我的做法是在技能目录里放一个README.md写清楚这个技能依赖哪些环境、需要哪些权限、怎么验证安装成功。另外共享技能时description要写得更保守一些因为不同人的使用习惯不一样宽泛的description在团队场景下更容易造成误触发。7.3 持续迭代的触发测试集前面提到的触发测试集我建议长期维护。每次技能出问题就把那个 case 加进测试集。时间长了这个测试集就成了技能的质量保障网。7.4 从单个技能到技能库的组织技能多了之后组织方式就很重要。我按领域分目录比如writing/、coding/、data/每个目录下放对应的技能。这样查找和加载都方便。另外技能之间可以互相引用。比如一个“周报生成”技能可以调用“文档重构”技能的能力。这种组合能让技能库的整体能力远超单个技能之和。最后分享一个我自己的小习惯每写完一个技能我会隔一天再回来用它一次。隔一天的好处是我已经忘了自己当时是怎么设计的这时候用起来如果觉得别扭那就说明设计有问题需要改。这个“隔夜测试”帮我发现了不少设计缺陷。