上下班来回打车通勤一小时我经常在地铁上把自己从只会问AI问题的人升级成会给AI交付工作的人。这个转变的关键就是最近AI工具圈里被反复讨论的一个词——skills。skills这个词在不同语境下含义完全不同游戏里是技能树简历上叫技能栈而在AI Agent工具链里它已经变成了一种具体的文件规范。简单说就是把怎么做某件事的完整经验写成一个Markdown技能包让AI在遇到对应场景时直接调用而不是每次都要你从零开始解释。这篇文章要聊的就是围绕skills技能包我踩过的一系列坑和总结出的实操方法它解决什么问题、目录文件怎么组织、描述怎么写才能让AI精准触发、如何从零做一个能用的技能包、以及翻车之后的排查思路。适合那些每天重度使用AI写代码、写文档、做分析的人也适合刚接触Agent技能这个新概念、想一次搞懂原理的读者。1. 先搞明白Skills到底解决什么问题1.1 每次都要从头解释的痛上下文成本的真相我回忆了一下自己用AI的典型场景。写代码时就让它修个bug它可能写出完全不符合项目风格的代码写周报时就让它总结一下这周做了什么它把聊天记录翻个底朝天也总结不到重点上。问题的根源不在于AI笨而在于我每一次对话都在假设它记得我们上次怎么做的。可模型没有记忆。每次新对话就是一张白纸它只知道你此刻输入了什么不知道你偏爱什么格式、什么语气、什么颗粒度。你必须把背景、规则、范例、边界条件全部塞进提示词里而这部分成本极其昂贵——上下文窗口有限提示词越长留给真正任务的空间就越少提示词越长模型在无关信息上跑偏的概率也越高。我把这个情况类比成带实习生。你每次分配任务前都要花十分钟讲一遍团队规矩、代码规范、交付格式实习生才能开始干活。等你讲了三十遍终于忍不了了——你会写一份《实习生干活手册》以后直接丢给他看。Skills就是这个东西。它把我究竟希望这件事怎么做沉淀成一份稳定可复用的操作手册让AI在接到任务的瞬间就知道整套流程不需要你反复输入。1.2 系统提示词不是技能分清人设和操作手册很多人的第一反应是那我直接把需求写进系统提示词不就行了这确实是常规做法但它和Skills有本质区别。系统提示词解决的是你是谁的问题Skills解决的是这件事具体怎么做的问题。你可以让AI扮演一个资深前端工程师这是人设但你没法让人设里塞进几十种具体任务的操作流程——系统提示词会膨胀到不可维护而且每次加需求都得改全局配置牵一发动全身。Skills是独立的、按需加载的能力单元。需要处理周报时调周报技能需要代码审查时调代码审查技能各管各的文件夹互不干扰想改其中一个模块也不会波及全局。还有一个容易忽略的点系统提示词是一次性全部注入的会占用大量上下文Skills是AI在对话中遇到匹配场景时才加载的平时躺在磁盘里需要时才进入上下文。这个按需加载的机制是skills这个词在Agent架构里真正值钱的地方。1.3 什么样的任务才值得做成Skills三个判断标准不是所有任务都值得做成技能包。我自己总结了一套判断标准可以作为评估参考任务特征例子是否值得做成Skills高频重复、流程固定技术周报、代码审查、Markdown格式化非常值得逻辑清晰、结果可预期批量文件重命名、日志分析值得重交互、依赖实时信息头脑风暴、需要联网查询的调研不建议用普通对话更灵活一次性任务、无复用价值临时改写一段文案不建议写了也是负担高度依赖个人审美判断品牌文案定调、视觉设计决策谨慎只能辅助不能替代判断口诀就是三个词高频、稳定、可判断。这三点都满足的任务做成技能包才有杠杆效应。如果你一年只做一次的事花两小时写技能包那就是亏的。要克制万物皆可技能化的冲动技能包的价值是复用不是仪式感。2. 拆开一个Skills包SKILL.md的目录、描述与正文写法2.1 目录与命名规范一个技能一个文件夹先把最基础的文件规范讲清楚。一个Skills技能包本质上就是一个目录目录名就是技能名目录里至少包含一个SKILL.md文件其他辅助资源模板、脚本、参考文档可以平级放在同一个目录下。这个结构在主流AI工具中的实现路径大致是统一约定具体入口位置可能因客户端版本不同有差异但逻辑是一致的——把每个技能隔离到独立目录便于加载、更新和备份。命名上我建议目录名用短横线连接的小写单词比如weekly-report、code-review、markdown-formatter。对外展示的技能名写在文件里的name字段路径名保持文件名友好。一个技能包含多个子流程时可以在同一个SKILL.md里按章节拆也可以拆成多个文件互相引用但一个技能目录只服务一个核心任务域这是高内聚原则。我踩过的一个坑是把多个相关技能塞进同一个目录。比如周报和月报是两个任务我当时图省事放在一起结果AI经常分不清该调用哪部分输出格式来回跳。后来拆成weekly-report和monthly-report两个独立目录各写各的描述和步骤问题立刻消失。宁可目录多一点也别让一个目录承载太多职责。2.2 description是匹配入口像写搜索词一样写描述如果只能记住一条Skills写作经验我会选这条description是AI判断该不该调用这个技能的唯一入口它决定了你的技能包是能被动触发还是永远躺在角落里吃灰。这里要理解一个机制。AI并不是逐字读你的技能文件来决定是否调用而是先读每个技能的description把它和当前对话内容做匹配。匹配机制说白了就是一套模糊检索类似搜索引擎的query匹配不是精确相等是语义相关性。所以description写得好不好直接决定了命中率。我建议在description里写清楚三件事这个技能是做什么的哪些说法会触发它触发词哪些情况它不该插手排除条件。触发词部分尤其重要因为用户不可能用你定义的标准术语来表达需求。比如周报技能的描述里我会写当用户提到周报、本周总结、工作进展、weekly report、这个礼拜干了啥等说法时使用覆盖真实对话里的口语化表达。反例我也见过很多最典型的就是把description写成帮助用户高效生成技术周报。这句话本身没错但它和帮我搞定季度汇报的匹配度几乎为零因为缺少用户视角的触发词。写description时把自己伪装成那个着急的用户脑子里过一遍如果我有一件事要做我会怎么跟AI说再把这些话原样放进描述里。2.3 正文组织把隐性经验拆成显性步骤SKILL.md的正文部分才是技能的真正内核。这里的核心逻辑是将你脑中凭经验直接做的隐性过程翻译成AI能一步步执行的显性流程。我建议按四个区块来组织正文任务目标、执行步骤、输出格式、边界与反例。任务目标先讲清楚做完这件事意味着什么给AI一个全局坐标系执行步骤按顺序拆解每步都写清输入、动作、判断条件输出格式给出模板或结构要求避免AI自由发挥边界与反例明确它不该做什么、什么情况要停下来问用户。拿代码审查技能举例。你脑子里可能想的是看看代码有没有问题但要写成步骤就得拆成先读diff和变更范围再按优先级检查逻辑错误、边界条件、性能隐患、风格问题每个问题标注严重级别附上代码片段和修改建议最后汇总成审查报告按严重程度排序。如果你不拆这么细AI很可能看完代码直接回你一句看起来没什么问题那就等于白搭。写正文最有效的素材来源是你自己过去做过的事。想想你上一次手工完成这个任务时第一步做了什么第二步做了什么中途遇到什么情况你会临时调整策略这些判断条件全都可以写进步骤里。相反如果你自己都没想清楚流程AI更不可能替你脑补出一套合理的流程来。2.4 最小可用模板直接复制就能用我把这种结构固化成一个模板每次新建技能包都从这个框架起步--- name: example-skill description: 做什么事当用户提到触发词A、B、C时使用如果用户只需要D则不要使用本技能。 --- # 技能名称 ## 任务目标 明确这个技能交付的结果是什么。 ## 执行步骤 1. 第一步做X使用输入Y。 2. 第二步根据Z判断走分支A还是分支B。 3. 第三步按模板输出结果。 ## 输出格式 markdown 【固定结构】 字段1 字段2边界与反例如果只有原始素材但没有明确目标先询问用户要什么。不要输出空泛的结论必须给出可执行的具体结果。注意正文里如果用了代码块建议用四个反引号包裹避免和文件本身的三反引号格式冲突。这个模板看起来很简单但足够支撑大多数任务场景。真正拉开差距的是模板里每个区块填充的内容质量。 ## 3. 实战从零做一个技术周报技能包 ### 3.1 先画工作流再写文件 理论知识讲完了下面用我自己常用的技术周报技能做一次完整实操。这个过程的核心原则是先想清楚工作流再动手写文件。 我平时的周报习惯是周一翻一遍上周的git提交记录、看合并的PR和关闭的Issue、扫一眼和同事的聊天记录里有什么进展然后提炼成几个模块——本周完成、关键数据、风险与阻塞、下周计划。这几件事听起来简单但每件事都有判断细节什么提交算值得写进周报什么只是修了个拼写错误什么数据能证明进展什么指标说了等于没说。 把这个流程画成工作流的话大概是收集信息源与用户确认范围按类型整理原始材料筛选掉低价值条目按模板生成结构化周报标记需要用户确认的疑点输出最终版本。每个环节的输入输出我都写清楚再落成SKILL.md就水到渠成。 ### 3.2 第一版技能包完整文件与逐段拆解 下面是我实际使用的weekly-report技能的SKILL.md保留了这个结构你可以直接参考 markdown --- name: weekly-report description: 生成技术周报。当用户提到周报本周总结工作进展weekly report这个礼拜干了啥等说法时使用。如果用户需要日报或季度总结不使用本技能。 --- # 技术周报生成器 ## 任务目标 把零散的日常工作信息整理成一份结构化、可对外同步的技术周报重点是让没参与本周工作的人也能看懂进展。 ## 执行步骤 1. 询问用户有哪些素材来源默认包括git提交记录、PR列表、Issue列表、会议纪要或聊天记录。如果用户只提供了部分素材明确以用户提供的为准。 2. 收集并整理原始材料请用户贴出文本信息或告知仓库路径。逐条阅读剔除纯机械修改拼写修正、格式调整和无实质进展的记录。 3. 按主题对剩余条目分组组名建议使用业务模块名称如用户中心重构数据看板优化不要使用git分支名作为组名。 4. 为每个分组提炼关键进展补充该改动的业务价值例如修复了订单超时问题要写成订单超时率从2.1%降到0.6%双十一大促路径稳定性提升。 5. 识别风险与阻塞标记没有结论的讨论、被卡住的依赖、需要外部配合的事项单独输出到风险与阻塞模块。 6. 按下方输出格式生成周报初稿标出所有需要用户确认的数字和结论请用户核实后发布。 ## 输出格式 ### 本周完成 - [模块名] 一句话核心进展附数据或链接 ### 关键数据 - 指标名本周值对比上周值注明口径 ### 风险与阻塞 - 事项描述涉及方、卡点、需要的支持 ### 下周计划 - 按优先级排列每项明确预期结果 ## 边界与反例 - 不要为了凑字数罗列所有提交记录只保留有业务价值的条目。 - 不要擅自编造数据所有数字必须有来源无法确认的标记为待确认。 - 不要输出修复了若干bug这类空泛描述每项都要有具体对象和影响。逐段拆解一下我为什么这么写。description里我把日报季度总结写成排除条件是为了防止AI在用户聊别的时间粒度时误触发周报技能。执行步骤里我特意强调不要用git分支名作为组名因为这是我最开始使用时真实遇到的问题——AI把feature/user-center-refactor原样搬进周报读者根本看不懂。第5步单独拎出风险和阻塞是因为这部分在非技术读者视角里最容易丢但是对团队协作又最关键。输出格式里的每个模块都有明确的物理意义不给AI自由发挥的空间。3.3 接入与首次触发把技能真正用起来文件写好之后剩下的就是把它放进正确的目录。按主流工具的约定将weekly-report这个目录放进本机的skills根目录即可然后重启对话让配置生效。首次触发时我故意没有在对话里提到技能两个字只发了一句帮我写一下这周的技术周报git log在~/projects/order-service这周主要做了订单超时优化和看板接口开发。AI很快就匹配到了weekly-report这个技能然后按照文件里的步骤反过来向我确认收到素材来源我理解为git提交记录请问PR列表需要一并提供吗看到这句话我就知道技能触发成功了。整个过程里我特别留意了AI的输出是否符合我预设的格式。结果它生成的初稿基本结构是对的但数据表述明显偏简化比如把优化了超时逻辑直接当成一条完成项没有按技能文件里的要求补充业务价值。这正是第一版技能需要迭代的信号。3.4 第一版的翻车点与第二版迭代第一版用下来我暴露了两个问题。第一个问题是步骤描述太依赖默认。我在第1步写了默认包括git提交记录、PR列表、Issue列表但实际使用时用户不一定能一次性给全这些素材AI有时会基于默认假设直接开始编内容而不是先向用户确认。修复方法是把步骤改成强约束任何非用户明确提供的素材都视为不存在不能自行脑补。第二个问题是输出偏事件清单缺乏进展对比。周报的价值不只是罗列做了什么更在于说明相比上周有什么变化。我在第二版新增了关键数据模块并且要求AI在每个数字旁边标注对比值。这个改动让周报从文字流水账变成了可追踪的进度报告。版本迭代的一个小技巧每次修改SKILL.md后在文件末尾加一段更新记录写下这版改了什么、为什么改。这样下次自己回看时能快速定位每个设计决策的前因后果比维护一个单独的文档省事得多。4. 实战中容易翻车的5个问题与排查速查表4.1 技能不触发描述宽了还是窄了最常遇到的翻车现场是你已经把技能包写好了但对话里怎么提需求AI都没有调用它。这时第一反应应该是检查description而不是怀疑AI的能力。太宽泛或太窄都会导致匹配失败。太宽的描述比如处理各种文字工作AI无法判断你的技能和当前任务的确切关系太窄的描述比如当用户输入生成基于git的周报时使用没有用户会这么说话。正确做法是覆盖用户真实说法加入本周总结这周干了啥帮我把这周的事情整理一下这类口语化触发词。还有一个隐蔽问题技能描述里用了技术黑话但用户习惯用业务语言。比如你写帮助用户生成Sprint复盘报告但用户只会说这轮迭代做完了帮我总结下。要让触发词贴近用户而不是贴近你的代码习惯。4.2 跑到一半跑题让步骤长出分支技能被触发了但执行到一半输出风格突然跑偏或者跳过关键步骤直接给结论。这种情况通常意味着你的步骤列表不够细或者缺少条件分支。AI本质上是一个填词模型它倾向于顺着最自然的路径输出。如果你的步骤只写了整理材料→生成报告它很可能直接跳到你没想到的中间环节。解决办法是在步骤里增加分支判断如果出现了情况A执行X如果出现了情况B执行Y。分支写在步骤里AI才会在关键时刻停下思考。我见过一个极端的例子有个技能包只写了两行步骤结果AI每次输出都不一样毫无稳定性可言。把怎么判断什么情况下换策略这类隐性决策写进步骤才是让技能输出可控的关键。4.3 技能互相打架命名与作用域隔离技能多了以后会出现描述重叠问题。比如我有个weekly-report技能后来又写了个project-summary技能两者都需要处理项目进展信息。结果用户说帮我总结项目进度时两个技能都匹配上了AI可能同时加载两个技能上下文互相干扰输出的格式混乱。我做了一次全面的技能目录梳理定了两条规矩第一所有技能description的触发词互不包含A技能说周报B技能就不提周报只提项目总结第二每个技能只负责一个核心任务域。这套规则执行后技能打架的情况几乎消失。4.4 上下文被塞爆把全量加载改成按需询问有些技能设计时喜欢引用大量外部文件比如模板、历史报告、参考文档全部写进技能目录里。这个思路本身没问题但如果AI每次触发技能都把这些文件全部读进上下文上下文窗口很快就被占满留给真正任务的空间急剧缩小。我的做法是按需询问式加载。技能正文里不直接把模板内容写死而是写先询问用户是否需要参考历史周报格式如果需要再读取模板文件。这样技能包本身只是轻量的操作指南真正重的数据只在用户确认后才进入上下文。实测下来这种设计大幅减少了误读和上下文膨胀的问题响应速度也提升明显。4.5 改烂了改不会去用Git管理你的技能库技能的迭代是反复的改到第三版时你可能发现第二版某个写法更好但你已经不记得原文了。我自己早期吃过这个亏后来把整个skills目录纳入Git管理每次改动提交一个commitcommit message写上改动原因。回滚、对比、查看历史都变成一行命令的事。如果你的技能库是团队共享的Git还能解决协作问题——大家各自提PR评审后再合并技能库的质量会比单机自嗨高一个量级。这也是我后面要聊的团队化方向。下面把以上问题整理成一张速查表方便直接对照排查问题表现排查方向解决方法技能不触发对话里提到需求但没反应检查description补触发词、加排除条件执行跑偏输出风格突变、跳过步骤检查步骤粒度拆细步骤、加条件分支技能冲突多个技能同时加载检查描述重叠触发词去重、目录隔离上下文爆满响应变慢、输出冗长检查资源加载策略改成按需询问式加载版本混乱改坏后找不回旧版检查版本管理纳入Git、写commit message5. 意外收获Skills不只是给AI的更是给自己的使用说明书5.1 把我知道怎么做写成别人也能照着做在整理技能包的过程中我发现最大的收益方其实是我自己。每次把一个流程写成SKILL.md都是一次对自己工作方式的复盘——原来我写周报时真正在看的是那几类信息原来我做代码审查时先看diff再看逻辑是有原因的原来在很多任务上我凭直觉的判断背后都有一套可拆解的规则。这套梳理工作的价值在于它把我知道怎么做变成了别人也能照着做。当AI能按你的技能包稳定完成任务时说明你对这件事的理解已经足够结构化。技能文件本质上就是你工作方法的说明书有了说明书你才能把重复性工作放心地交出去把省下来的精力放在真正需要判断力和创造力的地方。5.2 从个人技能库到团队共享如果技能包只躺在自己电脑里它的价值仍然有限。我后来把团队里常用的几个技能包放进了共享仓库周报、代码审查规范、故障复盘模板。新同事入职不用再听我口述流程直接把技能目录clone下来AI就能按团队标准辅助工作。团队共享需要注意一点每个人的工作习惯不同技能包格式的统一和评审机制比内容本身更重要。我建议团队技能库建立简易的更新流程任何改动都要说明原因避免技能库变成无人维护的垃圾堆。5.3 什么时候不该用技能边界感过度依赖技能化也有副作用。依赖AI自动处理已经结构化的流程你的判断力会逐渐失去锻炼机会依赖技能库去应对创意类任务输出会变得模板化、套路化。我把技能化的边界立在了需要审美判断和情感共鸣的任务上——这类工作依靠AI技能包辅助可以完全交给它不行。写技能包的过程让我意识到一个很根本的问题你对一件事的理解决定了你能写出什么样的技能包而技能包的质量反过来又会限制AI帮你完成任务的边界。这套方法论不是单向的训练AI更像是一场双向训练——我在教AI的同时也在逼自己把模糊的经验讲清楚。我个人实操中最大的体会是写Skills最难的地方不是语法、不是目录结构而是发现自己原来根本没想清楚自己是怎么把一件事做好的。任何一种工作能被写清楚才能被教给AI能被教给AI才算真正形成了可迁移的方法论。如果你也想试试建议从自己最常做、最熟练的一个小任务开始把它写成第一个技能包那个过程里学到的东西会比任何教程都管用。