最近在整理自己的 Agent Skills 目录时我发现一个很典型的现场仓库里 Skill 文件夹堆了十几个名字起得一个比一个唬人但真正跑起来能被稳定调用的翻来覆去就那几个。认真排查一轮之后问题几乎都出在同一处——主文件SKILL.md写得不对路。很多人把主文件当成功能说明书来写写了厚厚一版流程和背景介绍结果 Agent 压根不触发也有人把描述写得太宽结果什么任务都来蹭一下输出全是四不像。这篇文章我就专门拆一下 Claude Skills 主文件的编写技巧从文件结构、description 设计、正文组织到调试迭代把那些能让技能真正被用起来的细节一次讲透。适合正在开发自定义 Skills、想把工作流沉淀成可复用技能的开发者也适合刚接触 Agent 开发、想搞懂主文件为什么这么重要的人。1. 为什么主文件直接决定 Skills 的生死1.1 装了但从不触发的 Skills问题多半出在主文件我见过太多次这样的对话开发者兴致勃勃地装好了一个 PDF 处理 Skill描述也写了文件也放对位置了结果在对话里让 Claude 处理一份 PDF它就像没看见这个技能一样自己用别的方式硬做甚至直接说我无法处理文件。这时候绝大多数人的第一反应是模型能力不行或者Skills 不靠谱但真相往往很朴素——主文件里的描述没有让 Agent 在正确的时机认出这个技能。Agent 判断该不该调用某个技能的窗口非常短用户请求抵达、上下文还在滚动的时候它会快速扫一遍所有技能的描述信息做个粗粒度匹配命中才把对应主文件注入到工作上下文里。这个过程有点像招聘官几十秒扫一份简历简历上写本人吃苦耐劳、善于学习跟写精通 Python 数据处理近三年处理过百份财报 PDF后者才可能被约面试。所以主文件的第一使命不是介绍功能而是制造匹配。它是一扇门门上的招牌description决定了 Agent 会不会推开这扇门。招牌挂错了里面装修得再漂亮都没人进来。1.2 把 Skills 理解为文件注入而非插件Claude Agent Skills 的设计思想和传统插件机制有很大区别。传统插件常驻后台监听事件、暴露接口而 Skills 本质是一包静态文件Agent 到要用的时候才把其中内容注入上下文。那篇很火的《claude agent skills: a first principles deep dive》里有个观点我特别认同对 Agent 来说Skill 就是一个可以被注入到上下文中的文件或小文件树主文件是入口其余资源文件脚本、模板、参考数据都是被主文件按需引用的附件。这个认知一旦建立编写思路就完全变了。你写主文件不是在写产品的 README而是在写一份交给一个聪明但失忆的临时工的操作手册。这份手册平时放在仓库里没人看一被注入就要立刻让这个临时工知道我现在要处理什么问题、按什么步骤做、做到什么程度算完、遇到什么情况要停下来问人。想通了这一点你就知道为什么有些人写的主文件单看没问题用起来问题一堆——因为它是写给人类看的说明文档不是写给 Agent 执行的指令集。两者最大的差异在于人类可以脑补上下文Agent 在没有明确指令时倾向于自由发挥而自由发挥恰恰是技能失控的根源。2. 主文件骨架把结构拆开看才不迷路2.1 元信息区name 与 description 就是路由钥匙一个常规主文件的开头是 YAML 格式的元信息区里面最核心的两个字段就是name和description。这一段位于文件最顶部Agent 做技能路由时扫描的也主要是这个区域。--- name: meeting-notes-formatter description: 当用户需要将会议录音转写文本整理为结构化会议纪要时使用。输入应包含发言段落或转写文本输出按议题、结论、待办事项分组每个待办注明负责人与截止日期。若输入不是会议记录不要调用本技能。 ---这里有个容易被忽略的点name不直接参与触发判断。它更像一个语义锚点让 Agent 在同一批技能里能快速区分对象。真正决定你的技能何被选择的是description。description里写了什么等于告诉路由系统我管哪摊事。我自己的经验是写元信息时把触发条件三件套想清楚输入长什么样触发前提、输出长什么样交付承诺、什么时候不该用排除条件。三件套都写进 description 之后路由的命中率会有质的提升。后面第 3 节我会专门细讲 description 的写法这里先记住一个原则元信息区不是摆设是技能的第一版销售话术。2.2 正文区按标准作业流程组织别按论文结构组织过了元信息区剩下都是正文。正文是主文件的主体Agent 注入后主要靠它来驱动执行。但很多人在这里犯的错特别统一把正文写成了带目录、带背景、带大段原理介绍的文档。合格的主文件正文长这样# INPUT REQUIREMENTS - 输入应为会议录音的转写文本txt 或 markdown 格式 - 若无转写文本停止执行并向用户索要 # PROCEDURE 1. 读取全部转写内容按发言人划分段落 2. 识别每个段落的议题归属议题包括项目进度、风险、决策、待办 3. 合并同一议题的讨论点剔除寒暄与重复发言 4. 生成结论列表每个结论标注支持该结论的关键发言 # OUTPUT FORMAT - 会议纪要结构议题 | 结论 | 待办事项 - 待办事项必须包含负责人与截止日期缺失时标为待确认 # EDGE CASES - 单段内容同时涉及多个议题拆分后归属不同议题 - 缺少发言人信息使用发言人A/发言人B代指 - 转写文本为空终止输出返回提示信息看出来区别了吗正文的每一个板块都在回答一个执行时必然遇到的问题输入从哪来、按什么顺序做、做完交什么格式、遇到异常怎么办。板块标题用全大写加#开头是因为模型对这类符号标记的文本更敏感——当一大段手册被注入上下文时标记符号能让关键段落被更快定位。用给新同事的交接文档来类比再合适不过你肯定不会在交接文档里写公司的使命愿景你会写这台服务器怎么连、这个报表每周几跑、数据对不上找谁。主文件正文要的就是这种扑面而来的实用性。3. description 的精雕细琢决定 Agent 何时想起你的技能3.1 技能选择的隐形打分Agent 是这样挑活儿的要写好 description得先理解 Agent 在技能选择时做了什么。当一个用户请求进来Agent 不会把每个 Skill 的正文都读一遍那太浪费 token。它的选择器会更倾向于只扫描每个技能的 description 区块做一次粗糙的语义匹配命中之后再拉取对应主文件全文。所以 description 本质上承担着预筛选的作用。预筛选阶段有三个关键维度关键词重合度、场景条件吻合度、排除条件的清晰度。前两个好理解第三个很多人没意识到——如果你在 description 里写清楚了什么时候不要用反而能帮助 Agent 在模糊匹配时更快做排除决策减少不该触发却触发了的尴尬。打个生活化的比方你让一个助理帮你拿东西如果他记忆里所有工具的描述只有这是一个工具你让他拿剪刀的时候他大概率先抄起一把螺丝刀看看。但如果你给每个工具都贴上圆头细长、剪线头用和十字口、拧螺丝用的标签他根本不会犹豫。Skills 市场里几百个技能并存时description 就是那个标签写得好不好直接决定 Agent 会不会举一反三地找错工具。3.2 可复用的 description 配方三个层次一次到位我写 description 有自己的固定套路分享出来给大家参考。第一层是触发场景以当用户需要……时使用开头把用户意图描述得尽量贴近真实对话语气。第二层是输入输出契约告诉 Agent 这个技能接收什么、产出什么必要时点明格式要求。第三层是禁区声明说明哪些情况应该跳过本技能。完整的正面示范当用户需要把会议录音的转写文本整理成结构化会议纪要时使用。输入是转写文本输出包含议题、结论、待办事项待办事项带有负责人与截止日期。如果输入不是会议相关文本或用户只需要总结而非结构化纪要不要使用本技能。反面典型我也见过不少一个用于会议纪要整理的工具。这种 description 等于没写。它没有触发条件、没有输入输出形态、没有排除项。Agent 可能在任何提到会议的时刻尝试调用它也可能在用户实际需要它的时候因为上下文里会议一词不明显而根本没想起它来。3.3 触发词不是堆得越多越好有不少人把 description 当成 SEO 来做把会议、纪要、总结、minutes、meeting notes、agenda全部塞进去想着总能命中一个。短期看触发率是上去了但误触发率也同步起飞——用户随口说帮我记一下待办事项会议纪要技能也可能被拉出来空转一圈。这个问题的根源在于关键词的覆盖面和精确性之间存在张力。我的处理办法是优先保精确description 里明确写输入为转写文本/逐字稿而不是泛泛写处理会议内容。这样一来普通待办记录、聊天总结等请求就不会误伤真正需要结构化纪要的请求文本里往往自带逐字稿、转写、会议记录这类特征词反而更容易被匹配。过一段时间后你再根据实际触发日志微调描述把那些看了触发但输出不合适的请求反向喂给描述做排除训练而不是盲目加词。4. 正文编写让技能从看起来有用变成真能用4.1 为什么分块标记比长段落更可靠很多人写主文件正文习惯用自然语言来一大段首先你需要分析用户提供的文本提取关键信息然后按照一定的格式输出报告同时要注意语言的简洁性……这种写法信息都在但执行时效果很差。原因在于 Agent 接收的是线性文本流一段 500 字没有层级感的散文会显著增加它提取关键指令的认知负担而带#分隔的模块化文本每一层都像给文档打了锚点模型能迅速跳到对应位置。我常用的板块标记如下# ABOUT THIS SKILL # INPUT REQUIREMENTS # PROCESSING STEPS # OUTPUT FORMAT # COMMON MISTAKES # WHEN TO STOP每个板块下用三五行把话说透不要发散。尤其# WHEN TO STOP这个板块看起来可有可无实际价值极大——它给了 Agent 一个明确的退出权限当输入不符合要求时它可以停止执行并反馈而不是硬着头皮编一个结果。这比你在描述里写一百遍不要幻觉都管用。4.2 把步骤写成决策链而不是思路清单正文里的操作步骤是最容易写好、也最容易写废的部分。废的标准动作是写成思路清单分析数据、生成报告、输出结果——每个词都是动词短语但 Agent 不知道判断标准是什么、遇到分支怎么走。合格的步骤应该是决策链每个环节都带条件与分支检查输入是否包含至少两条独立数据记录。若不足两条直接向用户说明并退出。对每条记录执行字段完整性检查。缺失字段超过 30% 的记录标记为低质量数据不参与后续汇总。汇总时按日期分组日期缺失的记录放入未标注日期分组。输出汇总表后附上一行说明指出低质量数据记录占比。看到区别了吗步骤里出现了判断标准30%、例外放置规则未标注日期分组、输出附带说明。这样的步骤Agent 在执行时基本不需要自己发明规则只需要逐条落实。这也直接拉高了输出的可复现性——同一条输入跑十次结果都差不多。4.3 边界条件与错误恢复主动给 Agent 刹车和倒挡边界条件常被忽略但它是专业技能和玩具脚本的分水岭。所谓边界条件就是输入与预期不符时Agent 应该怎么反应。不写边界条件Agent 大概率会强行完成流程哪怕输入质量已经崩了。我自己写主文件时一定会带一个小节专门列如果……就……的规则。比如处理发票数据时如果输入文件中没有发票号码字段停止处理并告知用户缺少关键字段。如果发票金额包含非数字字符先做清洗清洗后仍无法解析将记录放入异常列表。如果用户只提供了图片格式发票且数量超过 10 张建议用户先走 OCR 预处理而不是硬塞给模型。边界条件还有一种更微妙的价值它能避免 Agent 在多个技能之间犹豫。边界条件写清楚了Agent 会更快决定这个场景不属于我从而把机会让给更合适的技能整个 Agent 系统的行为稳定性也随之提升。5. 主文件调试从对话试错到日志追踪5.1 最容易踩的四个坑附对照改进写主文件的时间久了我总结出四个高频问题基本能覆盖大部分人调试时遇到的情况。做成表格方便大家对照自查问题特征典型表现修改方向description 太泛很多不相关请求触发该技能输出经常文不对题收紧触发条件明确输入必须是什么什么时候不要调用正文步骤太粗技能被触发了但执行结果不稳定每次输出格式都不一致将步骤改为带判断条件的决策链固定输出格式模板缺少边界条件输入残缺时技能硬做产生看似完整但实际错误的结果补一个异常情况章节列出输入异常时的处理规则元信息与正文脱节description 说的功能正文根本没写或正文写了但描述没提让两者互相照应改一个时必须同步检查另一个这四个坑里我认为危害最大的是第二个正文步骤太粗。因为描述写得再好技能执行阶段还是靠正文驱动的正文给不出可靠操作序列前面的触发成功反而放大了后续的输出混乱。5.2 迭代式调试一次只改一个变量我自己调试主文件的流程基本是对话内观察 活动日志核对双通道。先在对话里故意说出符合该技能触发条件的请求观察 Claude 是否主动调用了该技能。如果没有调用直接追问它为什么刚才不使用 xx 技能模型通常会给出一个候选原因比如我认为你的请求更接近一般对话——这句话基本就是在告诉你 description 哪里没写透。如果触发了但执行结果不对那就看输出卡在哪一步。输出格式问题修正文输出模板中间步骤乱修步骤的决策条件完全没有按流程走大概率是正文结构不够清晰回到标记分块上做强化。调试还有个纪律一次只改一个变量。改完 description 就去测触发率别同时动正文结构改完正文结构就去测输出一致性别顺手把元信息区的措辞也换了。否则出了新问题你根本定位不到是哪个改动引入的。另外主文件尽量控制在合理篇幅内——我个人的经验是正文部分在几百行内最合适。太短往往规则不全太长会增加注入成本且关键指令被稀释。如果确实需要大量参考数据或脚本把它们拆成独立文件在主文件里用读取当前目录下的 xxx.py 并按其中逻辑执行来引用不要让主文件无限膨胀。6. 从官方市场到本地定制主文件移植与二次开发6.1 拿到手的 Skills 不一定到手即用要主动改现在获取 Claude Skills 的渠道不少Anthropic 官方市场一直在扩充社区里也有大量开发者维护的技能仓库。很多人以为从市场里把 Skill 拉下来、放进 skills 目录就算完事实际用起来却发现触发频率很低。原因并不神秘别人技能里的 description 是针对别人的使用场景写死的未必适配你的数据形态。拿到一个现成 Skill 后我建议按这个顺序过一遍读主文件尤其是 description 和输出模板判断它和你实际业务流程的匹配度。用你手头真实数据跑一次观察触发时机和执行结果记录偏差。根据偏差改主文件调整 description 的触发条件改动输出模板的字段结构。改完再跑一轮确认原先的偏差消除顺手看一眼有没有引入新问题。这里面最关键的一点是主文件是本地配置不是上游代码。它本来就该被你按需修改而不是像安装二进制软件一样装完就锁死。真正用得好的团队本质上都会对官方 Skills 做二次裁剪——把不需要的边界条件删掉把符合自己业务的黑话写进描述里输出对齐内部报表的格式。改完之后这个技能才算真正长在你的工作流里。6.2 借用第一性原理的视角来审查别人的 Skills前面提到的那篇第一性原理深度解析文章给了一个很好的思维框架剥开 Skills 的外壳它本质上就是在回答两个问题——什么时候用description 区和怎么执行正文区。用这个框架去审查任何一份主文件都能很快判断它值不值得被装进自己的技能库。那些描述含糊其辞的技能扔步骤没有分支逻辑的技能扔边界条件空白满篇只讲理想情况的技能扔。反过来一份主文件如果能把触发场景、输入契约、输出规范、异常处置写得分明哪怕这个技能本身领域跟你不太相关它的编排方式也值得你借鉴到自己的技能设计里。说实话写主文件这件事难度不在于语法或格式而在于把自己脑子里的隐性流程显性化。很多人的业务流程是自己门儿清一落到文字就默认读者也有同样背景结果写出来的主文件只有自己能看懂。我现在的习惯是反着来假设自己是第一天接手这份工作的新人只靠文件内容能不能把活干好。按这个标准去写主文件的质量基本就不会太差。最后再分享一个实际体会。最开始我写 Skills 总想着把每个流程设计得高大全一个技能恨不得覆盖十种情况结果主文件越来越长触发率反而越来越低。后来做减法一个技能只解决一个问题、描述只承诺一份输出、正文只保留必要的分支效果立刻好起来。你想让 Agent 可靠地调用你的技能主文件就要像一份干净的作战指令而不是一本百科全书。