1. 技能编写，到底在写什么
先说个场景：你手上有一套智能助手或者自动化系统，它能干活，但能干多少、干得漂不漂亮，很大程度上取决于你给它定义好的技能包。这个技能包不是几行代码那么简单，它是一整套描述、约束、执行逻辑和反馈机制的集合。我见过太多人把技能编写当成写说明书，结果做出来的东西要么触发不灵，要么参数满天飞却执行不到点上，要么别人根本看不懂这个技能是干什么用的。
Skills 编写学习，本质上是在学一套“如何把人类做事的经验，翻译成系统能读懂、能执行、能复用的规范语言”。这个能力，恰恰是当下做智能体、做自动化工作流、做知识库系统最值钱的通用技能之一。因为不管底层用的是什么模型、什么框架，最后落到业务上，靠的都是一个个定义良好的技能单元。
这篇文章不打算讲某个特定平台的界面操作，因为那太容易被版本迭代淘汰了。我想分享的是从需求拆解、描述撰写、参数设计到执行逻辑打磨的一套完整方法，配合我实际调试过程中踩过的坑和总结出来的经验。适合正在学习技能编写的初学者，也适合已经写过几个技能但总感觉“差点意思”的朋友。不管你是给智能助手加技能，还是给某个业务流程做自动化配置，思路都是通用的。
2. 技能定义的本质与设计逻辑
2.1 一个技能的三层结构
很多人第一次接触技能编写，容易把它理解成“写一段提示词”或者“写一个函数”。实际上，一个能稳定运行的技能，至少要包含三个层面，缺一不可。
第一层是意图识别层。系统凭什么判断用户这句话需要调用这个技能？这靠的是技能描述、触发关键词、适用场景说明。这一层写得模糊，技能就容易“聋”——改叫不醒，或者“滥”——什么话都往这儿引。
第二层是参数解析层。一旦技能被触发，系统要从用户的输入里抽出哪些关键信息？这些信息有哪些约束条件？哪些是必填的，哪些可以缺省？这一层就像表单设计，字段定义不清楚，后面执行就是空中楼阁。
第三层是执行逻辑层。拿到参数后，技能内部按什么步骤运行？遇到分支怎么走？出错怎么兜底？结果怎么返回给用户？这一层是真正的“体力活”，也是最容易出细节问题的地方。
打个比方，技能就像餐厅里的一道招牌菜。意图识别层是菜单上的菜名和介绍，让顾客知道这是啥、想不想点；参数解析层是后厨点单时确认忌口和分量；执行逻辑层则是灶台上的所有操作步骤，火候、顺序、调料一个都不能乱。
2.2 设计前必做的需求拆解清单
动笔写技能之前，我习惯先做一个拆解练习。你可以在纸上或者文档里回答下面这些问题，回答清楚了，技能框架基本就立住了。
- 这个技能服务的核心任务是什么？一句话能不能说清楚？
- 触发这个技能的人通常处于什么场景？他手上有什么信息，想要什么结果？
- 完成这个任务需要哪些关键参数？每个参数的取值范围、格式、默认值是什么？
- 任务执行过程中有没有分支情况？比如数据缺失、条件不满足、结果异常？
- 技能运行结束后，用户期望看到什么样的反馈？是一次完成，还是分段汇报？
我见过一个很典型的反面教材：有人写了个“会议纪要整理”技能，描述写的是“帮助用户把会议内容整理成纪要”，但完全没有说明输入是录音转写文本还是零散笔记，也没定义纪要需要包含哪些板块。结果技能倒是能触发，但每次输出的格式都不一样，有时候是纯段落，有时候是带表格的，用户根本没法直接拿去用。这就是需求拆解环节偷懒的代价。
2.3 从模仿到自研：学习路径建议
学习技能编写最有效的方式，不是从零开始闭门造车，而是找三五个现成的优秀技能样本做逆向拆解。你把别人写好的技能定义拿出来，逐个字段分析：为什么描述要这么措辞？为什么参数要这样命名？为什么执行步骤是这个顺序？然后模仿着写一个功能类似的，再慢慢换成自己的业务场景。这个过程反复三四次，你就能形成自己对技能结构的直觉。
当模仿积累到一定程度，你会发现所有技能编写的底层痛点其实是共通的：模糊的描述、缺失的兜底、过长的执行链路、难以调试的输出格式。而这些痛点，没有一套现成的标准答案，只有基于对业务场景深入理解的持续打磨。
3. 实操前的准备工作
3.1 明确技能的应用环境与平台约束
动手写技能之前，第一件事是搞清楚你要服务的平台/框架在技能编写上有什么约束。不同环境的约束差别可能很大，主要包括：
- 描述字段是否有长度限制，是支持纯文本还是支持 Markdown
- 参数系统支持哪些类型（字符串、数字、枚举、数组），是否能定义必填项和默认值
- 是否有独立的提示词模板区，还是全部写在描述里
- 执行逻辑是采用固定步骤还是支持条件跳转
- 输出区是否允许自定义格式，有没有模板语法
我建议把平台文档里关于技能定义的说明全部读一遍，甚至把字段清单整理成表格。很多人上来就凭着印象写，写到一半才发现某个关键字段根本不存在，或者平台对描述格式有强制要求，被迫返工。这种问题完全可以通过提前读文档来避免。
3.2 材料准备：没有文档就拿不到好技能
技能写得好的前提，是你对业务领域有足够深的理解。举个例子，你要写一个“员工入职办理”技能，那你至少需要：入职流程的标准步骤、每个环节涉及的部门与系统、需要收集的员工信息字段、不同岗位类型的差异化要求。这些材料如果没有，写出来的技能必然是空壳。
所以我的习惯是，接到技能编写需求后，先花半天到一天时间搜集、梳理领域资料。该问业务专家的问专家，该翻历史文档的翻文档，该整理标准操作流程的整理流程。这个准备阶段的投入，会在后续调试阶段几倍地省回来。记住一句话：技能编写的瓶颈，通常不在于技术，而在于你对业务过程的理解深度。
3.3 工具选型：用结构化编写提升效率
工欲善其事，必先利其器。我常用的编写工具主要有三类：一是平台自带的技能编辑器，二是支持 YAML/JSON 结构的文本编辑器，三是带版本管理的仓库工具。
平台自带编辑器适合新手，因为字段都是可视化的，不容易漏填。但它的劣势是不方便批量对比多个技能的差异。所以我个人更建议用文本编辑器写好草稿，再粘贴到平台中。特别是 YAML 格式，它天然支持层级结构，适合表达意图识别、参数定义、执行步骤这种多层次的技能内容。
如果你同时维护多个技能，建议把每个技能定义单独存放，并加上版本号和更新日期。技能这东西会持续迭代，没有版本管理的话，改着改着就不知道自己改到哪儿了。哪怕只是用带历史记录的云笔记，也比裸奔强。
4. 技能描述与触发条件的打磨
4.1 描述既要“让人懂”，更要“让系统懂”
技能描述有两个读者：一个是使用技能的人，一个是解析技能的系统。两者对描述的要求有时是冲突的——人喜欢简洁，系统喜欢明确。优秀技能描述必须同时照顾两头：用一句通俗的话说明技能用途，再用若干条精确的触发场景补充说明。
我自己常用的描述模板大概是这样的：
这个技能用于[完成什么任务]。当用户提到[触发场景1]、[触发场景2]等需求时，调用此技能。典型输入示例包括：[示例1]、[示例2]。如果用户请求与[相关但不同的事项]，请勿调用此技能。
注意最后那句“请勿调用”，很多人会忽略。加这句话是为了防止意图漂移。比如你写了一个“查天气”技能，如果描述里只写了“当用户问天气时调用”，那用户说“帮我看看明天适不适合洗车”，系统很可能也会抓着这个技能不放。但如果你明确写了“涉及洗车建议、穿衣建议等场景请勿调用，应引导至生活建议技能”，意图识别的准确率会明显提升。
4.2 触发条件的颗粒度设置
触发条件的颗粒度是个很有意思的平衡问题。写得太粗，技能容易被误触发；写得太细，覆盖率又不够。我的经验是：先写核心触发场景，再逐步扩展边界，每次扩展都要实际测试。
举个例子。我做过一个“周报生成”技能，初版描述只写了“当用户要求生成周报时调用”，结果用户说“帮我汇总一下这周的进展”时，技能没被触发。后来我在描述里补充了“汇总/整理本周工作”“这周干了什么”“周报”等多种表达，还会根据上下文判断用户是否有生成周报的意图。经过几轮迭代，触发率才到了可接受的水平。
这里透露一个实操技巧：为了验证触发条件的覆盖度，我会准备一批“正向样本”和“负向样本”。正向样本是应该触发技能的表达，负向样本是绝不应该触发的表达。改一次描述，拿这批样本全测一遍，既快又准。
4.3 描述中常见的关键词陷阱
我审阅过不少别人写的技能描述，发现几个特别常见的问题：
第一个是形容词先行。比如“智能地分析用户数据并给出专业建议”，这种描述对系统没有任何约束力，因为“智能”“专业”是主观词，不是可判定的触发特征。应该改成可识别的行为描述：“当用户上传数据文件并询问趋势分析或改进建议时”。
第二个是覆盖太全。一个技能想把所有相关的情况都揽进来，结果触发的边界越来越模糊。其实正确的做法是聚焦核心场景，把边缘场景交给别的技能去处理。技能之间各管一摊，整体识别率才会高。
第三个是忽略否定表达。用户说“不用生成周报了”，系统还在调用周报生成技能。这种负面意图如果不在描述里约束好，就会出现很尴尬的体验。
5. 参数定义与输入处理
5.1 参数就是技能的输入接口
参数定义得好不好，直接决定了技能在实际运行中能拿到什么质量的数据。这一步没有捷径，老老实实列出执行任务所需的全部信息，逐个确定类型和约束。
我一般采用这样的步骤。第一步，写出任务执行的完整逻辑过程，每到一个需要输入信息的分支，就把它记成一个潜在参数。第二步，判断这些参数哪些能从用户话语中直接抽取，哪些需要默认值，哪些需要系统根据上下文自动获取。第三步，为每个参数定义类型、格式、可选值、默认值和含义说明。
用“项目进度查询”技能举例，核心参数大概有三个：一是项目名称或者ID（必填，标识查询对象），二是查询的时间范围（选填，默认最近30天），三是结果输出的详细程度（选填，默认为标准模式）。如果用户只说“帮我看看项目的进度”，技能也能基于默认值运行，而不是报错说缺参数。
5.2 必填参数与选填参数的边界
初学者最爱犯的毛病是把所有参数都设为必填。这么做的后果是，用户在自然表达中没提供某个参数时，技能不得不反复追问，交互体验非常差。反过来，如果把所有参数都设为选填，技能又可能在关键信息缺失的情况下盲目执行，给出一个猜测性的错误结果。
我的平衡原则是：核心业务对象必填，条件约束尽量选填并具备合理的默认值。比如“创建订单”技能，商品明细和金额是必填的，否则订单不成立；而收货时间、备注这些信息可以选填。对于选填但缺失的参数，设计清晰的默认行为，让技能“带着默认值干活，必要时再确认”。
5.3 别忽视参数校验与归一化
系统抽取出来的参数，未必是干净可直接用的。用户说“后天下午”，如果参数系统解析出来的是“后天下午”这种自然语言，你的执行逻辑就没法直接计算。所以技能里要包含参数处理环节：把自然语言表达归一化成标准值，把模糊表达转换成精确值，把超出范围的值拦截或修正。
我习惯在技能执行的第一步就做参数校验。校验包括三个层面：内容是否完整、格式是否合法、取值是否在预设范围内。校验不通过时，不是直接报错，而是整理出“缺什么、怎么补”的指引，引导用户把信息补齐。这种细节，是技能从“能用”走向“好用”的关键差距。
6. 从零到一：实操一个技能
6.1 案例背景：做一个“会议待办提取”技能
理论说再多，不如动手做一遍。下面我用一个完整的例子，走一遍技能编写的全流程。场景设定是：用户经常会贴一段会议纪要或者聊天记录，希望系统自动提取出其中的待办事项，按负责人和截止时间整理成任务清单。
这个技能对应的核心需求很清晰：从非结构化的文本中，识别“谁在什么时间之前要完成什么事”，输出结构化的待办列表。适合刚接触技能编写的读者当成模板，也适合有经验的人参考我处理边界条件的方式。
6.2 分步编写：描述、参数与执行逻辑
第一步，写意图识别描述。我的初版描述：
这个技能用于从会议纪要、聊天记录或任务描述文本中提取待办事项，并按负责人、截止时间和任务内容整理成清单。当用户粘贴文本并表达“提取待办”“整理任务”“看看有哪些要做的事”等意图时调用。如果用户只是询问会议总结或进行文字翻译，请不要调用。
第二步，定义参数。核心参数只有一个，就是待分析的原始文本（text），类型为字符串，必填，长度限制按平台上限来。再给一个选填参数“是否需要按负责人分组”（group_by_owner），默认为否。随着版本迭代，我后来又加了“截止时间格式”参数，用来控制时间是输出为 YYYY-MM-DD 还是相对时间表达，默认输出绝对日期。
第三步，设计执行逻辑。这一步最关键。我是这么拆的：
- 校验文本是否为空，为空则提示用户提供内容。
- 扫描全文中的责任人标识，通常是“@某人”“某人负责”“由某某跟进”这一类的模式。
- 扫描截止时间表达，包括“X月X日前”“本周五之前”“EOD”这类说法，一一转换成标准日期。
- 提取动作描述，即“完成XX”“输出XX报告”“确认XX方案”这类含有实际任务的语句。
- 将提取结果组装成表格或列表，每条待办包含负责人、截止时间、任务内容三个字段。
- 如果在提取过程中发现某些待办缺少负责人或截止时间，在结果末尾单独列出“待补充信息”板块，而不是自作主张填空。
6.3 调试实录：我踩过的那几个坑
这个技能看起来简单，但真调试起来，问题一个接一个。我记录一下当初最有价值的几个问题点。
问题一：负责人识别把被动语态也抓进来了。文本里出现“这个方案被市场部否了”，我的技能竟然把“市场部”提取成了负责人。后来我设了一条规则，只有出现在“负责”“跟进”“牵头”“完成”这些动作动词附近的实体才被当作负责人候选，再配合提示词的内容约束，误识别率才降下来。
问题二：截止时间多义。“月底前完成”到底是指本月最后一天，还是下个月最后一天？如果上下文中提到了“下个月新版上线”，那“月底”大概率指“下个月底”。这种语义推断单靠规则很难全覆盖，我的应对方案是以当前时间点为基准，默认“月底”为当前自然月的最后一天，同时允许用户在生成结果后手动调整。
问题三：输出格式不稳定。有时候输出纯列表，有时候输出表格，用户反馈说“看得舒服的格式你就统一一下”。我后来干脆在输出提示词模板里固定了 Markdown 表格结构，并且对出现空字段的行做特殊标记。效果立竿见影，生硬程度上也好了很多。
问题四：长文本处理超时。有一段几千字的讨论记录，技能跑了十几秒才返回结果，体验很差。我做了两步优化：第一步，在提取前做文本裁剪，只保留包含责任人、时间或者动作关键词的句子，大幅缩短内容长度；第二步，把执行逻辑中的中间结果做缓存，用户微调参数后不需要重新全文解析。
6.4 效果评估与迭代方向
技能写完后，我拿了一批真实会议记录做测试。最开始准确率只有六成左右，主要表现在责任人误识别和部分口语化表达漏提。经过三轮规则和提示词的迭代，测试集上的准确率到了八成以上。需要说明的是，这类基于语义提取的技能，很难做到百分之百准确，因为自然语言的歧义是客观存在的。所以设计上要接受“机器初筛+人工确认”的协作模式，而不是期望技能全自动一步到位。
后续迭代方向可以考虑：接入日历系统自动创建任务、识别任务优先级、根据负责人维度汇总输出等。每加一个方向，都要重新审视参数和执行逻辑的扩展性，避免堆功能堆到不可维护。
7. 避坑指南：常见问题排查实录
7.1 技能不触发的排查顺序
技能“装聋”是反馈最集中的问题。我总结了一套排查顺序，按效率从高到低排列。
第一，检查描述里的触发表达和用户实际输入是否真的有匹配空间。很多时候用户不会用你预设的词，比如你写的是“生成周报”，用户说“帮我总结这周”，就匹配不上。第二，检查是否存在其他技能“截胡”。如果系统里同时存在“文档助手”“周报生成”等多个技能，意图识别可能被强描述的技能抢走。第三，检查描述是否被平台截断或格式解析异常。第四，检查触发条件是否设置了过高的置信度阈值。
这套排查流程我走下来，几乎所有“不触发”的问题都能在二十分钟内定位。最怕的是上来就怀疑是系统bug，然后反复改触发阈值，结果发现是描述写得太窄。
7.2 参数解析错误的典型特征
参数解析出错通常有迹可循。最常见的特征包括：多参数时只解析出第一个；时间表达被误读；数字单位丢失；并列结构被拆错。
我印象很深的一个案例：技能需要提取“3月15日和4月20日的会议安排”，结果系统把“3月15日”和“4月20日”以外的部分全部丢弃，用户追问时才发现技能只处理了前半段。排查后确认是参数规则里没有定义多值参数的切割方式。后来我在参数说明里明确标注了“本参数支持多个日期，用逗号分隔”，问题解决。
如果你用的平台支持自定义参数解析指令，一定要把格式示例写足。“参数说明要举例”这句话我强调多少次都不为过，因为模型对示例的敏感程度远超你对抽象描述的想象。
7.3 输出结果不稳定的处理策略
同一个技能，前后两次跑出来的结果格式不一样，这是初期最容易遇到的困扰。原因通常出在执行逻辑对固定模板的约束不够。解决思路是：在最终输出之前，增加一道“格式化整理”步骤，强制按模板输出，关键字段缺失时输出占位符或提示语，而不是让执行逻辑自由发挥。
还有一个技巧，就是在技能里加入“输出自查”环节。简单说，就是让技能在生成完结果后，再对照字段清单检查一遍，确认所有必填字段都已写入正确的位置。这个环节看似多此一举，但能明显提升输出稳定性，特别是在复杂技能的落地过程中。
7.4 多人协作编写时的规范建议
如果团队里有多个人同时维护一套技能库，没有统一规范的话，很快会乱成一锅粥。我建议至少约定以下几点。
一是描述格式统一，比如第一句必须是“这个技能用于做什么”，方便大家快速理解。二是参数命名遵循统一风格，用下划线或驼峰，不要一会儿一个样。三是每个技能维护一份变更记录，写明每次改了哪些地方、为什么改。四是定期清理废弃技能，保持技能库精简，避免意图识别相互干扰。
8. 从编写者到设计者的进阶建议
8.1 技能复用：模块化拆分的价值
当技能数量多起来，你会发现很多执行步骤是重复的。比如“从文本中提取时间”“从文本中识别责任人”，这些能力在多技能场景下反复出现。如果你把它们拆成公共子流程，而不是在每个技能里复制一遍，后续的维护成本会大幅下降。
模块化拆分有一个判断标准：如果同一段逻辑出现在三个以上技能中，就应该考虑抽出来复用。但也不要为了抽象而抽象，尤其是那些依赖特定上下文的逻辑，强行复用反而会引入更多配置复杂度。
8.2 先跑通，再优化：迭代式开发原则
我在技能编写上最大的心得，就是别指望一次写完美。任何一个技能，第一版能跑通主流程就算及格。先把主干流程走通，再根据错误反馈和用户习惯逐步补充边界条件、优化提示词、调整参数。如果一上来就想着把所有情况覆盖完，项目大概率会卡在某个边角细节里出不来。
有个朋友说过一句特别对的话：技能是一点一点“养”出来的，不是一次“写”出来的。你要有持续跟踪和调整的预期。
8.3 保持记录习惯：写技能日志
最后，强烈建议每个技能编写者养成记录的习惯。每调试一次，就把问题现象、原因分析和解决方案记一笔。三个月后回看，这份日志就是你最宝贵的私人手册。我当时就是这么做的，后面再写同类技能，直接翻日志就能避开一大半坑。
Skills 编写学习这事，说难也难，说简单也简单。核心还是你对任务过程的理解是否透彻，以及你愿不愿意在细枝末节上反复打磨。我见过有人花了大量时间研究模型参数，写出来的技能却连基本的业务逻辑都理不顺；也见过一些人方法论朴实，但每个技能都稳得惊人。差别就在这儿。希望这篇文章能把你的技能编写之路往前推一段，少走几条弯路。
