1. 从“每次都要重新讲一遍”说起skill-creator 到底解决什么问题如果你带过团队、做过交付、或者只是长期用 AI Agent 处理重复性工作一定遇到过这种场景某个流程你已经跑通了步骤清晰、参数明确、坑也踩过了但每次换个人、换个会话、换个项目就得从头再讲一遍。讲的人累听的人懵最后执行出来的结果还参差不齐。skill-creator这个项目要解决的就是这件事。它的核心思路非常直接把一套已经验证过的操作流程沉淀成一个结构化的 Skill 文件让 Agent 能够识别、触发并复用。你不再需要每次手动复述“第一步做什么、第二步注意什么”而是把这些内容写进一个SKILL.md里Agent 在合适的时机自动加载并执行。我第一次接触这个概念的时候脑子里蹦出来的类比是“把老师傅的手艺写成操作手册”。但后来发现这个类比还不够准确。操作手册是给人看的而 Skill 是给 Agent 看的——它不仅要写清楚“怎么做”还要写清楚“什么时候做”“做到什么程度算完成”“遇到什么情况该停下来”。这就涉及description的写法、触发条件的定义、以及和 Agent 框架的配合方式。适合谁来参考这篇内容三类人。第一类是把 AI Agent 当日常工具用的重度用户想让自己的重复操作自动化第二类是团队里负责流程标准化的角色想把个人经验变成团队资产第三类是对 Agent 开发感兴趣、想理解 Skill 机制底层逻辑的技术人。不管你属于哪一类接下来的内容都会从设计思路讲到实操细节尽量让你看完就能动手做一个自己的 Skill。2. 整体设计思路为什么是 SKILL.md而不是别的形式2.1 Skill 和 Agent 的关系一个负责“会做”一个负责“知道何时做”很多人一开始会混淆 Skill 和 Agent。简单说Agent 是一个能自主决策、调用工具、多步执行的智能体Skill 是它手里的一本“专项操作手册”。Agent 负责判断当前任务需不需要某个 SkillSkill 负责告诉 Agent 具体怎么做。这个分工很关键。如果没有 SkillAgent 每次都要靠通用推理去拼凑步骤结果不稳定如果只有 Skill 没有 Agent那它就是一份静态文档没人触发就不会执行。两者配合起来才能实现“可复用、可触发”。从架构上看Skill 通常以文件形式存在最常见的就是SKILL.md。这个文件里包含几个核心要素名称、描述、触发条件、执行步骤、注意事项、输出格式。Agent 在运行时会扫描可用的 Skill 列表根据当前对话上下文判断是否匹配某个 Skill 的触发条件匹配上了就加载对应的SKILL.md内容然后按照里面的步骤执行。2.2 为什么用 Markdown 而不是代码或 JSON你可能会问为什么不用 Python 脚本或者 JSON 配置来定义 Skill原因有三个。第一可读性。Markdown 是人和机器都能读的格式。你写完之后团队成员可以直接 review不需要懂代码。Agent 解析起来也不复杂按标题层级和段落结构提取信息就行。第二灵活性。代码是确定性的但很多操作流程包含判断和模糊地带。比如“如果用户没有提供目标平台默认按通用格式输出”——这种逻辑用自然语言写在 Markdown 里Agent 能理解写成代码反而僵硬。第三可维护性。流程会变参数会调坑会新增。Markdown 改起来成本最低不需要重新编译、不需要跑测试改完保存就生效。对于快速迭代的场景这一点非常重要。注意Markdown 的灵活性也意味着你需要更严格地约束格式。如果SKILL.md写得像散文Agent 提取信息时容易漏掉关键步骤。建议用固定的标题层级和列表结构来组织内容。2.3 触发机制的设计description 是灵魂一个 Skill 能不能被正确触发八成取决于description写得好不好。写得太宽泛Agent 会在不相关的场景下乱加载写得太窄该触发的时候又匹配不上。我的经验是description要同时包含三个信息做什么、什么时候用、不适用于什么情况。比如一个“周报生成 Skill”的描述可以写成“当用户需要整理本周工作内容并生成结构化周报时使用。适用于有明确任务列表和进展记录的场景不适用于需要实时数据拉取的场景。”这样 Agent 在判断时就有明确的边界。另外description里最好包含一些用户可能说的自然语言关键词因为 Agent 匹配时往往基于语义相似度关键词能提高命中率。2.4 方案选型的取舍自建 vs 复用现有框架如果你只是想自己用最简单的做法就是在本地建一个skills目录每个 Skill 一个子目录里面放SKILL.md。Agent 启动时扫描这个目录把每个 Skill 的description加载到上下文里需要时再读取完整内容。如果你在团队里推广可能需要考虑版本管理。Git 是最自然的选择——每个 Skill 一个文件改动有记录review 有依据。但要注意Skill 的更新频率可能很高如果每次改动都走完整的 PR 流程反而会拖慢迭代。折中方案是核心 Skill 走 review实验性 Skill 允许直接提交定期清理。还有一种情况是复用现有 Agent 框架自带的 Skill 机制。不同框架对 Skill 的支持程度不一样有的只支持简单的指令注入有的支持完整的文件加载和触发判断。选型时要看你的 Agent 是否支持动态加载外部文件以及触发判断是基于关键词还是语义。如果框架不支持你就需要自己在 Agent 的 prompt 里手动注入 Skill 列表或者写一层简单的匹配逻辑。3. 核心细节解析一个高质量 SKILL.md 应该长什么样3.1 文件结构从名称到输出格式的完整拆解一个标准的SKILL.md通常包含以下几个部分。我用一个“会议纪要整理 Skill”作为例子来说明。# 会议纪要整理 ## 描述 当用户提供会议录音转写文本或会议要点草稿需要整理成结构化会议纪要时使用。 适用于有明确议题和讨论内容的会议记录不适用于纯头脑风暴或无结论的讨论。 ## 触发条件 - 用户提到“整理会议纪要”“会议记录”“meeting notes” - 用户提供了大段的会议对话文本或要点列表 - 用户要求输出包含“决议事项”“待办任务”“责任人”的内容 ## 执行步骤 1. 通读输入内容识别会议主题和参与角色 2. 提取讨论要点按议题分组 3. 识别决议事项标注责任人和截止时间 4. 整理待办任务按优先级排序 5. 按指定格式输出 ## 输出格式 - 会议主题 - 参与角色 - 议题与讨论摘要 - 决议事项含责任人、时间 - 待办任务含优先级 ## 注意事项 - 如果输入内容缺少责任人信息标注“待确认”而不是猜测 - 如果讨论内容存在矛盾保留双方观点并标注 - 不要添加输入中没有的信息这个结构看起来简单但每一部分都有讲究。下面逐项拆解。3.2 描述与触发条件让 Agent 在对的时候找到你描述和触发条件是 Agent 判断是否加载这个 Skill 的依据。描述要简洁但信息完整触发条件要具体但不过度限制。我见过最常见的错误是把描述写得太短比如只写“整理会议纪要”。这样 Agent 在遇到任何和会议相关的内容时都可能加载包括“帮我安排一个会议”“会议场地推荐”这种完全不相关的请求。加上“当用户提供会议录音转写文本或会议要点草稿”这个限定后匹配精度会明显提升。另一个错误是触发条件写得太死比如只写“用户说‘整理会议纪要’”。但实际使用中用户可能说“帮我把这段会议内容理一下”“这些讨论要点帮我汇总成文档”。所以触发条件里要包含多种表达方式或者用更语义化的描述让 Agent 自己判断。实操心得写完触发条件后拿几个真实的历史对话测试一下。看看哪些该触发的没触发哪些不该触发的触发了。根据结果调整描述和条件通常迭代两三轮就能达到比较稳定的效果。3.3 执行步骤颗粒度决定可复现性执行步骤是 Skill 的核心。颗粒度太粗Agent 执行时自由发挥空间太大结果不稳定颗粒度太细又可能限制 Agent 处理边界情况的能力。我的建议是关键决策点写细常规操作写粗。比如“识别决议事项”这个步骤如果决议的判定标准很模糊就需要写清楚“什么算决议”——是有明确结论的、有责任人的、有后续动作的。而“按议题分组”这种操作Agent 本身就能做好不需要展开。另外步骤之间最好有明确的顺序和依赖关系。如果某一步需要前一步的输出要写清楚。如果某几步可以并行也可以标注出来。这样 Agent 在执行时能更好地规划。3.4 输出格式用示例代替描述输出格式部分最有效的方式是直接给一个示例。Agent 对示例的理解能力远强于对抽象描述的理解。比如与其写“输出应包含会议主题、参与角色、议题摘要”不如直接给一个填好内容的模板。## 输出格式示例 **会议主题**Q3 产品路线图评审 **参与角色**产品经理、技术负责人、设计负责人 **议题与讨论摘要** 1. 新功能优先级排序——讨论了三个候选功能的投入产出比 2. 技术债务处理——确认了本季度需要重构的模块 **决议事项** - 新功能 A 优先开发责任人张三截止时间7月15日 - 技术债务重构分两批进行责任人李四截止时间8月30日 **待办任务** - [高] 输出新功能 A 的详细需求文档——张三 - [中] 评估重构模块的测试覆盖方案——李四有了这个示例Agent 输出时会自然对齐格式不需要你反复调整。3.5 注意事项把踩过的坑写进去注意事项是 Skill 里最有价值的部分因为它承载的是“经验”。常规步骤谁都能写但注意事项是你踩过坑之后才知道要加的东西。比如上面会议纪要的例子“如果输入内容缺少责任人信息标注‘待确认’而不是猜测”这一条就是典型的经验沉淀。如果没有这条Agent 很可能会自己编一个责任人名字导致后续执行出错。写注意事项时尽量用“如果……就……”的句式把条件和应对方式绑定。这样 Agent 在遇到对应情况时能直接执行不需要额外推理。4. 实操过程从零做一个可触发的 Skill4.1 环境准备与目录结构假设你用的是支持本地文件加载的 Agent 框架第一步是建目录。推荐的结构如下skills/ ├── meeting-notes/ │ └── SKILL.md ├── weekly-report/ │ └── SKILL.md └──># 数据清洗 ## 描述 当用户提供原始数据文件或数据片段需要进行去重、空值处理、格式统一、异常值标记等清洗操作时使用。 适用于结构化表格数据不适用于非结构化文本或图像数据。 ## 触发条件 - 用户提到“数据清洗”“数据整理”“去重”“补空值” - 用户提供了包含缺失值、重复行或格式不一致的表格数据 - 用户要求对数据进行标准化处理第二步写执行步骤。这里我把每一步的操作意图也写进去方便 Agent 理解为什么要这么做## 执行步骤 1. 读取数据识别列名和数据类型意图建立数据概览判断后续处理方式 2. 检查重复行按所有列或指定列去重意图避免重复数据影响统计结果 3. 检查空值按列类型选择填充策略 - 数值列用中位数填充并新增标记列 - 文本列用“未知”填充并新增标记列 意图保留空值信息避免直接删除导致样本偏差 4. 统一格式日期列统一为 YYYY-MM-DD数值列保留两位小数 5. 标记异常值数值列超出 3 倍标准差范围的值标记为异常 6. 输出清洗后的数据和清洗报告第三步写输出格式和注意事项## 输出格式 - 清洗后的数据表 - 清洗报告包含原始行数、去重后行数、各列空值数量、异常值数量 ## 注意事项 - 如果某列空值比例超过 50%先提示用户确认是否保留该列 - 异常值标记不要直接删除保留原始值并新增标记列 - 日期格式统一时如果原始格式无法识别保留原值并标注写完这四部分一个可用的 Skill 就成型了。整个过程大概 20 分钟但后续能节省的时间是持续的。4.3 触发测试怎么验证 Skill 能被正确加载写完不等于能用。必须做触发测试。我的做法是准备一组测试用例包含“应该触发”和“不应该触发”两类。测试输入预期结果实际结果调整“帮我把这份销售数据清洗一下”触发触发无需调整“这份表格有重复行帮我处理”触发触发无需调整“帮我分析一下这份销售数据”不触发触发了在描述中增加“不适用于数据分析场景”“推荐一个数据可视化工具”不触发不触发无需调整测试过程中发现的问题主要通过调整描述和触发条件来解决。如果 Agent 框架支持查看匹配分数可以更精确地定位问题——分数接近阈值时说明描述需要更明确。4.4 迭代优化从能用 to 好用第一版 Skill 通常只能做到“能用”。要让它“好用”需要在实际使用中持续迭代。我通常会关注三个信号第一触发失败。用户明明在做对应操作但 Agent 没有加载 Skill。这时候要检查描述里是否缺少用户常用的表达方式。第二执行偏差。Skill 被触发了但执行结果和预期不一致。这时候要检查步骤是否写得太粗或者注意事项没有覆盖到对应情况。第三过度触发。在不相关的场景下加载了 Skill。这时候要收紧触发条件或者在描述里明确排除场景。每次迭代不需要大改往往加一句话、调一个词就能明显改善。关键是养成“用完就记”的习惯——遇到问题随手在SKILL.md里加一条注意事项下次就不会再犯。5. 常见问题与排查技巧实录5.1 触发相关问题的排查思路触发问题是最高频的。我整理了一个速查表覆盖大部分情况问题现象可能原因排查方法解决方式该触发时不触发描述缺少关键词对比用户实际表达和描述用词补充同义表达该触发时不触发触发条件太窄检查是否只写了特定句式改为语义化描述不该触发时触发描述太宽泛看是否缺少场景限定增加“不适用于”说明不该触发时触发关键词歧义检查是否有通用词替换为更具体的词触发不稳定描述模糊多次测试看匹配分数明确核心场景排查时有一个技巧把 Agent 的匹配日志打开看它给每个 Skill 打的匹配分数。如果目标 Skill 的分数接近但没超过阈值说明描述需要更聚焦如果分数很低说明描述和用户表达差距太大。5.2 执行结果不稳定的原因与对策Skill 被正确触发了但每次执行结果不一样这通常是因为步骤颗粒度不够。Agent 在模糊的地方会自由发挥导致输出波动。对策是把关键决策点写死。比如“按优先级排序”这种步骤要写清楚优先级怎么定义——是高/中/低三档还是按截止时间还是按影响范围。写清楚了Agent 就不会每次用不同标准。另一个原因是注意事项覆盖不足。比如数据清洗时遇到某列全是空值第一版 Skill 没写这种情况怎么处理Agent 可能直接删列也可能保留。后来加了“如果某列空值比例超过 50%先提示用户确认”行为就一致了。5.3 多个 Skill 冲突时的处理当你有十几个 Skill 时可能会出现两个 Skill 都匹配当前请求的情况。比如“数据清洗”和“数据分析”可能同时被触发。处理方式有两种。一种是优先级机制在 Skill 里加一个优先级字段Agent 在多个匹配时选优先级高的。另一种是互斥声明在描述里写清楚“本 Skill 不处理分析类请求分析请使用数据分析 Skill”。我更推荐第二种因为它把判断逻辑放在了 Skill 内部不需要 Agent 框架支持额外的优先级机制。而且写互斥声明的过程本身也是梳理 Skill 边界的好机会。5.4 团队协作中的版本管理经验团队共用 Skill 时最大的问题是“谁改了什么、为什么改”。我的做法是每个 Skill 文件头部加一个变更记录区记录每次修改的日期、修改人、修改内容核心 Skill 走 Git PR实验性 Skill 允许直接提交每月做一次 Skill 清理把三个月没触发过的 Skill 归档变更记录不需要很正式几行字就行。比如## 变更记录 - 2025-06-01 张三增加空值比例超过 50% 的处理逻辑 - 2025-05-15 李四调整触发条件增加“数据整理”关键词这样即使过了很久回头看也能快速理解每次改动的原因。5.5 独家避坑技巧汇总最后分享几个我在实操中总结的技巧都是文档里不会写的技巧一先写注意事项再写步骤。很多人习惯先写步骤再补注意事项但这样容易漏掉边界情况。反过来先想“这个流程最容易出什么错”把注意事项列出来再根据注意事项去设计步骤覆盖度会更好。技巧二用真实对话测试不要用自己编的句子。自己编的测试句子往往太规范和用户实际表达差距大。直接从历史对话里找真实请求来测试效果更准。技巧三Skill 名称用动词开头。比如“整理会议纪要”比“会议纪要”更好因为 Agent 在匹配时动词能提供更多语义信息。技巧四不要追求一次写完美。第一版只要能触发、能跑通就行。后续在使用中持续迭代比花两小时写一个“完美”版本更有效。技巧五定期回顾触发日志。看看哪些 Skill 从来没被触发过哪些频繁误触发。前者可能是描述有问题后者可能是边界没划清。这个习惯能让你的 Skill 库保持健康。6. 进阶方向让 Skill 从“单点工具”变成“能力网络”当你有了几个可用的 Skill 之后可以考虑让它们之间产生关联。比如“数据清洗 Skill”执行完之后可以自动触发“数据分析 Skill”“会议纪要 Skill”输出的待办任务可以触发“任务跟踪 Skill”。实现方式有两种。一种是在 Skill 的输出格式里约定“下一步建议”Agent 看到后自动加载对应 Skill。另一种是在 Agent 层面做编排把多个 Skill 串成工作流。前者更轻量后者更可控。另一个方向是给 Skill 加参数。比如“数据清洗 Skill”可以接受一个填充策略参数用户可以选择用中位数、均值还是固定值填充空值。参数化之后一个 Skill 能覆盖更多场景减少 Skill 数量。还有一个值得尝试的方向是 Skill 的自动生成。当你发现某个操作流程被重复执行了多次可以让 Agent 根据历史记录自动生成一个 Skill 草稿你只需要 review 和调整。这能大幅降低沉淀 Skill 的门槛。我在实际使用中发现Skill 库的价值不是线性增长的。前五个 Skill 可能只是省了一些重复劳动但当 Skill 数量超过十个、并且开始互相配合时整个 Agent 的工作效率会有明显跃升。因为这时候 Agent 不再是一个“什么都要现学”的新手而是一个“带着工具箱”的熟练工。如果你还没开始做自己的 Skill建议从最高频、最标准化的那个流程入手。不用追求大而全先做一个能跑通的小 Skill感受一下“写一次、用多次”的收益。踩过几次坑之后你会慢慢找到适合自己工作节奏的 Skill 设计模式。
