1. Claude Skills 是什么主文件为什么值得单独研究先聊一个很多人容易忽略的事实Claude Skills 并不是什么黑魔法它本质上是一套“让 Claude 在特定场景下按固定套路干活”的能力包。你可以把它理解成一个岗位说明书——不是一次性对话里随口说一句“你帮我总结一下”而是把一类任务的处理方式、判断标准、输出模板全部固化下来让 Claude 拿到任务后自动按照这套流程执行。我这里说的“主文件”指的是技能包里的核心定义文件通常叫SKILL.md。见过太多人把精力花在写零散的 prompt 上结果换个场景就失灵也有人直接把一大段系统提示词扔进 Custom Instructions结果 Claude 一遇到稍微复杂点的任务就开始自由发挥。真正好用的 Skills核心都集中在这个主文件里它既要告诉 Claude“什么时候该用这项技能”又要告诉它“具体怎么干”还要给它“能抄的作业”。这套机制最打动我的地方在于它把“能力”和“指令”拆开了。普通 prompt 是“你说什么它做什么”而 Skill 是“你封装好一套能力Claude 在合适的时机自己调用”。主文件写得清不清楚直接决定了技能是被稳定复用还是偶尔灵光一现。我前后编写和改写过几十个技能文件踩了不少坑这里把主文件的编写思路、结构设计和实操细节完整梳理一遍适合正在研究 Claude Skills 的开发者也适合想把自己重复性工作交给 Claude 处理的重度用户。需要先说清楚一件事Claude Skills 的主文件不是给机器看的配置文件它是一份写给 Claude 读的 Markdown 文档。这意味着你写的每一行文字都会被模型理解而不是被语法解析器解析。所以编写主文件的核心逻辑从“写代码”变成了“写清楚一份带约束的说明书”。下面我就从结构拆解开始逐步讲透每个部分应该怎么写、为什么这么写。2. 主文件的结构设计从骨架到血肉2.1 frontmatter给 Claude 看的“身份证”主文件开头有一段 YAML 格式的 frontmatter夹在两个---之间。这段信息不会被 Claude 当作正文指令来执行而是用来做技能识别和调度的。很多人在这个阶段就犯懒随便写个 name 和 description 就完事结果技能发布后要么永远不被触发要么在技能市场里别人根本看不懂这玩意儿是干嘛的。frontmatter 里最关键的字段是name和description。name建议用全小写、短横线连接的形式比如meeting-minutes、weekly-report-helper。它相当于技能的唯一标识符命名尽量做到望文生义。我看到过有人用中文命名比如会议纪要技能虽然也能用但在一些工具链和日志系统里会出现兼容性问题包括后续做版本管理、写测试脚本都会麻烦。description是最需要花心思写的地方。它不是给人类看的简介而是给 Claude 的“语义钩子”。Claude 会根据你的描述判断“当前用户需求是否匹配这个技能”。如果你的描述写的是“整理会议纪要”那当用户说“帮我把这段讨论整理一下”Claude 大概率不会把两者关联起来。反过来如果你写成“将会议录音转写文本或零散讨论笔记整理成包含议题、结论、行动项的正式会议纪要”匹配率会高很多。我在实践中总结的描述写作框架是“任务对象 输入示例 预期输出”三要素缺一不可。任务对象说明这个技能管什么输入示例给出典型触发语句帮助模型建立关联预期输出说明交给技能后能得到什么。这套框架写出来的描述触发准确率比那种两三个字的描述高出一大截。2.2 正文把技能拆成人话frontmatter 下面的正文部分是技能的实际执行说明。很多人在这里犯的错误是把它当成 prompt 来写堆砌一堆形容词和祈使句比如“请务必仔细分析”“确保输出高质量结果”。这类话对 Claude 来说信息量极低因为它不理解“高质量”的边界在哪里。更有效的写法是分模块组织正文我常用的结构是这样使用场景When to Use明确列出哪些情况下应该启用本技能哪些情况下不要用。这一步相当于给技能划了边界防止 Claude 在无关场景下强行套用。执行步骤Steps用有序列表把任务拆成 3-7 个步骤。步骤要具体到可操作比如“从原文中提取所有出现的人名和对应观点”而不是“分析各方观点”。输出格式Output Format给出输出内容的骨架模板。这里可以用 Markdown 示例直接展示最终产物的样子Claude 对“照着样子输出”的理解能力远超对抽象描述的领悟。注意事项Rules列出执行过程中必须遵守的红线比如“不得编造原文中不存在的内容”“保留原文中提到的数据时不要做四舍五入”。这套结构的好处是Claude 拿到任务后能按顺序执行而不是靠猜。我自己的体会是步骤数量和粒度要适度。步骤太少模型容易跳步步骤太多模型容易在无关细节上消耗上下文窗口。一个需要 10 分钟人工完成的任务步骤控制在 5 个左右最合适。2.3 示例与边界决定技能质量的隐藏因素如果说 frontmatter 和正文决定了技能能不能用那么示例和边界声明就决定了技能好不好用。很多技能文件写得中规中矩但效果不稳定问题往往出在这里。示例是给 Claude 的“Few-shot 样本”。Claude 本身有很强的模仿能力一个高质量的输入输出对比十行解释性文字都管用。我在技能文件里通常会放 1-3 组示例优先选择典型业务场景下的真实案例。示例要完整展示从原始输入到最终输出的全过程不要只给结果不给过程。边界声明则是对技能的约束。最常见的坑是技能描述写得过于宽泛导致 Claude 在完全不相干的场景里尝试调用它。比如一个“数据分析助手”技能如果不写清楚“仅适用于处理 CSV 或表格数据”用户问“帮我分析一下这段文本的情绪”Claude 可能也会强行套用最后输出一个四不像的结果。所以我在每个技能文件里都会加一段“不适用场景”明确告诉模型什么时候不要用这个技能。3. 主文件编写实操一步步写出一份能用的技能定义3.1 先定场景以“会议纪要整理”为例理论讲再多不如直接上手写一份。下面我用一个最常见的场景——“会议纪要整理”来演示主文件的全过程。这个场景的典型用户需求是这样的团队开完会有人丢过来一段语音转写文本或者一整屏的群聊讨论希望整理成结构清晰的会议纪要。看起来很简单但真实处理起来有几个难点转写文本口语化严重包含大量语气词和重复表达讨论过程中话题来回跳跃不是线性的有些内容是闲聊有些是结论有些是待办需要区分。我最初写的技能版本只有一段描述加一句“请整理成会议纪要”结果 Claude 输出的东西就是单纯删减原文议题还是乱的行动项也藏在段落里找不出来。后来我按上面说的结构重写了主文件效果稳定了很多。3.2 主文件成品与逐段拆解这一节给出一个完整的SKILL.md示例这个示例我实际使用过并做了若干轮迭代可以直接作为模板参考--- name: meeting-minutes-organizer description: 将会议录音转写文本、零散讨论笔记或群聊记录整理成包含议题、结论和行动项的正式会议纪要。适用于用户提供非结构化的多轮对话内容并要求总结或纪要的场景。 --- # 会议纪要整理技能 ## When to Use - 用户提供的是会议录音转写文本、多人参与的讨论记录、群聊片段。 - 用户明确提出“整理成纪要”“总结一下会议”“列出结论和待办”等需求。 - 输入内容包含至少两个不同话题或讨论环节且夹杂口语化表述、重复内容或闲聊。 不要用于 - 用户给出的是已经结构化的文档如表格、正式报告。 - 用户只要求翻译或润色没有要求提炼结论。 ## Steps 1. 通读原始内容先按讨论话题切分段落。判断标准是“话题是否发生实质性转换”例如从“预算讨论”跳到“人员安排”而不是从“预算讨论”跳到“预算的另一个数据口径”。 2. 对每个话题段落提取三个信息要素核心讨论内容、最终结论若有、遗留问题若有。 3. 过滤口语化表达和重复信息保留所有具体数据和关键决策不改变原意。 4. 按“议题一结论一行动项”的结构组织输出行动项统一放在文末单独列出。 5. 检查行动项中是否包含负责人和截止时间。原文没有明确提到负责人的写“待确认”不得编造人名。 ## Output Format 输出使用以下 Markdown 结构 # 会议纪要 ## 会议信息 - 会议主题[若原文未提及写“未知”] - 参会方[若原文未提及写“未明确”] ## 核心议题 ### 议题一[议题名称] - 讨论要点... - 结论... - 遗留问题... ## 行动项 - [ ] 事项描述负责人XXX截止MM-DD - [ ] 事项描述负责人待确认截止待确认 ## Rules - 原文中没有的信息一律不补充、不推测用“未提及”或“待确认”标注。 - 保留原文出现的金额、日期、数量等数据不得做任何形式的近似或四舍五入。 - 行动项必须区分“已确认的待办”和“讨论中提到的可能事项”后者归入“遗留问题”而不是“行动项”。## Example 输入 “刚才小王说的那个方案我觉得可以预算大概两万左右但是老李说排期有点紧下个月中可能来不及。另外客户那边催方案文档催得很急周三前能不能给一版还有设计那边说新页面适配还没做。” 输出 # 会议纪要 ## 会议信息 - 会议主题未知 - 参会方小王、老李、设计组 ## 核心议题 ### 议题一方案评审 - 讨论要点小王提出方案初步认可预算约 2 万元。 - 结论方案方向可行。 - 遗留问题排期紧张下月中旬前完成有风险。 ### 议题二客户方案文档交付 - 讨论要点客户催促方案文档。 - 结论需要尽快提供一版。 - 遗留问题设计侧新页面适配尚未完成。 ## 行动项 - [ ] 输出方案文档初版负责人待确认截止周三前 - [ ] 确认新页面适配排期负责人设计组截止待确认## Version v1.2 ## Changelog - v1.2 增加行动项与遗留问题的区分规则修复原版本将“可能事项”直接列为行动项的问题。 - v1.1 增加数据保留规则避免模型对金额进行四舍五入。这个主文件我从 v1.0 迭代到 v1.2每一版都解决了一个真实使用中暴露的问题。下面逐段讲讲为什么这么写。首先是description。我特意在描述里同时塞了“输入长什么样”和“用户可能怎么说”。这样 Claude 在判断是否调用技能时既能通过内容特征匹配“转写文本”“群聊记录”又能通过用户意图匹配“整理成纪要”双重保险。有些技能不常用的原因就是描述只覆盖了一种匹配路径。正文里的When to Use不只是给 Claude 看也是给自己看的。写“什么时候不用”尤其重要。我在早期版本里没写这个结果用户让 Claude“帮我总结一下这篇报道”时模型居然也调用了会议纪要技能把一篇新闻报道硬生生拆成了“核心议题”和“行动项”非常荒谬。Steps部分我特意把判断标准都写进去了比如“话题是否发生实质性转换”这个判断标准就是多次实测后加上的。因为模型默认会把“同一个大话题下的不同小点”误判成新话题加上这个标准后输出的议题切分明显准确很多。Rules部分里“不得编造人名”这条规则是吃过亏才加的。模型在整理跨部门会议记录时会因为对话里没提某个事项的负责人就自作主张填上“项目组全员”或者“相应负责人”看起来合理实际上产生了不存在的信息。在正式工作流里这种“合理编造”比明显错误更危险因为肉眼很难发现。3.3 配套文件怎么放虽然本文重点是主文件但一个完整的技能包通常不只包含SKILL.md。主文件里如果引用了模板文件、参考文档需要在技能包的目录结构里一并放置。常见的结构是这样meeting-minutes-organizer/ ├── SKILL.md └── references/ └── meeting-template.md主文件里可以通过相对路径引用这些资源。比如在Output Format部分写“详细模板见 references/meeting-template.md”Claude 在需要读取模板时会按路径查找对应文件。这个机制对管理大型技能很有用主文件保持精简细节内容放在子文件中避免单个 Markdown 文件膨胀到几千行那样反而影响模型对核心逻辑的把握。不过这里面有个平衡问题如果主文件本身的步骤、格式说明不够完整完全把细节交给外部文件Claude 在每次调用时都要额外读一次子文件既消耗上下文又增加不稳定性。我的建议是核心流程和输出结构必须写进主文件只有大段的模板、常用话术库、参考数据才放子文件。4. 实测中遇到的坑与排查技巧4.1 技能匹配失败的常见原因技能写了却用不上是最高频的反馈。排查顺序我按概率排了个序先看description再动手改。第一个原因是description写得太短。三个词以内基本只能靠运气触发比如“翻译助手”“代码优化”用户不直接说这几个词的时候模型根本不会想起来有这么个技能。第二个原因是描述里的动词用得太泛“处理”“分析”“生成”这类动词在模型的理解里权重很低换成“将……整理成……”“从……中提取……”“把……翻译为……”这种有明确输入输出的表达触发率才上得来。第三个原因是技能名与描述不一致有人技能叫meeting-notes描述却写“整理周报”模型做语义匹配时明显会犹豫。排查看板我整理成了一张表方便对照自查症状最可能的原因快速验证方法技能从未被触发description 缺少输入输出特征在描述中补上触发例句偶尔触发时灵时不灵描述中存在抽象动词改为明确的动作短语如“将……拆解为……”在错误场景下被触发缺少“不要用于”边界在 When to Use 中补充负面场景触发了但输出不对正文步骤不够具体检查每个步骤是否包含判断标准4.2 上下文太长与指令漂移技能文件本身写得冗长是一个容易被低估的问题。主文件本质上会占据模型处理请求时的上下文窗口如果技能文件有两三千行那么每次调用这个技能都相当于从有限的上下文里切走一大块留给真正待处理内容的空间就变小。更麻烦的是过长的指令会让模型“注意力漂移”——中间段落写的关键规则模型可能在执行到后半程时就遗忘了。我的经验是主文件的正文部分控制在 1200 字左右最舒服超过这个量就要考虑拆分子文件。这和我前面说的“核心逻辑留在主文件大段模板放子文件”是一致的。另外把最重要、最容易被违反的规则尽量放在Rules部分且靠近末尾模型在结束阶段反而会对后端出现的规则更敏感这是我在多次测试中观察到的现象。还有个细节是不要在主文件里写互相矛盾的规则。比如既写“保留原始数据”又在Rules里写“对数字进行合理简化”模型往往不知道取舍最终表现就是有时保留有时简化。规则之间要尽量正交一条规则只约束一件事。4.3 特殊符号与格式隐患主文件是 Markdown 格式但它在被模型读取时会经过一层解析。这里有一个常见的坑在 frontmatter 里使用英文冒号后跟特殊字符或者正文里出现未闭合的代码块符号都可能让解析器错乱导致整个技能无法加载。我在早期版本里写过一段区块链交易分析技能正文中引用了交易哈希的示例包含大量0x开头的字符串。由于其中一些哈希值恰好被模型补全时出现了类似 Markdown 链接的格式导致技能加载后行为异常。后来我统一把这类内容放入独立的数据文件并在主文件里只写“参见 examples/tx-sample.yaml”问题才解决。另外要强调的是主文件里尽量不要直接用 emoji 作为列表符号或者重点标识。虽然 Markdown 渲染没问题但模型在解析时对 emoji 的注意力权重会分散到字符层面的联想上容易造成输出内容里莫名其妙带上表情符号。用加粗和引用块做强调效果干净得多。5. 主文件编写的通用原则与进阶方向5.1 从“写提示词”到“定义工作流”很多人第一次编写主文件时直觉上还是在写一段“更长更大的提示词”。这是需要突破的第一个思维误区。提示词的核心是“让模型理解我这一次的需求”而 Skill 主文件的核心是“让模型掌握这一整类任务的执行范式”。我用一个类比来解释提示词像是你叫一个临时工“今天把这面墙刷白”而技能主文件是给装修队的一份施工手册里面规定了腻子怎么刮、涂料怎么刷、阴阳角怎么处理、验收标准是什么。临时工靠理解力办事装修队靠手册办事。理解力受状态影响手册稳定发挥。所以写作时的自我检查方式也变了。写完一段说明后不要问“这句话能不能让模型明白”而要问“如果模型百分之百严格执行这段话结果是否符合预期”。如果你发现自己写的句子还需要模型“发挥理解力”才能执行那就说明该把这句话改得更具操作性。5.2 版本记录是主文件的隐形价值我见到的绝大多数技能主文件都没有Version和Changelog字段这是一个遗憾。Claude Skills 生活在快速迭代的环境中——模型版本会升级业务场景会变化你的技能定义也在不断调整。如果没有版本和变更记录哪天 Claude 行为发生变化你根本分辨不出是模型本身变了还是技能文件被谁改动过。我的做法是在主文件末尾留两行版本信息同时把迭代过程中发现的关键问题记录在 Changelog 里。比如“v1.2 增加规则行动项必须区分已确认与可能事项”这样每次回看时都能清楚知道这个规则当初想解决什么问题。在团队协作的场景下这个字段更是避免“盲目改回旧版”的定心丸。5.3 再谈一个被忽视的细节给技能留出“确认口”最后一个实操小技巧是我在多次翻车后总结出来的主文件里可以给 Claude 加一条“主动向用户确认信息”的规则但必须附带明确的判断条件。比如在会议纪要技能里我加了一条规则当输入内容缺失关键人物或关键时间且无法从上下文推断时可以在输出末尾加一行“以下信息待确认……”。这样做比让模型直接编造强得多也比让它停下来追问用户更流畅——因为很多用户丢一段文本过来后就切走了并不会在线等 Claude 提问。不过这种“确认口”不能滥用。如果每个技能都无脑确认输出就会变得拖沓。判断条件是信息缺失是否会影响纪要的可用性如果缺失的是一个次要信息直接标注“未提及”即可如果是核心决策缺少结论才值得单独列出确认项。总的来说主文件编写没有太多玄学核心就是结构清晰、描述具体、边界明确、示例到位。我见过的最稳定好用的技能往往不是写得最花哨的而是那些老老实实把场景和步骤写清楚的文件。只要肯花半小时把description打磨到位再给正文配上两三个真实示例这个技能的可用性就已经超过市面上大部分随手写的 skill 了。