1. Skills这阵风到底在吹什么先看懂它解决的真实问题最近技术社区里被skills刷屏的频率越来越高。Claude有Agent SkillsCodex也在力推Skills机制各家AI编程工具都在把这个词当成核心卖点。但说实话大部分讨论都停在什么是Skills的科普层面很少有人把它背后的运行逻辑、怎么开发、怎么排查问题讲透。我在实际用了一段时间之后最大的感受是Skills本质上解决的是一个很朴素的痛点——AI Agent每次都像失忆一样换个项目、换个对话就得重新教一遍它怎么做某件事。今天你花半小时写提示词告诉它评审代码的时候要按什么流程走、重点看哪几类问题、输出格式长什么样明天开启一段新对话它又全忘了。Skills就是把这些教一遍的东西固化成工作区里的可复用资产让它变成Agent的肌肉记忆。这篇文章我只聊三件事Skills的原理骨架是什么怎么从零写一个真正能落地的Skill以及装完、写完、跑起来之后那些文档里不会写的坑。全部基于我自己的实操经验代码和配置都贴出来你可以直接照着做。先说清楚适用人群正在用Claude Code、Codex一类的对话式编程工具觉得每次都要重复描述工作流很烦的人或者团队里想沉淀一套统一开发规范、让AI按标准干活的人。如果你只是偶尔用AI写个函数那Skills的复杂度暂时对你没必要。2. 拆开看本质Skills不是插件是给Agent的操作手册加工具箱2.1 最常见的误解很多人一看Skills能装、能卸、能下载下意识就把它当成插件Plugin。这是最要命的误解。插件的核心是代码执行能力——装了就多一个能调用的函数Agent直接调用它去干某件事。而Skills的核心是指令与流程的封装——它是一组当遇到某类场景时按这些步骤、这些规范来工作的说明外加可选的一些辅助代码。打个比方插件是给你请了个水电工他自带工具你说换个灯他直接上手。Skills是给一个聪明但没经验的实习生一份岗位操作手册——手册里写了遇到客户投诉要先安抚情绪、再记录问题、再升级处理也许还附带了一张标准表格模板但最终动手干活的还是实习生本人。2.2 一套Skill的标准骨架收到任何一份Skill先别急着装拆开来看看它是什么结构。虽然Claude、Codex、Cursor每家定义略有差别但主流实现基本趋同一个SKILL.md文件用自然语言写清楚这名实习生在什么情况下出手、按什么步骤干活、输出物长什么样。这就是操作手册。一个代码目录放着脚本或程序负责执行这个流程中人用自然语言说不清楚的部分——比如解析日志、转换格式、调接口。这是工具箱。一个可选的元数据块通常以YAML格式写在SKILL.md开头声明名字、描述、触发场景、版本号。三者之间的关系我习惯用一句话概括SKILL.md决定了Agent想不想、会不会、怎么干代码目录决定了Agent干得动干不动。2.3 触发机制描述匹配与上下文注入Skill的触发不是靠人手动去点启用按钮而是靠Agent在对话中实时判断当前用户请求是否匹配某个Skill的描述。比如你写了一个code-review技能描述里写清楚了当用户要求审查代码变更、评审Pull Request、检查代码质量时使用Agent扫描到这段话和你当前的需求对上了就会把SKILL.md内容注入到上下文里然后按里面的步骤执行。这个机制有一个关键设计渐进式披露。SKILL.md的表面描述通常很短只有几十个字目的是让Agent快速匹配不浪费上下文窗口。真正的详细步骤藏在SKILL.md的正文里等Agent确认触发后才会被完整读取。这个设计直接借鉴了官方文档的先给摘要、再展开细节的思路对控制Token成本很重要。2.4 权限边界Skill不能越权Skill本身只是一堆文本和脚本它不能脱离Agent单独运行。它不能自己决定我要访问网络我要删掉这个目录我要执行shell命令——所有实际操作权限仍然受Agent自身安全策略的约束。这意味着一个很实际的问题Skill写得好不好一半看步骤清楚不清楚另一半看它有没有把边界说清楚。比如我写过的一个日志分析Skill专门在文档里强调只读取当前工作目录下的文件不递归扫描上级目录只输出统计结果不修改原文件。你不写清楚边界Agent可能自由发挥去做一些你不希望它做的事。3. 从零手写一个能落地的Skill以技术评审纪要生成器为例3.1 为什么选这个场景空谈概念没有意义我直接用一个我自己每天都在用、并且已经跑通了的Skill来讲——从会议记录自动生成技术评审纪要。痛点背景我们团队每周两次技术评审会会议记录是一个几百行的零散文字稿里面有背景说明、方案讨论、有人提出风险、有人拍板了技术选型、还有一堆待办事项。之前每次开完会都有人花一两个小时把这些乱七八糟的对话整理成结构化的纪要发到群里。有了Skills之后这个活儿基本可以归Agent干了。3.2 目录结构与核心代码我先创建目录并初始化结构mkdir -p tech-review-skill cd tech-review-skill mkdir scripts整个Skill就两个核心文件SKILL.md操作手册定义了Agent的行为逻辑。内容如下--- name: tech-review-minutes description: - 根据用户提供的技术评审会议原始记录生成结构化评审纪要。 当用户提到生成评审纪要整理会议记录技术评审输出时使用。 适用于包含方案讨论、技术选型、风险评估的会议场景。 ---正文部分继续写详细的执行规范注意这里才是最关键的# 技术评审纪要生成器 ## 职责边界 - 只处理与技术评审相关的会议记录不处理日常站会、周报等内容。 - 只读取用户提供的文本或指定文件不主动扫描工作区其他文件。 - 输出Markdown格式的纪要文件不直接修改用户的原记录。 ## 执行步骤 ### 1. 识别与分段 先通读全文识别出记录中归属的讨论主题。每个主题可能是 一个技术方案、一个架构选型、或一个代码审查议题。遇到 明显的无关闲谈内容比如开场寒暄、订餐讨论直接丢弃。 ### 2. 信息抽取 对每个主题按以下维度抽取信息 - 背景为什么会有这个讨论它要解决什么问题 - 方案提出了哪些候选方案各自的核心思路是什么 - 决策最终拍板了哪个方案或者明确暂缓/否决了什么 - 风险讨论中提到哪些技术风险、依赖风险或进度风险 - 待办事项明确指派给谁的任务格式为 [负责人] 任务描述。 抽取时要保留记录中的具体技术术语不要自行翻译或改写。 ### 3. 输出结构化纪要 按要求输出Markdown纪要章节顺序固定 1. 评审概览主题列表一句话概括每个主题 2. 逐项评审详情按上述维度展开 3. 风险清单按严重程度从高到低排序 4. 待办事项按负责人分组 ### 4. 校验与自查 生成完毕后检查是否满足 - 所有明确出现过的决策信息都被记录 - 待办事项都有负责人 - 每项风险都注明了涉及的主题 若发现决策缺失在纪要末尾的待确认项中列出防止漏项。scripts/extract_actions.py工具箱里的螺丝刀负责干Agent做得不好但脚本做得很好的事——从全文里把待办事项精确提取出来用正则匹配XXX负责YYY这类长尾句式#!/usr/bin/env python3 Extract action items from technical review meeting notes. import re import sys from collections import defaultdict ACTION_PATTERNS [ r([^。\n]?)负责([^。\n]), r(?:待办|TODO|后续|跟进)[:]\s*(.?)(?:\n|$), r(?:由)([^。\n]?)(?:跟进|处理)([^。\n]*), ] def extract_actions(text: str) - list[tuple[str, str]]: actions [] seen set() for pattern in ACTION_PATTERNS: for match in re.finditer(pattern, text): owner, task match.groups() # 过滤掉明显的人称代词误判 if owner.strip() in (我, 你, 他, 她, 我们): continue key (owner.strip(), task.strip()) if key not in seen: seen.add(key) actions.append(key) return actions def group_by_owner(actions: list[tuple[str, str]]): result defaultdict(list) for owner, task in actions: result[owner].append(task) return result if __name__ __main__: content sys.stdin.read() grouped group_by_owner(extract_actions(content)) for owner, tasks in sorted(grouped.items()): print(f## {owner}) for t in tasks: print(f- {t})这个脚本没什么高深算法但用正则处理中文的负责跟进句式实测准确率在七八成剩下的靠Agent兜底判断已经够用了。3.3 SKILL.md里步骤拆解的写法逻辑你可能会问为什么步骤要这么碎Agent又不是傻子。我一开始也这么想第一次写Skill时只写了三句话识别主题抽取信息输出纪要。实际跑下来效果很差——Agent输出的内容十分随意有时把背景和方案混在一起有时待办事项只有一条待补充。后来我才想明白问题Agent在没有强约束时倾向于用最省力的方式完成指令但这个省力理解和你期望的不一定一致。你把识别与分段单独列出来它就会真的先分段再抽取你把每一步的输入输出说清楚它才会按你的标准执行。所谓Skill写得好本质就是给Agent的每一步都打好锚点。3.4 测试这个Skill的完整流程写完之后我建议从小样本开始不要一上来就丢给它一份五千字的会议记录。我当时的测试流程# 先创建一个测试目录避免污染实际工作区 mkdir /tmp/skill-test cd /tmp/skill-test # 准备一份裁剪过的会议记录片段100-200字即可 cat meeting.txt EOF 关于订单服务拆分方案的评审记录。张伟提出按业务域拆分为订单、支付、履约三个服务。 李娜认为拆分后需要考虑分布式事务建议先调研Seata的方案。王强负责对比Seata与TCC方案的优缺点 本周五前输出对比报告。刘洋提出缓存一致性是个风险点决定暂缓后续由李娜跟进 Redis 多级缓存方案。 EOF # 在对话中向Agent提供meeting.txt内容并输入 # 用tech-review-minutes技能生成评审纪要第一次测试跑下来输出结构基本正确但有两处问题李娜的跟进 Redis 多级缓存方案没被识别成待办王强的任务负责对比方案只输出了一半。这就是我说的脚本解决七八成剩下的两成要靠你根据测试结果回头去改SKILL.md里的提示语让它明确提取待办时重点关注后续跟进负责这些信号词。改完再跑经过三轮迭代这个Skill才达到可以稳定使用的状态。4. 安装、分发与版本管理官方渠道、第三方平台与本地目录4.1 官方市场与内置仓库先说最简单的安装方式。如果某个代码工具有官方Skills市场安装通常只需要一条命令或一次点击。以我常用来演示的Claude Code为例它有官方的Skill浏览与安装入口按官方文档的指引执行即可。这种方式的优势是经过官方审核、更新有保障、依赖关系清晰。我在装这类官方Skill时有一个自己的习惯装完之后先不进对话先去看它装进了哪个目录把SKILL.md读一遍。别嫌麻烦因为很多第三方Skill的描述写得天花乱坠实际行为却和你预期完全不同。花五分钟读一遍你就能快速判断这玩意值不值得留。4.2 GitHub等平台下载怎么看源码再决定要不要装大量Skills是可以直接从GitHub下载的。搜索平台上的Skills集合仓库你会发现很多个人开发者维护了成体系的目录按领域分好类。但每次下载之前我会强制自己过三关看SKILL.md是否完整如果只有一句描述、一个名字没有执行步骤那它大概率只是一个玩具不是能用的Skill。看有没有代码好的Skill至少会带一段脚本或明确的工具链调用。空有一个markdown文件的通常只是高级提示词换个名字不是完整意义上的Skill。看更新时间和Issue超过半年没更新的Skill大概率已经和最新版本的工具机制不兼容了。4.3 手动安装三分钟搞懂本地目录结构不管从哪下载的Skill手动安装的道理都是相通的。先找到你那个AI工具的配置目录看看有没有一个专门的skills子目录没有就手动建一个。然后把整个Skill文件夹放进去确保SKILL.md在Skill文件夹的根目录下。结构示例如下~/.工具配置目录/ └── skills/ ├── tech-review-minutes/ │ ├── SKILL.md │ └── scripts/ │ └── extract_actions.py └── 其他技能名/ ├── SKILL.md └── ...装完之后重启对话或让Agent重新加载配置就可以触发测试了。如果没生效先别急着怀疑人生大概率是目录层级不对——很多人直接把SKILL.md扔进了skills根目录而没有包在子文件夹里Agent会找不到。注意不同工具对Skill目录的识别规则有细微差异。装完第一时间看工具的日志或调试输出确认有没有报Skill not found一类的错误。4.4 用Git管理你自己的Skills库我自己的Skills已经积累到比较多了所以专门建了一个私有Git仓库来管理。每个Skill一个子目录提交信息里写明新增XX能力修复XX触发词误判更新脚本兼容性。好处有三个换新机器一键拉取、改坏了可以回滚、想分享给同事时直接给他们一个仓库地址。在仓库里我还会放一个README.md里面用表格列清楚每个Skill的名称、适用场景、依赖条件、已知限制。别小看这个索引文件半个月后你再看自己写的七八个Skill没有索引你根本记不清哪个是哪个。5. 实测中的玄学问题Skill没生效的完整排查链路5.1 症状一描述了但Agent就是不调用这是我最常被问的问题。我把需求描述得清清楚楚为什么它就是不触发我的Skill排查的第一站是触发描述写错了。很多人把描述写得太宽泛或太狭窄。太宽泛Agent无法判断当前请求是否属于该场景于是干脆不用太狭窄Agent看到了但觉得你的需求没完全匹配到也不会用。我见过最典型的案例一个代码规范审查Skill描述里写的是检查代码的命名是否规范、注释是否完整用户实际输入是帮我看下这段代码符不符合我们团队规范——Agent判断这句话没有明确出现命名注释等词匹配失败。后来把描述改成当用户要求检查代码规范、代码风格、团队规范时使用才正常触发。排查链路如下打开调试模式观察每轮对话Agent内部的tool call或skill invocation日志。看输出里有没有Skill匹配分数或候选列表。如果完全没出现说明描述匹配阶段就挂了。手动把用户请求和描述放在一起对比用大白话自己判断是否有明显语义关联。5.2 症状二触发了但执行到一半就停这个情况更有意思。Skill成功触发开头几步也按流程走了但中途Agent突然断片跳过几个步骤直接输出结果。问题多半出在SKILL.md的步骤设计太反直觉。举个例子我早期写的Skill里有一句先分析所有方案再评估风险最后输出结论。这个顺序其实不符合Agent内部偏好的处理路径——它可能先看到结论两个字就直接奔着结论去了。解决办法是把步骤改成交互式的小段落每一步有输入、有动作、有输出。比如第1步只输出你识别到的主题列表不要展开分析。第2步根据用户确认逐项展开每个主题的背景、方案、风险。这样强制Agent分阶段推进效果会稳定很多。本质是把一个一次性大指令拆成了多个可验证的小步骤。5.3 症状三装了新Skill旧的开始出错这属于Skill环境污染。有些Skill的SKILL.md描述里用了非常通用的词比如当用户要求分析代码时使用。装了这个新Skill之后所有代码分析请求都优先命中了它盖过了之前那个更专用的Skill的触发。这一类问题最隐蔽因为表面上两个Skill都装了但实际上它们在抢请求。我在实践中给冲突Skill的解决思路是检查新Skill描述里的触发词将其改得更具体、更限定场景。确认描述里明确写仅当...时才使用不需要处理...场景。还有一个细节描述中出现否定句Agent在匹配时经常忽略这也很让人头疼。所以尽量用肯定句说清什么时候用别指望什么时候不用能拦住Agent。5.4 症状四权限不足Skill想读的文件读不到如果Skill的脚本里需要读文件、执行命令而当前会话的工作目录没有落到Skill期望的目录就会报各种诡异错误。这不算Bug而是权限边界在起作用。我的做法是Skill脚本里做防御性检查在开头显式判断目标路径存在且可读如果不可读就输出一个清晰的错误提示而不是让Agent在错误中猜来猜去。比如在extract_actions.py里我加了import os if not os.path.exists(input_path): print(f错误文件 {input_path} 不存在请确认当前工作目录) sys.exit(1)小细节但能节约大量排查时间。6. Skill的设计哲学、组合玩法与维护误区6.1 设计一个Skill之前先回答的五个问题我现在设计新Skill前会强制自己填一份需求判断题这个任务真的要反复做吗只做一次的事不值得封装成Skill。它适合让Agent做吗涉及大量上下文、需要人类判断权衡的活Agent不一定干得好。边界是什么允许读哪些文件、写哪些文件、执行哪些动作失败路径是什么如果Agent执行到一半发现步骤不适用它该怎么办输出物是什么不定义清楚输出格式Agent就会自由发挥。其中第4点是我后来补上的。因为Agent在真实使用中一定会遇到记录里的信息不足以做判断的情况如果不提前安排向用户澄清这个兜底动作它就会自己脑补甚至编造出不存在的所谓会议结论这很危险。6.2 组合玩法Skill是可以串联的Skills之间不是孤岛完全可以串联成流水线。我目前常用的一个组合是拿到一段代码变更先触发代码审查Skill做静态问题排查再把审查结果喂给评审纪要Skill生成评审文本最后交给提交信息规范Skill生成符合团队要求的commit message。整个过程里Agent在多个Skill之间按需切换我只需要在每个节点给一个轻量的确认指令。实现串联不需要什么特殊机制关键在于写Skill时就要想好它和其他Skill的输入输出兼容性。我习惯在SKILL.md末尾明确写一句本Skill的输出可作为另一Skill的输入格式如下这样Agent自然能在多跳对话里把它们接起来。6.3 Skill也会腐烂维护比开发重要写一个Skill也许只需要半小时但维护它需要持续投入。我最深的一个感受是Skill和代码一样是对现实流程的建模而现实流程是会变的。开会方式变了、团队约定的术语变了、工具版本升级导致上下文行为变了都可能导致Skill表现下降。我现在给自己定了一条规矩每个月把核心的Skill拿出来跑一遍固定的测试用例就像回归测试一样。发现问题及时改改不动就重写。另外尽量别攒太多Skill。Skill一多触发冲突的概率、上下文加载的成本、维护的负担都会上涨。我个人的舒适区间是常驻十来个重度使用五六个其他的用完就删。6.4 关于安全检测类Skill的一点提醒顺便说一句题外话。我在下载平台上看过不少打着自动挖洞自动化漏洞挖掘旗号的Skill。这类东西的定位非常特殊它的本质是自动化安全测试前提必须是你对自己拥有授权或明确授权的目标进行检测。没有授权的情况下对任何系统做主动探测无论在哪个国家、什么语境下都是明确不合规、不合适的。我自己的做法是只在自己的测试环境或公司明确授权的项目中尝试这类Skill并且在配置阶段就把目标范围写死绝不落到让它自己找目标这种不可控的用法上。工具无罪边界在人。最后说点掏心窝的话。Skills这套机制我第一次接触的时候也觉得不过是高级提示词但用深了才发现它真正改变的其实是人和AI协作的颗粒度。以前我是在每一轮对话里跟Agent反复博弈现在我是把博弈过程和决策标准固化下来一次性解决一类问题。这种把经验沉淀成资产的思路可能才是Skills最值得琢磨的地方。我这套评审纪要生成器Skill至今还在团队里每周稳定产出。它不聪明但它可靠这就够了。