几年前我们聊AI说的是“模型有多大、参数有多少”后来大家开始聊“提示词写得巧不巧”再后来话题变成了“Agent能调什么工具”。而最近这段时间不管是Claude生态还是Codex社区都在疯狂追一个叫“skills”的概念。有人把它捧成“AI Agent的超级能力”有人一头雾水地问这不就是另一个插件格式吗如果你也盯着“skills”这个词琢磨过我建议你先别急着下载这个、部署那个。先用第一性原理把一件事搞清楚skills到底解决了什么问题它和插件、工具、MCP这些我们好不容易才分清楚的名词又是什么关系这篇文章我会从原理层面把skills拆开再带你手写一个能复用的技能包最后分享一些我在实际项目中踩过的坑和筛选经验。看完之后你自己就能判断这玩意儿值不值得投入以及怎么用才不浪费。1. Skills是什么从“会聊天”到“会干活”的关键一跃1.1 先看清它到底改变了什么先说结论skills是一套把“提示词、流程、参考资源、可执行脚本”打包成一个文件夹的标准格式Agent用之前会先“阅读理解”这个文件夹的说明文件然后按里面的步骤和脚本去完成一类具体任务。为什么要搞这么个东西因为纯靠对话式的AI有个很致命的毛病每次都是“从零开始”。你让它写周报它每次都得重新理解“周报要包含哪些维度”你让它做数据分析它每次都得重新摸索“数据清理流程”。哪怕你把这些要求写进系统提示词下次换个对话、换个Agent又得重新来一遍。而skills把“怎么完成一类任务”固化成标准化模块——一次编写到处复用。这才是它区别于普通提示词的核心价值。这么说有点抽象打个比方普通提示词像是你口头跟助理交代“帮我把明天会议记一下按老规矩整理”skills则是你交给助理一本《会议纪要标准作业手册》手册里连模板、检查清单、常用工具都备好了。助理翻开手册就能干活而且每次干出来的水平都稳定。所以你现在看很多Agent框架都在往“skills”上靠根本原因不是赶时髦而是它们都意识到真正让Agent变得可用的不是模型多聪明而是它能不能稳定复用人类沉淀下来的操作流程。1.2 Skills、Tools、MCP别再傻傻分不清很多人一看到skills有脚本、有工具调用就觉得它和MCP是一回事。实话讲我第一次看到官方文档时也有点恍惚。但把三者放在一张表里对比区别立刻就清楚了。维度Prompt提示词Skill技能包Tool / MCP工具/外部服务本质对话时的指令文本结构化的知识流程脚本外部能力接口生命周期随对话消失静态文件可长期复用常驻服务按需调用是否需要运行环境不需要可能需要脚本环境通常需要独立服务网络依赖无无使用时注入上下文有实时请求外部API适用场景临时性指导反复执行的固定流程实时数据获取、外部动作举例“帮我写得专业一点”“写周报的标准流程”“查天气”“发邮件”关键区别就两条第一Skill本身不一定调用外部服务。它把“如何做事”的说明和参考资料打包好Agent在需要时把它作为上下文读进来。而MCP是实时连接外部系统的桥梁强调的是“操作能力”。第二Skill是可组合、可版本管理的静态资产。你可以把它提交进Git仓库同事clone下来就能用而MCP服务通常要跑起来才能调。更准确地说skills和工具并不互斥而是互补关系skill负责“知道怎么做”工具负责“实际去执行”。一个成熟的Skill里甚至可以包含“推荐使用哪个MCP工具”的说明。1.3 为什么说它是“第一性原理”式设计“第一性原理”这个词被用滥了但放在skills上还真挺贴切。因为它把“Agent能力”这个模糊概念还原成了几个最基础的构成要素知识说明文档、过程步骤清单、资源数据/模板、执行力脚本/工具。想象一下没有skills的年代你想让AI按公司规范生成合同需要做几步先写详细的步骤提示词再把公司合同模板贴进对话还要祈祷AI别发挥创意乱改条款。每次对话都得来一遍而且换个人用又得重新教。skills则直接规定一份合同生成技能 SKILL.md行为说明 references/templates/合同模板池 scripts/条款校验脚本。Agent识别到任务后自动加载这套组合按说明执行。这不是“让AI更聪明”而是“让AI变规范”。把隐性经验显性化、把临时流程结构化这才是skills最接近第一性原理的地方。它没有增加新能力却让已有能力变得可复制、可传承。2. 核心机制拆解一个Skill内部到底长什么样2.1 最小单元一个目录从文件系统的视角看一个Skill就是一个有固定约定的目录而不是某个单一文件。这个设计很朴素但非常重要——它意味着技能包可以包含任意复杂度的素材。下面是一个常见的布局示例skill-name/ ├── SKILL.md # 技能说明文件核心必须存在 ├── scripts/ # 可执行脚本按需调用 │ └── generate_chart.py ├── references/ # 参考资料、模板、示例 │ ├── weekly_report_template.md │ └── examples/ └── assets/ # 静态资源图片、样式、数据文件目录结构看起来自由但有几个规则是硬性的SKILL.md 必须存在这是Agent识别技能包的“身份证”。没有它整个文件夹只会被当作普通文件目录。文件夹命名要语义化比如weekly-report别叫my_skill_20250101。因为Agent很多时候通过目录名来建立粗认识。超过一定大小限制后要拆references不要把几百页资料全塞进一个说明文件。2.2 SKILL.md是怎么被“读懂”的SKILL.md是整个技能包的核心它的写法直接决定Agent会不会正确使用这个技能。不需要把它当成“程序”而是要当成“写给另一个工程师看的操作手册”。典型的SKILL.md由两部分组成YAML格式的元信息头和Markdown正文。--- name: weekly-report description: 根据本周工作日志生成规范化周报。适合项目周会前的汇报整理可自动提取任务进度、风险与下周计划。 --- # 周报生成技能 ## 什么时候用 - 用户要求生成周报 - 需要从零散工作记录中汇总周度进展 ## 操作步骤 1. 读取用户提供的日志或历史记录 2. 按模板结构提取本周完成、风险阻塞、下周计划 3. 调用 scripts/summarize.py 清洗重复项 4. 按 references/weekly_report_template.md 输出 ## 注意事项 - 不要编造用户没有提供的工作内容 - 若信息不足明确列出缺失项并询问这里最容易被忽略但最要命的是description字段。你描述得越具体Agent在“该用哪个技能包”的时候判断就越准。比如“生成周报”这种描述会让Agent在多技能场景里犹豫而写了“适合项目周会前的汇报整理”之后命中率会明显提升。我实测下来description是影响技能调用频率的第一因素。2.3 脚本和参考资料是怎么协同的一个纯Markdown的Skill确实能工作但上限有限。真正好用的Skill一定会把“AI擅长的”和“程序擅长的”结合起来。举个例子。写周报这个场景AI擅长什么擅长理解零散记录、归纳重点、润色表达。AI不擅长什么不擅长精确统计工时、不擅长去重合并、更不擅长生成固定的可视化图表。所以一个设计良好的周报技能会把“统计工时”交给Python脚本把“归纳总结”留给Agent自己# scripts/summarize.py # 输入原始工作记录JSON Lines格式 # 输出按项目分组的时长统计汇总 import json import sys def main(): records [json.loads(line) for line in sys.stdin if line.strip()] projects {} for r in records: key r.get(project, 未分类) projects.setdefault(key, 0) projects[key] r.get(hours, 0) for name, total in sorted(projects.items(), keylambda x: -x[1]): print(f{name}: {total}h) if __name__ __main__: main()这里有一个关键机制Agent会自己决定何时执行脚本。它读懂了SKILL.md里的步骤说明后如果发现信息完备就会主动调用脚本再把脚本输出和它的语言理解能力融合。你不用在SKILL.md里写“在终端运行python summarize.py”这种具体指令——只要说清楚“按项目汇总工时”的目标Agent会自己找到合适工具。2.4 Agent是怎么决定使用哪个Skill的这部分我花了不少时间实测总算总结出一个规律。Agent在每次对话开始时会扫描所有已安装技能的SKILL.md元信息构建一个“技能索引”当用户消息进来后它先做一轮“意图匹配”把用户需求映射到最相关的技能上匹配成功后再把对应SKILL.md的完整内容加载进上下文。整个过程有两处性能关键点一是技能数量越多匹配噪音越大。装三十个描述同为“生成报告”的技能不只会变慢还可能选错。我个人的建议是生产环境里一套对话场景挂载的精简技能数量控制在5个以内仓库里可以存几十个但不要全量激活。二是description质量直接决定命中率。这一点前面提过这里说个实测数据我把某个技能的description从“数据清洗工具”改成“处理CSV/Excel中的重复行、缺失值填充、格式统一的批量清洗工具”调用命中率从不到四成提升到了八成以上。同样的技能代码只改描述就能有这么大差距这正是“技能说明即交互界面”的体现。3. 手把手开发自己的第一个Skill以“工作日志整理器”为例3.1 选题什么任务适合做成Skill不是所有任务都值得封装。我建议你用三条标准筛任务高频、稳定、有流程。高频意味着投入产出比高稳定意味着这个任务的执行方式长期不变有流程意味着你能把成功经验固化成步骤。反过来那种天马行空的创意任务或者一次性任务做成Skill反而是负担。我这边用一个很典型的需求演示把团队每天散落在各个群里的工作记录整理成规范化的日志文档。这个任务够高频、方法稳定、而且有明确的流程收集、去重、分类、格式化。3.2 设计SKILL.md的四个关键段落这个技能你要实现的功能是用户粘贴一段凌乱的工作记录文本或者上传一个日志文件技能自动清洗、按“项目/任务/耗时”分类并输出统一格式的md文件。--- name: work-log-organizer description: 将零散的工作记录整理为结构化工作日志。适用于粘贴文本、TXT、MD等格式的日志清洗与归类输出包含时间、项目、任务描述、耗时的标准文档。 --- # 工作日志整理器 ## 何时使用 - 用户提供一段或多段混乱工作记录 - 需要从流水账文本中提取结构化字段 - 需要将日志按项目归类并统一格式 ## 执行流程 1. 读取输入内容粘贴文本或指定的本地文件 2. 提取单条记录的四个字段时间、项目、任务、耗时 3. 调用 scripts/parse_log.py 进行时间序列排序和耗时汇总 4. 用 references/log_template.md 中的格式生成文档 5. 将最终结果保存为工作日志_日期.md ## 输入格式要求 - 时间优先识别 YYYY-MM-DD 或 HH:mm - 耗时支持 1.5h 30m 2小时 等写法 - 项目名以用户自定义项目列表为基准 ## 输出规范 - 每条记录一行时间排序 - 每个项目单独小节附总耗时 - 结尾列出“今日累计耗时”和“未识别记录”四个关键段位我总结为场景触发说明何时用、步骤大纲怎么做、输入约束读取什么、输出规范产出什么。写好这四块一个零基础Agent也能轻松胜任。3.3 给Skill配上辅助脚本和模板上面SKILL.md里提到了两个辅助资源parse_log.py和log_template.md。下面逐一实现。# scripts/parse_log.py # 用途解析流水日志按时间排序按项目汇总耗时 import re import sys from collections import defaultdict LOG_PATTERN re.compile( r(?Ptime\d{4}-\d{2}-\d{2}[\sT]\d{1,2}:\d{2})?\s* r\[(?Pproject[^\]])\]\s* r(?Ptask.?)\s* r(?Pduration\d(\.\d)?(h|m|分钟|小时))?\s*$ ) def to_minutes(dur, unit): if unit in (h, 小时): return float(dur) * 60 return float(dur) def main(): raw_lines sys.stdin.read().strip().splitlines() records [] for line in raw_lines: m LOG_PATTERN.match(line.strip()) if not m: continue dur m.group(duration) minutes 0.0 if dur: num float(re.search(r\d(\.\d)?, dur).group()) unit re.search(r(h|小时|m|分钟), dur).group() minutes to_minutes(num, unit) records.append({ time: m.group(time) or 未知时间, project: m.group(project), task: m.group(task), minutes: minutes, }) records.sort(keylambda x: x[time] if x[time] ! 未知时间 else 9999) summary defaultdict(float) for r in records: summary[r[project]] r[minutes] for r in records: print(f- {r[time]} | {r[project]} | {r[task]} | {r[minutes]:.0f}min) print(\n## 项目耗时汇总) for p, mins in sorted(summary.items(), keylambda x: -x[1]): print(f- {p}: {mins:.0f}min ({mins/60:.1f}h)) if __name__ __main__: main()资源模板references/log_template.md则是给最终输出用的格式参考# 工作日志{date} ## {项目名称} - [{时间}] {任务描述}{耗时} - [{时间}] {任务描述}{耗时} ## 汇总 - 总记录数{n} - 总耗时{total} - 未识别记录{list}这里的配合逻辑是脚本负责精确计算模板负责规范呈现Agent负责两边的衔接和补全。缺了哪一样技能都不完整。3.4 安装与激活验证Skill被正确加载写完目录结构后你需要确认Agent真的能发现并应用它。不同框架的安装位置有差异但基本套路一致把整个文件夹放入Agent配置指定的skills目录。检查目录名和SKILL.md中的name字段是否一致。启动新的对话或重置会话让Agent重新扫描技能索引。输入一条典型任务描述比如“帮我整理这段日志2025-03-10 [官网改版] 完成首页设计稿 2h”。观察Agent是否立刻进入“工作日志整理器”的执行流程。如果Agent对你的输入没有反应八成是description写得不够清楚或者会话尚未重新加载。这里有一个屡试不爽的调试技巧直接向Agent发问“你有哪些可用的skills”或“当前会话已加载了哪些技能”让它自己把索引列出来。这一步能省掉大量反复测试的时间。4. 测试与调试实录让Skill稳定好用的必备流程4.1 用固定用例做回归验证Skill是给别人用的稳定性是第一位的。我的习惯是每写一个Skill配套准备5组以上固定测试用例覆盖正常输入、边界情况和异常输入。以工作日志整理器为例我常用的测试集长这样用例类型输入样例预期行为正常完整“2025-03-10 09:30 [前端] 修复登录页按钮样式 1h”正确解析时间、项目、时长无耗时“2025-03-10 [后端] 联调API”记录保留耗时为空不报错多条混合多条不同项目、时间乱序的记录自动排序并按项目分组汇总带中文单位“[设计] 完成三屏视觉稿 2小时”耗时换算为120分钟无效输入“今天肚子疼请假”输出未识别记录不强行解析测试不要全指望Agent自己做。你需要人工核对每条用例的输出是否符合预期尤其是脚本部分。一个隐蔽的bug比如正则没匹配“半小时”Agent在真实对话里是很难发现的它可能会直接绕过脚本用“发挥”来填补。我的排查顺序是这样的先确认SKILL.md能被加载再确认脚本本身在终端能跑通最后才做端到端对话测试。三个环节层层排查效率最高。4.2 常见运行故障与排查思路下面整理一份故障速查表全部来自我实际踩过的坑症状可能原因解决思路Agent完全不调用Skilldescription不准确或没有命中意图重写description加入具体任务动词和关键词调用后行为不符合说明SKILL.md步骤写得含糊把每个步骤写成可验证的动作别写“适当处理”脚本报错但Agent没发现脚本运行失败后Agent仍继续编造结果在步骤中明确要求“执行脚本后核对输出异常则停止”同一类型的多个技能互相抢活description语义重叠合并技能或为每个技能增加专属适用边界加载后对话变慢/超长SKILL.md太长或references被全量加载精简正文把细节移入references按需读取4.3 实测心得决定Skill上限的三个细节第一“大白话”不等于“模糊”。我发现很多人写SKILL.md时喜欢写“根据情况灵活处理”这会让Agent选择困难。正确的做法是给出决策规则比如“如果耗时缺失标记为待确认不要猜测”。Agent需要的不是自由度而是明确的判断依据。第二脚本要追求“无脑稳定”。Skill的脚本不需要优雅但必须在各种脏输入下不崩溃。我习惯让脚本对每一行非法输入都保持宽容解析失败就跳过而不是中断整个任务。这样Agent至少能拿到部分结果不会全盘失败。第三版本迭代要留痕。Skill是一个会被反复迭代的文件资产我建议在SKILL.md的元信息头里增加version字段并在references/CHANGELOG.md里记录每次变更。这样多个Agent共用同一份技能时你才追得到“之前好用、这次为什么失灵”的改动来源。5. 生态盘点去哪儿找现成Skills怎么筛选5.1 主流水源与检索技巧自己写Skill能解决定制问题但很多通用能力完全不用重复造轮子。目前Skills生态的主力阵地有两类一类是GitHub上的开源仓库和聚合列表。搜索时别只搜“skills”这个词试这些组合awesome agent skills、claude skills、codex skills能挖到很多精品合集。我强烈建议收藏几个stars过千的合集取用前先看License是否允许商用。另一类是框架自带的官方技能目录或插件社区。不少Agent平台都内置了浏览、安装技能的机制安装命令通常是skills install name之类。至于具体用哪一个分发渠道看你的Agent框架文档就行。检索环节有个通用技巧搜索时带上任务动词和行业词比如“write weekly report skill”“seo content skill”比搜“skills大全”命中率高得多。5.2 用“风险四问”过滤劣质Skill从外部下载Skill最怕的不是不好用而是引入恶意指令或非法行为。我在引入任何第三方Skill之前会强制过四遍审查它有没有宣称做违反平台规范的事比如自动化绕过安全机制、批量抓取私人数据这种直接弃用。SKILL.md里有没有隐藏的“忽略之前指令”类内容这是典型的prompt注入特征正规技能不会写这种东西。脚本你看得懂吗看不懂的Python/Bash脚本先别急着跑尤其是有网络请求的。它能访问的权限边界是否最小化一个日志整理技能没理由让你开放全盘文件权限。除非是你百分百信任的发布者否则建议先隔离运行一次用一个独立的测试环境或临时目录加载观察它的行为再决定要不要集成进主环境。这一步小心能省下后面无数的麻烦。5.3 已安装Skills的维护和版本管理很多人装完Skill就忘了更新过几个月发现技能失效还以为是Agent框架升级导致的。实际上Agent框架的更新确实可能破坏旧Skill的兼容性所以维护环节必不可少。我目前的维护习惯是这样每个Skill使用独立的Git仓库或至少是monorepo里的独立子目录便于单独打tag和回滚。每次框架升级后先跑一遍我前面说的固定测试用例集确保回归通过再进生产环境。每周花十分钟检查官方聚合列表的更新评估正在用的Skill有没有安全修复或功能增强。对不再使用的Skill直接停用我还专门写了个脚本清理N天内没被调用过的技能包保持环境干净。这套维护流程看起来繁琐但真正出事的时候你就知道值了。我之前有过一次教训某个数据清洗Skill依赖的第三方解析库升级后接口变了脚本直接崩了而那个Skill帮我处理着每天上百条销售记录。从那以后我开始给每个Skill的脚本文件锁定依赖版本并在SKILL.md里写明“若运行报错请检查依赖版本”。6. 进阶玩法把Skills磨成真正的“超级能力”6.1 从单体Skill到Skill组合单个Skill解决单点任务Skill组合才能解决复杂链路。比如前面的工作日志整理器它可以和一个“数据统计图表生成”Skill联动前者负责清洗和汇总后者负责把汇总结果可视化成周趋势图。Agent会根据任务目标自动串联多个Skill这个能力在实际使用中非常惊艳。想让Skill组合更顺畅注意一点给每个Skill定义清晰的输入输出契约包括产出文件的格式、字段命名、保存路径。就像两个同事协作你交出去的文档必须符合对方的输入要求。6.2 参数化、记忆与反馈闭环更高阶的用法是让Skill支持参数化配置。例如工作日志整理器可以接受一个“项目列表”参数不同团队传不同参数同一份技能适配多场景。实现方式很简单把可变配置抽到SKILL.md元信息头的自定义字段里或者在references下放一个config.json让脚本读取。至于反馈闭环我建议在SKILL.md中增加“常见问题修正”小节专门记录过去踩过的坑。每次发现Agent执行偏差就在这个小节里补一条纠正指令。日积月累这个Skill会变得越来越聪明因为它把“实践经验”也写进了技能本身——这就是把普通技能磨成个人超级能力的过程。6.3 最后分享一个我踩过的坑聊点实在的。我要说一个我之前栽过跟头的场景希望大家引以为戒千万不要把公司的敏感业务数据封装进通用Skill里传播。我一度打算把某个内部项目的分析流程做成一整套Skill分享给同行好在发布前检查了一下references里的模板文件——里面嵌着真实客户的项目代号和内部人员的缩写习惯。Skill这种格式天然会把参考资料一并打包你在本地用感觉没什么一旦分发出去这些“隐藏信息”也就跟着出去了。所以在分享任何Skill之前我会专门跑一遍全目录扫描检查references和assets里有没有硬编码的敏感信息。我会把模板里的公司名、路径名、内部缩写全部替换成占位符再把示例数据换成虚构场景。这个习惯我现在已经当成发布Skill的固定流程。另外还有一个小技巧分享发布Skill时在SKILL.md末尾加一段“Tested By”小节把自己跑过的测试用例清单贴进去。别小看这行字它能极大提升别人对你的信任——至少表明你对自己的技能负责而不是丢一个半成品出去让用户当小白鼠。以我自己这大半年使用和开发Skills的体会来说这项技术真正的价值不在于它叫“skills”这个名字而在于它第一次把“AI该怎么稳定完成一类任务”这件抽象的事变成了可复制、可审计、可迭代的工程资产。哪怕你现在用的是完全不同的Agent框架只要理解了这个思路把所有重复性的工作流程都拆成标准技能包你的AI工具也会比之前好用出好几个数量级。 
长河君 · 2026/10/8 17:22:29 · 阅读 1.2k AI Agent必备技能：从原理到实战，手写你的第一个Skill
几年前我们聊AI说的是“模型有多大、参数有多少”后来大家开始聊“提示词写得巧不巧”再后来话题变成了“Agent能调什么工具”。而最近这段时间不管是Claude生态还是Codex社区都在疯狂追一个叫“skills”的概念。有人把它捧成“AI Agent的超级能力”有人一头雾水地问这不就是另一个插件格式吗如果你也盯着“skills”这个词琢磨过我建议你先别急着下载这个、部署那个。先用第一性原理把一件事搞清楚skills到底解决了什么问题它和插件、工具、MCP这些我们好不容易才分清楚的名词又是什么关系这篇文章我会从原理层面把skills拆开再带你手写一个能复用的技能包最后分享一些我在实际项目中踩过的坑和筛选经验。看完之后你自己就能判断这玩意儿值不值得投入以及怎么用才不浪费。1. Skills是什么从“会聊天”到“会干活”的关键一跃1.1 先看清它到底改变了什么先说结论skills是一套把“提示词、流程、参考资源、可执行脚本”打包成一个文件夹的标准格式Agent用之前会先“阅读理解”这个文件夹的说明文件然后按里面的步骤和脚本去完成一类具体任务。为什么要搞这么个东西因为纯靠对话式的AI有个很致命的毛病每次都是“从零开始”。你让它写周报它每次都得重新理解“周报要包含哪些维度”你让它做数据分析它每次都得重新摸索“数据清理流程”。哪怕你把这些要求写进系统提示词下次换个对话、换个Agent又得重新来一遍。而skills把“怎么完成一类任务”固化成标准化模块——一次编写到处复用。这才是它区别于普通提示词的核心价值。这么说有点抽象打个比方普通提示词像是你口头跟助理交代“帮我把明天会议记一下按老规矩整理”skills则是你交给助理一本《会议纪要标准作业手册》手册里连模板、检查清单、常用工具都备好了。助理翻开手册就能干活而且每次干出来的水平都稳定。所以你现在看很多Agent框架都在往“skills”上靠根本原因不是赶时髦而是它们都意识到真正让Agent变得可用的不是模型多聪明而是它能不能稳定复用人类沉淀下来的操作流程。1.2 Skills、Tools、MCP别再傻傻分不清很多人一看到skills有脚本、有工具调用就觉得它和MCP是一回事。实话讲我第一次看到官方文档时也有点恍惚。但把三者放在一张表里对比区别立刻就清楚了。维度Prompt提示词Skill技能包Tool / MCP工具/外部服务本质对话时的指令文本结构化的知识流程脚本外部能力接口生命周期随对话消失静态文件可长期复用常驻服务按需调用是否需要运行环境不需要可能需要脚本环境通常需要独立服务网络依赖无无使用时注入上下文有实时请求外部API适用场景临时性指导反复执行的固定流程实时数据获取、外部动作举例“帮我写得专业一点”“写周报的标准流程”“查天气”“发邮件”关键区别就两条第一Skill本身不一定调用外部服务。它把“如何做事”的说明和参考资料打包好Agent在需要时把它作为上下文读进来。而MCP是实时连接外部系统的桥梁强调的是“操作能力”。第二Skill是可组合、可版本管理的静态资产。你可以把它提交进Git仓库同事clone下来就能用而MCP服务通常要跑起来才能调。更准确地说skills和工具并不互斥而是互补关系skill负责“知道怎么做”工具负责“实际去执行”。一个成熟的Skill里甚至可以包含“推荐使用哪个MCP工具”的说明。1.3 为什么说它是“第一性原理”式设计“第一性原理”这个词被用滥了但放在skills上还真挺贴切。因为它把“Agent能力”这个模糊概念还原成了几个最基础的构成要素知识说明文档、过程步骤清单、资源数据/模板、执行力脚本/工具。想象一下没有skills的年代你想让AI按公司规范生成合同需要做几步先写详细的步骤提示词再把公司合同模板贴进对话还要祈祷AI别发挥创意乱改条款。每次对话都得来一遍而且换个人用又得重新教。skills则直接规定一份合同生成技能 SKILL.md行为说明 references/templates/合同模板池 scripts/条款校验脚本。Agent识别到任务后自动加载这套组合按说明执行。这不是“让AI更聪明”而是“让AI变规范”。把隐性经验显性化、把临时流程结构化这才是skills最接近第一性原理的地方。它没有增加新能力却让已有能力变得可复制、可传承。2. 核心机制拆解一个Skill内部到底长什么样2.1 最小单元一个目录从文件系统的视角看一个Skill就是一个有固定约定的目录而不是某个单一文件。这个设计很朴素但非常重要——它意味着技能包可以包含任意复杂度的素材。下面是一个常见的布局示例skill-name/ ├── SKILL.md # 技能说明文件核心必须存在 ├── scripts/ # 可执行脚本按需调用 │ └── generate_chart.py ├── references/ # 参考资料、模板、示例 │ ├── weekly_report_template.md │ └── examples/ └── assets/ # 静态资源图片、样式、数据文件目录结构看起来自由但有几个规则是硬性的SKILL.md 必须存在这是Agent识别技能包的“身份证”。没有它整个文件夹只会被当作普通文件目录。文件夹命名要语义化比如weekly-report别叫my_skill_20250101。因为Agent很多时候通过目录名来建立粗认识。超过一定大小限制后要拆references不要把几百页资料全塞进一个说明文件。2.2 SKILL.md是怎么被“读懂”的SKILL.md是整个技能包的核心它的写法直接决定Agent会不会正确使用这个技能。不需要把它当成“程序”而是要当成“写给另一个工程师看的操作手册”。典型的SKILL.md由两部分组成YAML格式的元信息头和Markdown正文。--- name: weekly-report description: 根据本周工作日志生成规范化周报。适合项目周会前的汇报整理可自动提取任务进度、风险与下周计划。 --- # 周报生成技能 ## 什么时候用 - 用户要求生成周报 - 需要从零散工作记录中汇总周度进展 ## 操作步骤 1. 读取用户提供的日志或历史记录 2. 按模板结构提取本周完成、风险阻塞、下周计划 3. 调用 scripts/summarize.py 清洗重复项 4. 按 references/weekly_report_template.md 输出 ## 注意事项 - 不要编造用户没有提供的工作内容 - 若信息不足明确列出缺失项并询问这里最容易被忽略但最要命的是description字段。你描述得越具体Agent在“该用哪个技能包”的时候判断就越准。比如“生成周报”这种描述会让Agent在多技能场景里犹豫而写了“适合项目周会前的汇报整理”之后命中率会明显提升。我实测下来description是影响技能调用频率的第一因素。2.3 脚本和参考资料是怎么协同的一个纯Markdown的Skill确实能工作但上限有限。真正好用的Skill一定会把“AI擅长的”和“程序擅长的”结合起来。举个例子。写周报这个场景AI擅长什么擅长理解零散记录、归纳重点、润色表达。AI不擅长什么不擅长精确统计工时、不擅长去重合并、更不擅长生成固定的可视化图表。所以一个设计良好的周报技能会把“统计工时”交给Python脚本把“归纳总结”留给Agent自己# scripts/summarize.py # 输入原始工作记录JSON Lines格式 # 输出按项目分组的时长统计汇总 import json import sys def main(): records [json.loads(line) for line in sys.stdin if line.strip()] projects {} for r in records: key r.get(project, 未分类) projects.setdefault(key, 0) projects[key] r.get(hours, 0) for name, total in sorted(projects.items(), keylambda x: -x[1]): print(f{name}: {total}h) if __name__ __main__: main()这里有一个关键机制Agent会自己决定何时执行脚本。它读懂了SKILL.md里的步骤说明后如果发现信息完备就会主动调用脚本再把脚本输出和它的语言理解能力融合。你不用在SKILL.md里写“在终端运行python summarize.py”这种具体指令——只要说清楚“按项目汇总工时”的目标Agent会自己找到合适工具。2.4 Agent是怎么决定使用哪个Skill的这部分我花了不少时间实测总算总结出一个规律。Agent在每次对话开始时会扫描所有已安装技能的SKILL.md元信息构建一个“技能索引”当用户消息进来后它先做一轮“意图匹配”把用户需求映射到最相关的技能上匹配成功后再把对应SKILL.md的完整内容加载进上下文。整个过程有两处性能关键点一是技能数量越多匹配噪音越大。装三十个描述同为“生成报告”的技能不只会变慢还可能选错。我个人的建议是生产环境里一套对话场景挂载的精简技能数量控制在5个以内仓库里可以存几十个但不要全量激活。二是description质量直接决定命中率。这一点前面提过这里说个实测数据我把某个技能的description从“数据清洗工具”改成“处理CSV/Excel中的重复行、缺失值填充、格式统一的批量清洗工具”调用命中率从不到四成提升到了八成以上。同样的技能代码只改描述就能有这么大差距这正是“技能说明即交互界面”的体现。3. 手把手开发自己的第一个Skill以“工作日志整理器”为例3.1 选题什么任务适合做成Skill不是所有任务都值得封装。我建议你用三条标准筛任务高频、稳定、有流程。高频意味着投入产出比高稳定意味着这个任务的执行方式长期不变有流程意味着你能把成功经验固化成步骤。反过来那种天马行空的创意任务或者一次性任务做成Skill反而是负担。我这边用一个很典型的需求演示把团队每天散落在各个群里的工作记录整理成规范化的日志文档。这个任务够高频、方法稳定、而且有明确的流程收集、去重、分类、格式化。3.2 设计SKILL.md的四个关键段落这个技能你要实现的功能是用户粘贴一段凌乱的工作记录文本或者上传一个日志文件技能自动清洗、按“项目/任务/耗时”分类并输出统一格式的md文件。--- name: work-log-organizer description: 将零散的工作记录整理为结构化工作日志。适用于粘贴文本、TXT、MD等格式的日志清洗与归类输出包含时间、项目、任务描述、耗时的标准文档。 --- # 工作日志整理器 ## 何时使用 - 用户提供一段或多段混乱工作记录 - 需要从流水账文本中提取结构化字段 - 需要将日志按项目归类并统一格式 ## 执行流程 1. 读取输入内容粘贴文本或指定的本地文件 2. 提取单条记录的四个字段时间、项目、任务、耗时 3. 调用 scripts/parse_log.py 进行时间序列排序和耗时汇总 4. 用 references/log_template.md 中的格式生成文档 5. 将最终结果保存为工作日志_日期.md ## 输入格式要求 - 时间优先识别 YYYY-MM-DD 或 HH:mm - 耗时支持 1.5h 30m 2小时 等写法 - 项目名以用户自定义项目列表为基准 ## 输出规范 - 每条记录一行时间排序 - 每个项目单独小节附总耗时 - 结尾列出“今日累计耗时”和“未识别记录”四个关键段位我总结为场景触发说明何时用、步骤大纲怎么做、输入约束读取什么、输出规范产出什么。写好这四块一个零基础Agent也能轻松胜任。3.3 给Skill配上辅助脚本和模板上面SKILL.md里提到了两个辅助资源parse_log.py和log_template.md。下面逐一实现。# scripts/parse_log.py # 用途解析流水日志按时间排序按项目汇总耗时 import re import sys from collections import defaultdict LOG_PATTERN re.compile( r(?Ptime\d{4}-\d{2}-\d{2}[\sT]\d{1,2}:\d{2})?\s* r\[(?Pproject[^\]])\]\s* r(?Ptask.?)\s* r(?Pduration\d(\.\d)?(h|m|分钟|小时))?\s*$ ) def to_minutes(dur, unit): if unit in (h, 小时): return float(dur) * 60 return float(dur) def main(): raw_lines sys.stdin.read().strip().splitlines() records [] for line in raw_lines: m LOG_PATTERN.match(line.strip()) if not m: continue dur m.group(duration) minutes 0.0 if dur: num float(re.search(r\d(\.\d)?, dur).group()) unit re.search(r(h|小时|m|分钟), dur).group() minutes to_minutes(num, unit) records.append({ time: m.group(time) or 未知时间, project: m.group(project), task: m.group(task), minutes: minutes, }) records.sort(keylambda x: x[time] if x[time] ! 未知时间 else 9999) summary defaultdict(float) for r in records: summary[r[project]] r[minutes] for r in records: print(f- {r[time]} | {r[project]} | {r[task]} | {r[minutes]:.0f}min) print(\n## 项目耗时汇总) for p, mins in sorted(summary.items(), keylambda x: -x[1]): print(f- {p}: {mins:.0f}min ({mins/60:.1f}h)) if __name__ __main__: main()资源模板references/log_template.md则是给最终输出用的格式参考# 工作日志{date} ## {项目名称} - [{时间}] {任务描述}{耗时} - [{时间}] {任务描述}{耗时} ## 汇总 - 总记录数{n} - 总耗时{total} - 未识别记录{list}这里的配合逻辑是脚本负责精确计算模板负责规范呈现Agent负责两边的衔接和补全。缺了哪一样技能都不完整。3.4 安装与激活验证Skill被正确加载写完目录结构后你需要确认Agent真的能发现并应用它。不同框架的安装位置有差异但基本套路一致把整个文件夹放入Agent配置指定的skills目录。检查目录名和SKILL.md中的name字段是否一致。启动新的对话或重置会话让Agent重新扫描技能索引。输入一条典型任务描述比如“帮我整理这段日志2025-03-10 [官网改版] 完成首页设计稿 2h”。观察Agent是否立刻进入“工作日志整理器”的执行流程。如果Agent对你的输入没有反应八成是description写得不够清楚或者会话尚未重新加载。这里有一个屡试不爽的调试技巧直接向Agent发问“你有哪些可用的skills”或“当前会话已加载了哪些技能”让它自己把索引列出来。这一步能省掉大量反复测试的时间。4. 测试与调试实录让Skill稳定好用的必备流程4.1 用固定用例做回归验证Skill是给别人用的稳定性是第一位的。我的习惯是每写一个Skill配套准备5组以上固定测试用例覆盖正常输入、边界情况和异常输入。以工作日志整理器为例我常用的测试集长这样用例类型输入样例预期行为正常完整“2025-03-10 09:30 [前端] 修复登录页按钮样式 1h”正确解析时间、项目、时长无耗时“2025-03-10 [后端] 联调API”记录保留耗时为空不报错多条混合多条不同项目、时间乱序的记录自动排序并按项目分组汇总带中文单位“[设计] 完成三屏视觉稿 2小时”耗时换算为120分钟无效输入“今天肚子疼请假”输出未识别记录不强行解析测试不要全指望Agent自己做。你需要人工核对每条用例的输出是否符合预期尤其是脚本部分。一个隐蔽的bug比如正则没匹配“半小时”Agent在真实对话里是很难发现的它可能会直接绕过脚本用“发挥”来填补。我的排查顺序是这样的先确认SKILL.md能被加载再确认脚本本身在终端能跑通最后才做端到端对话测试。三个环节层层排查效率最高。4.2 常见运行故障与排查思路下面整理一份故障速查表全部来自我实际踩过的坑症状可能原因解决思路Agent完全不调用Skilldescription不准确或没有命中意图重写description加入具体任务动词和关键词调用后行为不符合说明SKILL.md步骤写得含糊把每个步骤写成可验证的动作别写“适当处理”脚本报错但Agent没发现脚本运行失败后Agent仍继续编造结果在步骤中明确要求“执行脚本后核对输出异常则停止”同一类型的多个技能互相抢活description语义重叠合并技能或为每个技能增加专属适用边界加载后对话变慢/超长SKILL.md太长或references被全量加载精简正文把细节移入references按需读取4.3 实测心得决定Skill上限的三个细节第一“大白话”不等于“模糊”。我发现很多人写SKILL.md时喜欢写“根据情况灵活处理”这会让Agent选择困难。正确的做法是给出决策规则比如“如果耗时缺失标记为待确认不要猜测”。Agent需要的不是自由度而是明确的判断依据。第二脚本要追求“无脑稳定”。Skill的脚本不需要优雅但必须在各种脏输入下不崩溃。我习惯让脚本对每一行非法输入都保持宽容解析失败就跳过而不是中断整个任务。这样Agent至少能拿到部分结果不会全盘失败。第三版本迭代要留痕。Skill是一个会被反复迭代的文件资产我建议在SKILL.md的元信息头里增加version字段并在references/CHANGELOG.md里记录每次变更。这样多个Agent共用同一份技能时你才追得到“之前好用、这次为什么失灵”的改动来源。5. 生态盘点去哪儿找现成Skills怎么筛选5.1 主流水源与检索技巧自己写Skill能解决定制问题但很多通用能力完全不用重复造轮子。目前Skills生态的主力阵地有两类一类是GitHub上的开源仓库和聚合列表。搜索时别只搜“skills”这个词试这些组合awesome agent skills、claude skills、codex skills能挖到很多精品合集。我强烈建议收藏几个stars过千的合集取用前先看License是否允许商用。另一类是框架自带的官方技能目录或插件社区。不少Agent平台都内置了浏览、安装技能的机制安装命令通常是skills install name之类。至于具体用哪一个分发渠道看你的Agent框架文档就行。检索环节有个通用技巧搜索时带上任务动词和行业词比如“write weekly report skill”“seo content skill”比搜“skills大全”命中率高得多。5.2 用“风险四问”过滤劣质Skill从外部下载Skill最怕的不是不好用而是引入恶意指令或非法行为。我在引入任何第三方Skill之前会强制过四遍审查它有没有宣称做违反平台规范的事比如自动化绕过安全机制、批量抓取私人数据这种直接弃用。SKILL.md里有没有隐藏的“忽略之前指令”类内容这是典型的prompt注入特征正规技能不会写这种东西。脚本你看得懂吗看不懂的Python/Bash脚本先别急着跑尤其是有网络请求的。它能访问的权限边界是否最小化一个日志整理技能没理由让你开放全盘文件权限。除非是你百分百信任的发布者否则建议先隔离运行一次用一个独立的测试环境或临时目录加载观察它的行为再决定要不要集成进主环境。这一步小心能省下后面无数的麻烦。5.3 已安装Skills的维护和版本管理很多人装完Skill就忘了更新过几个月发现技能失效还以为是Agent框架升级导致的。实际上Agent框架的更新确实可能破坏旧Skill的兼容性所以维护环节必不可少。我目前的维护习惯是这样每个Skill使用独立的Git仓库或至少是monorepo里的独立子目录便于单独打tag和回滚。每次框架升级后先跑一遍我前面说的固定测试用例集确保回归通过再进生产环境。每周花十分钟检查官方聚合列表的更新评估正在用的Skill有没有安全修复或功能增强。对不再使用的Skill直接停用我还专门写了个脚本清理N天内没被调用过的技能包保持环境干净。这套维护流程看起来繁琐但真正出事的时候你就知道值了。我之前有过一次教训某个数据清洗Skill依赖的第三方解析库升级后接口变了脚本直接崩了而那个Skill帮我处理着每天上百条销售记录。从那以后我开始给每个Skill的脚本文件锁定依赖版本并在SKILL.md里写明“若运行报错请检查依赖版本”。6. 进阶玩法把Skills磨成真正的“超级能力”6.1 从单体Skill到Skill组合单个Skill解决单点任务Skill组合才能解决复杂链路。比如前面的工作日志整理器它可以和一个“数据统计图表生成”Skill联动前者负责清洗和汇总后者负责把汇总结果可视化成周趋势图。Agent会根据任务目标自动串联多个Skill这个能力在实际使用中非常惊艳。想让Skill组合更顺畅注意一点给每个Skill定义清晰的输入输出契约包括产出文件的格式、字段命名、保存路径。就像两个同事协作你交出去的文档必须符合对方的输入要求。6.2 参数化、记忆与反馈闭环更高阶的用法是让Skill支持参数化配置。例如工作日志整理器可以接受一个“项目列表”参数不同团队传不同参数同一份技能适配多场景。实现方式很简单把可变配置抽到SKILL.md元信息头的自定义字段里或者在references下放一个config.json让脚本读取。至于反馈闭环我建议在SKILL.md中增加“常见问题修正”小节专门记录过去踩过的坑。每次发现Agent执行偏差就在这个小节里补一条纠正指令。日积月累这个Skill会变得越来越聪明因为它把“实践经验”也写进了技能本身——这就是把普通技能磨成个人超级能力的过程。6.3 最后分享一个我踩过的坑聊点实在的。我要说一个我之前栽过跟头的场景希望大家引以为戒千万不要把公司的敏感业务数据封装进通用Skill里传播。我一度打算把某个内部项目的分析流程做成一整套Skill分享给同行好在发布前检查了一下references里的模板文件——里面嵌着真实客户的项目代号和内部人员的缩写习惯。Skill这种格式天然会把参考资料一并打包你在本地用感觉没什么一旦分发出去这些“隐藏信息”也就跟着出去了。所以在分享任何Skill之前我会专门跑一遍全目录扫描检查references和assets里有没有硬编码的敏感信息。我会把模板里的公司名、路径名、内部缩写全部替换成占位符再把示例数据换成虚构场景。这个习惯我现在已经当成发布Skill的固定流程。另外还有一个小技巧分享发布Skill时在SKILL.md末尾加一段“Tested By”小节把自己跑过的测试用例清单贴进去。别小看这行字它能极大提升别人对你的信任——至少表明你对自己的技能负责而不是丢一个半成品出去让用户当小白鼠。以我自己这大半年使用和开发Skills的体会来说这项技术真正的价值不在于它叫“skills”这个名字而在于它第一次把“AI该怎么稳定完成一类任务”这件抽象的事变成了可复制、可审计、可迭代的工程资产。哪怕你现在用的是完全不同的Agent框架只要理解了这个思路把所有重复性的工作流程都拆成标准技能包你的AI工具也会比之前好用出好几个数量级。