作为一名长期跟 Agent、工作流和各种自动化工具打交道的人我见过太多“看起来能用”实则关键时刻掉链子的 Skill。它们往往在演示时岁月静好一放进复杂项目里就原形毕露。这里面百分之八十的问题都出在写 Skill 的人对它的本质理解有偏差。今天这篇东西没有高大上的概念就是把“如何写一个优秀的 Skill”这件事拆开揉碎了讲。我尽量用我已经踩过的坑给你填平路子让哪怕是刚接触这块的新手也能按图索骥写出结构清晰、鲁棒性好、真正能打的 Skill 出来。1. 先别急着写代码搞懂 Skill 到底是什么才算入了门很多朋友一上来就到处找模板问“Skill 的代码结构是啥样的”。实际上Skill 的核心从来不是那一堆代码文件而是你对“模型如何完成一次高质量任务”这件事的深度封装。你可以把 Skill 理解成一个“超级提示词的容器”。它把完成某一类任务所需要的全部“知识”——包括角色设定、执行步骤、约束条件、边界处理、参考示例——打包在一起。这样不管是大模型还是自动化工作流只要调用这个 Skill就能稳定地复现一套经过验证的行为模式。我见过最典型的理解误区是有人把 Skill 写成一个大而全的“百科全书”什么情况都想覆盖结果模型一调用就糊涂了输出内容跟任务目标完全对不上。另一个误区是过度精简一个 Skill 里就扔给模型一句话“帮我处理这个”等于没封装模型依旧在裸奔发挥极其不稳定。一个真正优秀的 Skill一定具备这么几个特征职责单一一个 Skill 只解决一类问题而不是万能工具箱。比如“撰写项目周报”和“撰写项目复盘”虽然都是写文字但目标、结构、侧重点完全不同强行合二为一模型就要在内部做大量的“意图判断”反倒拉低了质量下限。行为可预期同样的输入在核心条件不变的情况下交给模型执行十次里有九次半的结果是稳定可靠的。这不是靠运气而是靠你写清楚的规则和步骤。边界清晰Skill 知道自己能干什么更知道自己什么情况下该“拒活儿”或者“求助”。比如你让它做数据分析结果对方丢过来一个没有数据的空表你的 Skill 应该明确告知“数据不全需要补充XX字段”而不是胡编乱造一堆数字。上下文友好它不是孤立运行的而是能够读懂当前对话或工作流里已有的信息只索取自己真正需要的输入避免给模型造成过重的上下文负担。简而言之写 Skill 就像是在为一个“能力很强但没啥主观能动性的实习生”写一份极其详尽的工作手册。你把所有关于“怎么做”的知识都沉淀在手册里他要做的仅仅是看到任务、翻开手册、按章执行。这样哪怕这位“实习生”每天换一个也就是模型版本升级或者换不同的大模型工作质量依然有保证。2. 动手前的规划磨刀不误砍柴工先想清楚这四件事很多人拿到一个需求比如“做个整理会议纪要的 Skill”立刻就去翻文档、搭框架、写提示词效率倒是高但往往做出来的东西用两次就想删掉重写。原因就出在需求分析没做透。每次动手之前我都会强迫自己花至少二十分钟把下面四个问题在脑子里过一遍甚至在草稿纸上写下来2.1 我的用户是谁他们卡在哪一步还是拿“会议纪要”举例。用户如果是团队负责人他的痛点可能不是“把语音转写成文字”而是“从冗长的讨论里快速提炼出决策结论、待办事项和负责人”。如果这一步没想清楚你做的 Skill 可能只是在做“文字摘要”或者“逐字稿精修”完全没戳中用户的真实需求。反过来用户如果是一线的项目助理他的痛点可能又是另一套他需要自动生成符合公司特定邮件格式的纪要——带编号、带风险标记、带截止日期。目标用户不同Skill 的侧重点和输出颗粒度就完全不一样。所以第一步永远是明确“给谁用”击中的是其具体的“痛”。2.2 这个任务的完整流程是什么样的不能只说“帮我把会议纪要写好”就完事。你得把流程分解成颗粒度更小的步骤读取或接收原始的会议语音转写稿、聊天记录等输入内容。清洗文本识别发言人、时间戳、讨论主题。抽取关键结论、分歧点、遗留问题。根据预设规则整理成结构化纪要含议题、结论、下一步行动、负责人、截止时间。按照排版规范输出为可直接粘贴到工作群或邮件中的纯文本或 Markdown 文本。一个优秀的 Skill一定是在步骤层面就给模型搭好了“脚手架”。它不用自己摸索开场该干嘛、中间该干嘛只需顺着你给的路径走。这也是后面写提示词时最耗体力的部分但前期规划得越细后期写起来就越轻松。2.3 输入端的不可控因素有哪些Skill 的使用环境是复杂的。调用方发给你的可能是一段音频转写后满是噪音的文字可能是两个小时的完整录音也可能是一段几百字、连人名都省了的聊天记录。你得提前想清楚哪些情况是“正常的、能处理的”哪些情况必须“直接拒绝或要求补充信息”。比如会议纪要 Skill原始输入里如果连“发言人A”“发言人B”都没有标记你的 Skill 是否还能正常生成有效纪要我的经验是可以在 Skill 里明确写一条规则“如果输入内容没有明显区分发言者或讨论主题首先向用户索要结构化文本并给出文本整理模板示例。” 这样就能避免模型硬着头皮去猜。2.4 成功和失败的判定标准是什么Skill 执行完之后你拿什么标准判断它“做好”了是格式正确、关键信息无遗漏还是语气风格符合要求最好把这些标准显式地写进 Skill 里让模型在执行结束、输出结果之前能自己先做一次“质检”。比如你可以要求模型在输出纪要后末尾附带一份自查清单“已包含会议主题/结论/行动项/负责人/截止时间无最关键的信息遗漏如遗漏请重新生成。”这样能在一定程度上拉高 Skill 输出的稳定性。3. 系统架构拆解一个优秀 Skill 的“三件套”长什么样先说明一下我这里不绑定任何具体的技术平台或开发框架讲的是通用的逻辑分层方案。你理解了这套结构不管是在什么工具、什么平台上落地都能一法通而万法通。我习惯把一个结构完善的 Skill 拆解成三层入口配置层、核心指令层、范例与知识层。3.1 入口配置层给别人一张清晰的名片这一层通常对应平台的配置文件比如 YAML 或 JSON主要作用是让这个 Skill 能被调用方“看见”并“理解”。它包含两个关键信息元信息该 Skill 的名称、作者、版本、用途说明。元信息看似简单实际上直接影响 AI 的调度成功率。比如“会议纪要助手”就比“scm_001”这种名字更让模型容易认识并调用。输入参数定义该 Skill 允许调用方传入哪些信息。这里能体现老手和菜鸟的差别。优秀的参数设计不是一股脑地把所有上下文都塞进去而是定义最少但最关键的“槽位”。这么说比较抽象举个例子。假设你要做一个“代码审查 Skill”。它的入口参数至少应该包含code_snippet待审查的代码片段必要参数。language代码语言比如 Python、JavaScript非必要但填了能提升精准度。review_focus审查侧重点比如是“安全检查”还是“性能优化”由调用方选择。还要明确告知调用方如果这个参数没传模型是无法开始工作的请补全后再调用。这一层写得越清晰Agent 调度器或者叫控制器就越容易把这个 Skill 分发到正确的位置上。3.2 核心指令层定海神针在这里这一层是 Skill 的“大脑”是一段精心编写的提示词。它决定了模型的工作方式和最终产出质量。我在写这一层时基本遵循一套相对固定的套路角色定义明确“你是谁”。例如“你是一名有十年从业经验的资深代码审查专家熟悉主流开发语言的规范与安全缺陷。”任务描述清楚说明“你要处理什么”。例如“以下是调用方提供的代码片段请从代码可读性、健壮性、安全性三个维度进行审查。”执行步骤把完成任务的路径拆成显式的动作。例如先通读片段梳理代码主流程。分析每个函数/方法的边界条件。列出发现的问题并按严重程度从高到低排序。对每个问题给出具体修改建议。约束条件和输出格式明确“不可以做什么”和“必须按什么格式输出”。例如“不修改原始代码只输出建议输出的每个问题需包含原文行号、问题描述、修改理由、修改后示例。”边界与兜底处理告诉模型“遇到什么情况就停下来”。例如“如果代码片段少于十行或缺少函数上下文无法进行有效审查请告知调用方需要补充更多上下文。”很多初学者最常掉的坑是把这一层写成一段“自由发挥”的散文看是好看但模型执行起来完全没有抓手。正确的姿势是写成类似“SOP操作手册”的样子分步、清晰、无歧义。3.3 范例与知识层减少模型的“自由发挥”这一层是大模型发挥稳定性的关键。你可以放一两个“标准答案”或“优秀范例”供模型在输出时进行参照。它的作用很明显大模型本质上是一个概率预测器有了范例它的输出概率分布就会被引导向高质量区域。例如在“会议纪要 Skill”中放一段从原始对话到最终纪要格式的“输入-输出”对照示例。模型看到示例就会知道“哦原来输出要这样分点要这样给待办事项归类”。实践中需要注意范例不在多而在精。一两个高质量、有明显对比度的例子足够了。放一堆烂栗子反而是负优化模型会被教坏。4. 实操方法论从零到一手写一个可跑的 Skill下面我们从零开始手动走一遍书写一个 Skill 的全过程。这里我拿“项目风险巡检”这个场景来演示用它来定一个相对通用的处理框架。4.1 第一步定义输入和输出规格为方便后续接入更复杂的自动化流水线我把输入输出定为结构化较强的 Markdown 或 JSON 文本。输入项目基础信息、当前进度描述、近一周的变更日志或风险描述文本。输出风险评估报告。包含项目整体健康状态红/黄/绿、风险点TOP5、每个风险点详情风险等级、可能性、影响度、应对措施、建议采取的下一步行动。4.2 第二步构建核心指令的骨架打开你的编辑器我习惯先写一个“主提示词”骨架你是一名项目风险管理专家。请根据调用方提供的项目信息完成以下任务 1. 识别项目中可能存在的技术风险、资源风险、进度风险。 2. 对每个识别出的风险进行评级高/中/低并给出评级理由。 3. 输出应对措施包括规避、缓解、转移、接受四种策略。 4. 最终输出格式必须严格遵循模板见输出格式定义。 注意事项 - 必须基于已知信息进行分析不得编造不存在的项目事实。 - 风险描述需具体避免“可能有问题”这类模糊表述尽量给出可衡量的信号。 - 输出语言与输入语言保持一致。这一步大多数人都能做到但离“优秀”还有距离。4.3 第三步把约束条件“参数化”和“规则化”这是拉开水平差距的核心。在上面的骨架里只说了“输出风险”但没告诉模型“什么样的风险算高风险”。所以在这步需要把判断基准显式写出来风险等级定义 - 高风险发生概率高70%且影响严重可能导致项目延期超一周或核心功能无法上线需在24小时内制定应对方案。 - 中风险发生概率中等30%~70%或影响可控短期延迟可内部消化需持续跟踪观察。 - 低风险发生概率低30%且影响有限不影响关键路径记录在案即可。 应对措施选用规则 - 规避适用于高风险且可以通过改变方案或范围来消除的风险。 - 缓解适用于无法规避但可降低影响程度的风险。 - 转移适用于可通过外包、采购或保险等方式转嫁的风险。 - 接受适用于低成本、影响小且应对代价高于风险本身的风险。把这类规则定义清楚模型就相当于拿到了一份带刻度尺的“标尺”而不是凭感觉打分。这一步也是把你在某个领域的行业经验转化为可复用资产的过程。4.4 第四步设计“少样本范例”而不是“废话连篇”这也是质量分水岭。很多人喜欢在提示词里写“你要注重细节”“要灵活变通”“要理解用户的言外之意”这些对模型来说都属于无效信息。真正有效的是给出一个完整的范例。例在“项目风险巡检”里范例可以这么写输入“项目A当前处于开发中期前端页面开发完成80%后端核心接口已完成联调但性能压测尚未开始。最新变更数据库选型从原有的方案切换为新方案预计开发成本增加三天。”输出一、整体健康度黄色需关注二、风险点TOP3风险描述数据库选型切换或导致底层数据访问层代码需返工可能影响后端进度。 等级高风险 依据切换数据库通常意味着 SQL 方言、事务机制、连接池配置均需调整剩余两天内完成适配并介入压测的难度较高。 应对策略缓解建议拉通后端骨干进行专项攻关暂缓非核心功能的开发任务将开发资源向适配工作倾斜。这样的范例能够让模型非常清晰地知道你期待的颗粒度、结构与表达风格。我见过有些朋友写的 Skill 之所以不太行就是因为核心指令还行但一个范例都懒得放或者放了一个不着四六的外行文本。4.5 第五步增加“自检清单”和“兜底策略”在指令的最后部分我会添加类似下面的一段要求模型输出前自行检查一次输出前二次检查 - 是否所有风险点都对应了风险等级和应对措施 - 是否给出的应对措施和风险描述存在逻辑断裂如果断裂请重新组织语言。 - 是否任何结论都有依据支撑没有凭空捏造 - 是否遵守了输入输出格式规范这能显著提升模型输出的一致性和完成度。配合兜底策略——“如果输入信息严重不足无法完成分析请明确列出缺失信息不要强行生成报告”就能避免模型在信息不足时一本正经地“编故事”。5. 迭代与调优写完不是结束这才是打磨的开始Skill 是一次性写成的但能力是一次次试出来的。我自己的习惯是哪怕初版写得再满意都要经过三轮以上的压测和迭代。5.1 第一轮正向用例测试找一个标准的、简单的输入跑通主流程。这一步主要验证“骨架”是否正确。如果连标准输入都输出得乱七八糟大概率是核心指令层写得不清晰需要回头改结构而不是调措辞。5.2 第二轮边界与异常用例测试这一步是拉开普通开发者和高级开发者之间差距的关键环节。我会故意准备几个反例给 Skill 处理空输入或极短的输入。输入中包含大量无关噪音信息。输入中存在明显冲突的信息比如同时说进度正常但上线日期已跳票三次。输入的语言和格式完全不符合预期。一个设计良好的 Skill在这些边界场景下应该不至于崩溃而是能清晰地表达“我遇到了什么困难我需要什么支持”或者能够稳定地从噪音中提取核心信息。如果这些场景下 Skill 表现不佳就得补充相应的规则和约束。5.3 第三轮措辞优化与“去AI感”在功能稳定后我会更关注输出表述。如果发现输出结果是“正确的废话”或者“标准的AI腔”比如频繁出现“总的来说”“综上所述”这类口头禅我会在输出格式规范里做一点约束比如“减少套话和总结性空话尽量用具体的事实数据说话。”实际上这些“小禁忌”和“小偏好”是高度依赖场景的。你不能指望一个通用的框架帮你解决所有问题优秀的 Skill 都是针对具体痛点养出来的这需要你刻意练习。6. 避坑指南这些年我把这几个坑踩了个遍6.1 提示词过于冗长或过于精简这像走钢丝。太长了可能在执行时消耗无意义的上下文资源且容易让模型在庞大的规则海里迷路太短了则没有足够的约束力。我的经验是能用步骤拆解表达的规则不要用大段散文描述。能做到精简又具备可执行性是高级技能。6.2 过度依赖单个模型的能力差异有些写作者把希望完全寄托在“模型够聪明”上觉得自己指令写得差不多就行。现实是同一套 Skill在更先进的模型上可能表现出色但在轻量级模型上就彻底翻车。判断一个 Skill 是好是坏不应该是“在某家的大模型上效果很好”而应该是在几个不同规格的模型上都能达到及格线以上的可用状态。6.3 忽略动态生成和模板的威力在进阶阶段你可以让 Skill 具备“按需生成模板”的能力。比如让它根据传入的参数类型在内部先生成一个处理模板再按模板执行。甚至你可以让 Skill 在输出结果之前先生成一个“检查当前输出是否符合外部标准”的自检脚本。这些都是让 Skill 从“能用”迈向“好用”的进阶玩法。7. 除了写还需要有工程化思维Skill 写多了之后你会慢慢意识到它的本质已经不是让你给大模型“布置作业”而是让你在给“未来的自己”或“其他开发者”设计一套可复用的方法论。因此规范化的命名、注释和版本管理同样重要。在我自己的实践里每个 Skill 都会带一个简短的 README 文件里面写明它依赖哪些输入、适合用在什么场景、预期输出是什么、有哪些已知限制。这样不管是自己三个月后回来维护还是同事/朋友复用都能快速上手而不需要从一堆结构文件里去“考古”。写一个好的 Skill确实没有太多高深莫测的魔法。它的核心其实就一句话把那些不可言说的经验用结构化的语言转化为模型可执行的稳定逻辑。希望你在自己动手写的时候也能体会到拳拳到肉、真正解决实际问题的快感。