先讲个真实的经历。过去两个月我一直在跟Skills这个词较劲。第一次看到它是在研究AI Agent扩展能力的时候当时只是觉得这不就是把一堆prompt和脚本打包成技能包吗看起来没什么技术含量。直到我自己动手写了五六个skill把项目上下文搞得一团糟才真正摸清这套机制的门道。如果你也在用AI辅助写代码、处理文档、自动化一些重复性工作这篇文章应该能帮你少走不少弯路——不仅讲清楚Skills是什么、能做什么更重要的是告诉你它什么时候不该用。1. 先别急着写Skill这东西到底要解决什么问题先说一个很多人的痛点。你让AI帮你整理会议纪要每次都必须在对话里写一遍请把这段记录整理成结构化摘要包含议题、结论、待办事项输出Markdown格式然后保存到指定目录…… 下个月再来一次这些话你还得原样说一遍。如果AI聊着聊着忘了格式要求你还得重新解释。这就是对话式AI的先天缺陷——它没有肌肉记忆。Skills这套机制想解决的就是这个问题把某类任务的完成方式固化下来让AI在遇到相似请求时自动调用固定的流程和工具而不是每次从零开始理解你的要求。1.1 一种更容易理解的理解方式把Skill想象成AI的职业培训手册我有一个类比觉得特别贴切。普通的提示词Prompt像是口头叮嘱——告诉AI这一次怎么做而Skill更像是岗位培训手册——把做一件事情的完整流程、判断标准、输出规范都写清楚装上之后AI就自动掌握了这类任务的标准做法。在很多Agent框架里Skill通常由三部分组成一个描述什么时候用、怎么用的说明文档一个或多个承载具体执行逻辑的脚本以及可选的模板、参考文件等资源。AI会根据用户请求的意图判断是否该调用某个Skill调用时读取说明按步骤执行脚本最后汇总结果回复用户。1.2 和普通提示词的本质区别确定性普通提示词和Skill最大的区别在于确定性。你用提示词让AI生成一份报告它每次输出的结构可能都有所不同但通过Skill挂载的脚本把生成文件、命名、保存路径、格式校验这些环节固定下来每次执行结果都完全一致。拿我实际做过的一个场景举例。每周我都要把团队语音转写的内容整理成会议记录。以前用提示词AI偶尔会漏掉待办事项或者日期格式写得乱七八糟。后来我写了一个归档Skill把处理流程拆成语义理解部分交给大模型文件操作部分交给脚本从那之后整理会议纪要这件事彻底变成了把原始文本丢给它拿起归档好的文件就走。1.3 一套Skill机制的系统是如何协调工作的理解了Skills解决什么问题再看它在整套Agent系统里的位置就清晰了。一个Agent系统的典型构成是这样的大模型负责理解意图、拆解任务、决定调用什么工具Skill负责提供某类任务的完整执行方案告诉模型该怎么一步步做普通的Tool负责单一的、无状态的功能点比如读文件、写文件、发请求模型的工作记忆上下文窗口负责临时保存对话信息。Skill和Tool的区别很重要Tool是零件Skill是装配流程。比如读取文件内容是一个Tool而读取文件、提取标题、生成摘要、按日期归档、输出归档路径这一整套操作就是一个Skill。2. Skill的内部构造SKILL.md、scripts、resources的分工逻辑想用好Skills得先看透它的内部构造。目前业界比较通行的Skill结构大多沿袭了一套约定一个文件夹就是一个Skill里面通常包含三类内容。2.1 SKILL.md写给AI看的操作手册这个文件是Skill的核心。它通常用Markdown写成开头是一段YAML格式的元数据正文则是详细的执行指导。元数据里最关键的两个字段是name和descriptionAI就是靠这两个字段来判断什么情况下该调用这个技能。给你看一个实际的例子这是我自己写的一个归档Skill的SKILL.md头部--- name: meeting-minutes-archiver description: 当用户提供会议录音转写文本或会议记录需要整理成结构化摘要并归档时使用。触发词包括会议记录、纪要、minutes、meeting note。 ---正文部分应该包含什么我的习惯是写清楚三件事输入要求这个Skill期望收到什么样的数据处理步骤按顺序列出执行流程比如第一步阅读原始文本提取议题第二步调用scripts/parse_and_archive.py脚本……输出规范最终交付物的格式、命名规则、保存位置。2.2 scripts目录承载确定性的逻辑SKILL.md管的是思考和判断scripts管的是确定执行。凡是涉及精确计算、文件操作、数据处理的部分应该尽量写进脚本里而不是让大模型自由发挥。为什么一定要把逻辑写进脚本大模型的强项是语义理解弱项是精确执行。它可能记住了把所有文件名统一成yyyy-mm-dd格式但在实际操作中可能漏掉一个文件的改名。脚本不会有这种问题。所以在我的Skill里所有文件操作、格式校验、数据清洗都会甩给Python脚本处理。这是SKILL.md中关于脚本调用的描述我会写得很具体避免模型自作主张## 执行步骤 1. 读取用户提供的会议记录原始文本。 2. 提取以下信息会议日期、参会人、议题列表、结论、待办事项。 3. 将提取结果写入临时JSON文件。 4. 在终端执行以下命令 python3 scripts/parse_and_archive.py --input 临时JSON文件路径 5. 将脚本输出的归档文件路径告知用户。2.3 resources目录放模板和参考数据第三类内容是可选的资源目录用来存放模板文件、参考数据、常见问题库等。举个具体场景如果你想让AI生成的会议纪要一律遵循公司规定的模板就把模板Markdown文件放在resources/templates/meeting-template.md然后在SKILL.md里指定输出格式必须符合resources/templates/meeting-template.md的结构。这里有一个关键认知resources目录里的内容会在AI调用Skill时被读取并塞进上下文。因此只放必要的模板和参考资料千万别把整个知识库都塞进去不然每次调用都会白白消耗大量上下文窗口。2.4 三类文件的协作逻辑用一张表说清楚组成部分核心职责主要消费方写错了的后果SKILL.md定义触发条件、执行步骤、输出规范大模型AI不知道何时该调用或调用后流程混乱scripts/执行精确计算、文件读写、数据转换Python/Shell解释器输出格式不符合要求或脚本执行崩溃resources/提供模板、参考示例、静态数据大模型上下文被占满每轮对话越来越慢3. 手写一个会议纪要归档Skill从需求拆解到完整落地光看结构理解不深我带你完整走一遍我自己写Skill的过程。这个例子麻雀虽小五脏俱全包含了Skill设计的大多数考点。3.1 第一步需求拆解我的需求很简单团队语音转写出一段杂乱文本后AI需要整理成结构化摘要并按「年/月/主题.md」的路径存档到本地目录。拆解一下这个需求里哪些环节适合大模型、哪些环节适合脚本适合大模型的理解转写文本中的语义、提取议题和结论、判断主题归属适合脚本的自动创建目录、写入文件、校验文件名合法性、检查是否重复归档。明确了分工开始搭骨架。3.2 第二步建目录结构我的Skill文件夹命名是meeting-minutes-archiver放在skills目录下。结构如下meeting-minutes-archiver/ ├── SKILL.md ├── scripts/ │ └── parse_and_archive.py └── resources/ └── templates/ └── meeting-template.md3.3 第三步写SKILL.mdSKILL.md的内容我一共迭代了三版这里直接放最终版。有几个地方是现实中真正踩过坑后补上的我先卖个关子。--- name: meeting-minutes-archiver description: 用于将会议录音转写文本整理为结构化会议纪要。触发条件用户提到会议记录、语音转写、meeting minutes、纪要归档。输入可以是口语化且杂乱的长文本。 license: MIT --- # 会议纪要归档技能 ## 任务目标 将用户提供的原始会议转写文本整理为规范、结构化的会议纪要并归档到本地文件夹。 ## 输入要求 - 用户直接提供文本内容或提供转写文件的路径。 - 文本可能是口语化、无标点、含语气词的原始转写。 ## 执行步骤 1. 阅读转写文本提取以下字段 - date会议日期。如果没提到取当前日期 - title根据讨论主题提炼一个简短标题 - attendees参会人姓名列表 - topics按主题归类的议题列表 - conclusions各项议题达成的结论 - action_items待办事项格式为「负责人|事项|截止时间」。 2. 使用resources/templates/meeting-template.md作为输出结构模板。 3. 将步骤1提取的JSON数据写入临时文件/tmp/meeting_data_XXXX.json。 4. 执行归档脚本 python3 scripts/parse_and_archive.py --input /tmp/meeting_data_XXXX.json --output-dir ~/meeting-archive 5. 向用户展示脚本返回的归档文件路径并概述会议纪要要点。 ## 输出规范 - 最终存档文件名格式YYYY-MM-DD_标题.md - 如果脚本检测到同日期同标题的文件已存在自动在文件名末尾追加序号。3.4 第四步写Python脚本接下来是scripts/parse_and_archive.py。脚本负责接收JSON数据、套模板、写文件。注意我特意加了参数校验和重复名处理。#!/usr/bin/env python3 import json import sys import os import argparse from datetime import datetime from pathlib import Path def load_template(template_path): with open(template_path, r, encodingutf-8) as f: return f.read() def safe_filename(title: str) - str: # 去掉文件名中的非法字符 for ch in [/, \\, :, *, ?, , , , |]: title title.replace(ch, _) return title.strip()[:50] def main(): parser argparse.ArgumentParser() parser.add_argument(--input, requiredTrue, helpJSON数据文件路径) parser.add_argument(--output-dir, requiredTrue, help归档根目录) args parser.parse_args() with open(args.input, r, encodingutf-8) as f: data json.load(f) date_str data.get(date) or datetime.now().strftime(%Y-%m-%d) title safe_filename(data.get(title) or 未命名会议) year date_str[:4] # 构造目标目录输出目录/年/ target_dir Path(args.output_dir) / year target_dir.mkdir(parentsTrue, exist_okTrue) template load_template(Path(__file__).parent.parent / resources / templates / meeting-template.md) content template.replace({{DATE}}, date_str) content content.replace({{TITLE}}, data.get(title, )) content content.replace({{ATTENDEES}}, \n.join(f- {name} for name in data.get(attendees, []))) content content.replace({{TOPICS}}, \n.join(f- {t} for t in data.get(topics, []))) content content.replace({{CONCLUSIONS}}, \n.join(f- {c} for c in data.get(conclusions, []))) content content.replace({{ACTION_ITEMS}}, \n.join(f- {item} for item in data.get(action_items, []))) # 处理重名追加序号 base_path target_dir / f{date_str}_{title} path Path(str(base_path) .md) counter 1 while path.exists(): path Path(str(base_path) f_{counter}.md) counter 1 path.write_text(content, encodingutf-8) print(json.dumps({archived_path: str(path)})) if __name__ __main__: main()3.5 第五步测试与迭代Skill写完不等于完事测试才是重头戏。我第一次测试时直接在对话里丢了一段会议转写结果AI在调用脚本前自己脑补了一个JSON文件路径脚本自然找不到文件。我马上回去改SKILL.md在第三步明确写上将JSON写入系统临时目录并在命令中传入完整路径。加了这句话之后后面几十次调用再没出过文件路径问题。还有一个迭代很典型。最初我把description写成处理会议记录结果用户发一份普通的聊天记录也让AI去调用输出格式完全不合适。后来我把触发条件细化加上了具体的触发词和示例句式AI的判断立刻准确了很多。测了三轮这个Skill才算真正稳定下来。4. 三个月实战踩坑合集触发过载、错误吞掉、权限失控Skill能用起来只是第一步。真正折磨人的是上线之后的各种异常我挑四个最有代表性的坑展开说说每个都是我实打实踩过、排查过的。4.1 触发过载description写太宽AI什么活都往这里塞第一个坑来得最快。我最初写的归档Skilldescription里有一句处理文本整理相关的需求。这句话简直是灾难——用户让AI润色一段文字它也调用归档脚本用户让AI写一封邮件它也调用归档脚本。结果脚本收到大量不该处理的输入频繁报错整个对话体验非常糟糕。排查过程不算难。我翻脚本运行日志发现调用来源五花八门根本不是会议场景。定位到问题在于description里的文本整理这个泛化词让模型误判了触发范围。修复方案是重写description把触发条件限定得极其严格description: 仅当用户提供会议语音转写、会议记录、讨论摘要等需要生成结构化会议纪要的原始材料时使用。日常文本润色、邮件撰写、普通聊天整理不得使用本技能。重要经验AI判断是否调用Skill主要看description和当前用户请求的语义相似度。写得太宽它会变得极其积极写得太窄它则几乎不会触发。理想状态是用户明显需要且仅在此类需求时触发。4.2 错误吞掉脚本抛出异常AI却对用户说一切正常这可能是最危险的一个坑。有几次脚本因为输入数据格式不对抛出了异常但AI看完终端输出后没意识到是错误信息照样对用户说归档已完成。根因我查了很久——SKILL.md里没有强调错误处理AI看到输出的是一堆看不懂的堆栈以为这是正常执行过程中的中间信息。修复分两步。第一步在脚本里加了一个铁律任何未捕获的异常必须在程序退出前打印明确的关键词【脚本执行失败】加原因。第二步在SKILL.md执行步骤里加了一条如果输出包含脚本执行失败字样立即停止归档流程向用户说明失败原因和最近一次成功保存的位置。这里我有一个深刻的感悟所有Skill里的脚本都是替你直接在用户的文件系统上操作。这种确定性既是Skill的价值所在也是它的风险所在。给脚本加上清晰的错误信号就是给整个调用链加一道安全锁。4.3 上下文污染resources用得越爽对话越慢越贵第三个坑是资源加载失控。我一度习惯把各种模板、参考示例全塞进resources觉得这样AI产出质量高。结果负责的Skill调用时一次性能吃掉8万多token的上下文普通任务两三轮就把上下文窗口占满了后面对话越来越慢。后来我做了个实验同样的Skill把resources里七个模板砍到只剩两个核心模板剩余五个改成仅在用户明确要求特殊格式时才由AI按需读取。结果输出质量几乎没下降对话速度却快了一大截。想想也合理大模型读取逻辑是这样的调用Skill时SKILL.md和它引用的资源通常会载入上下文并保持一定时间的记忆。既然是记忆就有容量上限。把低频参考数据从常驻内存里挪出去能给真正最重要的指令腾出空间。4.4 权限失控脚本权限太大半夜差点删错文件夹最后这个坑带着点惊悚色彩。有一次我设计一个清理临时文件的Skill图省事让脚本直接执行删除指定目录下所有早于7天的文件而目录路径由模型从对话里提取。结果AI理解错了用户说的项目目录差点把另一个项目的缓存目录当成目标。从那以后我给自己立了一个规矩凡是涉及删除的操作脚本必须首先打印将被删除的文件清单且必须经过用户二次确认才执行实际删除脚本默认以最小权限运行能只读就不写能只写指定目录就绝不扫描全盘危险操作的默认策略是先断言、再执行。把这些约束直接写进SKILL.md让它成为AI执行的一部分而不是指望AI自己临场判断。5. 我总结的Skill取舍标准高频、确定、上下文敏感被坑过这么多次再回头总结哪些场景值得写成Skill心里就有清晰的标尺了。不是所有任务都适合Skill化判断标准归纳起来是三条。5.1 高频是硬门槛如果一个任务你每周用不到三次暂时不值得为它写Skill。因为写Skill本身有成本——设计结构、编写脚本、反复测试、维护迭代这些前期投入如果不被高频使用摊薄性价比很低。我第一个Skill就是笑话生成器新鲜感过了就再没用过纯属浪费。反过来那些让你觉得又要重复做一遍了的任务恰恰是Skill的最佳候选。对我而言会议纪要归档、周报汇总、代码仓库初始化提醒这些高频又固定的事都值得被固化。5.2 确定性越强Skill价值越大Skill擅长的是有明确规则、可标准化流程的任务。比如输入一段文字输出特定格式的摘要把一批文件按规则重命名归档读取配置模板批量化生成文档。这些任务的结果是可预期的流程是可拆解的适合做成Skill。而探索性任务强烈不建议Skill化。比如帮我分析这份竞品报告并提出创新建议这类任务的核心价值在于模型的发散思考固化流程反而限制发挥。硬要写成Skill结果就是一坨呆板的模板化输出。5.3 上下文敏感度影响设计方式第三种判断标准经常被忽略——任务是否强依赖实时信息。如果任务每次执行都需要读取最新数据比如查询数据库当前内容、读取远程接口响应Skill设计时要格外小心要么把获取实时数据做成一个独立的Tool嵌入流程要么在SKILL.md里明确要求先调用数据获取工具再进行后续处理避免AI凭记忆输出旧数据。5.4 清理Skill和写Skill同样重要说了这么多怎么建Skill最后必须提一句怎么删Skill。我的建议是每两周花十分钟review一遍手上的Skill列表看看每个技能的调用次数。连续两周没被调用过的先归档再说。很多人舍不得删自己写过的Skill觉得以后可能用得上——这个想法看似合理实际上会不断累积上下文噪声。AI每次接到任务都会在所有已安装Skill的description里做语义匹配技能库越臃肿匹配失误的几率越高。我现在维护的原则是少而精。常用的大概只有五六个每一个都经过实战打磨SKILL.md写得具体精准脚本带完整的错误处理和权限限制。这套机制用下来最大的感受反而不是任务自动化了而是信任终于建立了——你可以放心地让AI去执行一套标准化流程而不必每次都在旁边紧张地盯着它有没有走样。