从去年开始我在好几个项目里陆续尝试了各种给AI Agent“加能力”的姿势往系统提示词里塞长文档、把几十个工具函数直接挂上去、甚至临时写一堆一次性脚本凑合。结果就是提示词越改越长、工具列表越来越乱最后模型反而不知道该先调哪个。直到我认真把这几个月圈子里反复被提到的skills机制捡起来动手把几个真实场景完整重做了一遍才算是彻底理顺了。如果你也在折腾AI Agent尤其是想让Claude这类模型在具体任务里稳定地干活而不是每次都在对话里“自由发挥”那这篇东西值得你花点时间看完。我会从skills是什么、内部结构怎么设计到怎么从零写一个能用的技能包再到多技能库怎么治理全部用我做过的真实案例来讲尽量把能直接抄作业的细节都给你。1. 为什么我把Agent Skills当作“给AI装外挂”1.1 纯靠提示词堆功能的体验有多痛先说个很典型的痛点。我之前做过一个代码仓库巡检的自动化场景需求本身不复杂给定一个目录让它帮我统计代码行数、找出明显的调试残留、检查有没有泄露的密钥格式。第一版做法很直接把这三条需求写进系统提示词再给模型挂几个shell工具和文件读取工具。结果一跑就露馅模型确实会去执行命令但它拿到一整个仓库之后完全不知道先看哪个目录、哪些文件值得读、统计口径应该是什么经常从.git和node_modules里翻出几万个文件然后一本正经地给我产出一份没什么用的报告。这背后的问题不是模型笨而是我把“任务目标”和“任务执行细节”混在一起塞给了它。提示词只说了“要做什么”但“怎么做、按什么顺序、哪些该忽略”全都没有模型只能自己瞎猜。后续我试着把所有规则写成一大段详细提示词能力是上去了一点代价是每次对话光携带这些指令就要消耗大量上下文稍微改一个规则又会连带影响其他任务整个提示词像一团互相拉扯的意大利面。所以skills这套机制打动我的第一个点就是它把“某个具体任务的方法论”给拆出来独立打包了。它不是往系统提示词里继续堆字数而是让模型在需要的时候自己决定加载哪个技能包。做一个巡检任务就写一个巡检技能做一个文件整理就写一个整理技能彼此不干扰调用时才占用上下文用完就释放。1.2 Skills相对提示词库、MCP、微调的几个关键优势圈子里现在还流行其他几种给Agent加能力的方案我也都试过一轮。做提示词库Prompt Library其实最普遍本质上就是一堆写好的指令模板但这类库跟模型之间没有明确的“按需发现”机制你仍然得在自己的应用代码里判断什么时候用哪份模板工作量一点没少。MCPModel Context Protocol解决的是外部工具和数据的连通问题适合去连数据库、连API、连浏览器但它更像是一套“外接设备”对于“怎么完成一项包含多步骤的领域任务”这件事粒度还是太粗了。微调模型则完全是另一条路成本高、周期长而且每次需求变了都得重新调一轮除非是特别垂直的领域否则普通项目根本玩不起。相比之下Skills的做法是模块化的一个技能可以包含操作说明、脚本、参考文档、小工具全部收进一个目录模型看到描述后自行决定是否加载。它介于提示词和代码工具之间既能给模型稳定“方法论”又能调用真实脚本和外部资源。我的体感是它特别适合那种“有清晰流程、有固定套路、反复执行”的任务比如代码巡检、批量文件整理、数据清洗、格式转换、生成周报、处理表格这类任务要的是稳定复现不是每次让模型临场发挥。2. 一个Skill的完整解剖SKILL.md、脚本、资源与依赖2.1 SKILL.md的frontmatter和description决定了模型会不会看你一眼一个标准技能包的核心是一份SKILL.md文件。理论上看过官方文档的朋友都知道它的头部有一段YAML格式的frontmatter里面主要写name和description。但真正落到实战里这两个字段的写法直接影响模型“动不动用你”我在这上面栽过好几次跟头必须多说几句。name不要起得太抽象也不要太长。我见过有人写code-review-skill-for-repo-analysis-v2这种名字首先就占字符其次模型并不需要靠名字来理解技能它更依赖描述。description才是真正的“钩子”。一个合格的描述应该回答三件事这个技能解决什么问题、在什么条件下触发、用了之后大概能得到什么结果。我一开始写得很含糊比如“用于代码仓库分析”结果模型面对一个仓库时根本不知道要加载它因为描述里没有把“分析什么、怎么触发、产出什么”讲清楚。一个我实测效果不错的描述模板是Trigger when the user asks to inspect a Git repository for leftover debug code and potential secret leaks. Analyzes file structure, runs targeted checks, and outputs a structured report.意思是“当用户要求检查Git仓库中是否残留调试代码和潜在密钥泄露时触发。分析文件结构、执行定向检查并输出结构化报告。”模型在决策是否加载这个技能时它会把自己当前的任务和这段描述做语义匹配描述越贴近真实使用场景触发率越高。2.2 content块、脚本与资源的编排逻辑SKILL.md的正文部分通常包含几个content块以及引用脚本、资源的相对路径。这就是技能包的核心“方法论”。我当时做巡检技能时在content块里写了这么几层内容第一层明确任务边界。告诉模型这个技能只做代码静态扫描不做依赖安全审计不负责自动修复代码。边界清晰有两个好处一是模型不会把任务扩散到它不擅长的领域二是当用户提的需求超出边界时模型能明确拒绝或建议使用别的技能而不是硬着头皮做。第二层给出执行步骤。比如先读取仓库顶层目录结构跳过.git、node_modules、dist、build等目录再根据语言类型识别主源码目录然后运行我提供的扫描脚本最后按固定模板输出报告。这相当于把老师傅干活的操作手册直接给模型看它每一步都知道该干什么。第三层写清楚需要调用哪些脚本和资源。我会在content块里用相对路径引用scripts/scan_repo.py、config/ignore_patterns.json模型读到这里就知道去技能目录下找对应文件来执行。目录结构大致是repo-inspector/ ├── SKILL.md ├── scripts/ │ ├── scan_repo.py │ └── check_secrets.py ├── config/ │ └── ignore_patterns.json └── references/ └── report_template.md这种“方法论在文档里、实现在脚本里”的分工是我用下来最顺手的模式。文档负责给模型讲清楚思路和步骤真正的重活交给Python脚本去干双方各司其职性能和稳定性都有保障。2.3 依赖声明和运行环境既然是“工具包”就得自带运行说明既然技能包里要跑脚本就会遇到环境依赖的问题。我在初版时踩过一个坑我给模型写了一个要用ripgrep的扫描脚本结果部署环境里根本没装rg命令模型执行时直接报错然后它居然尝试自己用Python现写一个简易搜索器产出结果完全对不上。从那以后我坚持在SKILL.md里加一个独立小节专门描述运行环境要求。这个小节一般放在正文很靠前的位置用“Requirements”之类的标题罗列清楚需要Python 3.10、需要能使用bash、需要提前安装ripgrep、需要网络访问如果某些检查需要调外部API并且给出安装命令示例。另外我强烈建议在脚本里加一个“启动自检”逻辑比如检查依赖命令是否存在不存在就直接输出友好错误而不是让模型在报错堆栈里反复挣扎。让模型知道“这个技能有明确的完成标准”一样重要所以content块里我还会顺带写上成功产出的判定条件比如“输出报告包含文件统计、调试残留下标、密钥风险清单三部分”这样模型做完后自己心里有数我也好验收。3. 从零构建一个可用的Skills包以代码仓库巡检为例3.1 需求拆解我要模型替我做哪几件事纸上谈兵没意思我直接说一个我完整做过的例子。有一阵我要频繁检查同事交上来的代码仓库为了赶进度很多分支里混着console.log、写死的测试密钥、临时注释块甚至有人把.env直接提交上来了。人肉翻太累我就想着这事能不能让Agent按一套固定流程替我干。拆解之后我确定这个技能要覆盖四件事摸清仓库结构知道有哪些主流语言、哪些目录是需要重点检查的源码目录。统计基本规模代码行数、文件数、主要文件类型分布。扫描调试残留找出console.log、print、debugger;、TODO/FIXME等标记并按文件归类。检查潜在密钥泄露扫出看起来像API Key、密码、私钥的高风险字符串。一个技能做的事情不宜过多这四件事已经是上限了。如果有更多需求我宁可拆成第二个技能也不往同一个包里硬塞否则SKILL.md的指令会变得特别长模型反而抓不住重点。3.2 一次性提交初版把“人肉操作”翻译成自动化命令需求定完我来写第一个版本的扫描脚本。核心是用Python标准库加一些简单的正则规则没必要一上来就搞得很重。里面的关键设计有几个忽略目录列表做成可配置的JSON支持按文件后缀做类型归类调试残留检查做成一个规则映射表以后加规则只改配置不改代码密钥检测用高熵字符串和常见Key名组合判断减少误报。脚本里比较核心的一段逻辑如下#!/usr/bin/env python3 import json import os import re from collections import defaultdict ROOT os.getcwd() IGNORE_DIRS {.git, node_modules, dist, build, __pycache__, .venv, venv} def iter_source_files(root): for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in IGNORE_DIRS] for fn in filenames: yield os.path.join(dirpath, fn) def classify_file(path): ext os.path.splitext(path)[1].lower() if ext in {.js, .ts, .jsx, .tsx}: return javascript if ext in {.py}: return python if ext in {.go}: return golang if ext in {.java}: return java if ext in {.md, .txt, .rst}: return document return other def scan_debug_markers(path): markers { console.log: console_log, print(: print_statement, debugger;: debugger, TODO: todo, FIXME: fixme, } hits defaultdict(list) with open(path, r, encodingutf-8, errorsignore) as f: for idx, line in enumerate(f, start1): for marker, tag in markers.items(): if marker in line: hits[tag].append((idx, line.strip()[:120])) return hits if __name__ __main__: stat defaultdict(lambda: {files: 0, lines: 0}) debug_hits defaultdict(list) secret_hits [] for path in iter_source_files(ROOT): kind classify_file(path) stat[kind][files] 1 try: with open(path, r, encodingutf-8, errorsignore) as f: line_count sum(1 for _ in f) stat[kind][lines] line_count except Exception: pass markers scan_debug_markers(path) for tag, lines in markers.items(): debug_hits[tag].append({file: path, lines: lines[:20]}) report { language_stats: stat, debug_markers: {k: v for k, v in debug_hits.items()}, secret_candidates: secret_hits, } print(json.dumps(report, ensure_asciiFalse, indent2))这个脚本故意写得比较朴素我连第三方库都没引就是怕模型在执行时还要现场pip install平白增加不稳定因素。密钥检测部分我初版只留了接口把所有规则单独放在配置里。脚本执行完会输出一份JSON格式的报告模型拿到报告后再根据SKILL.md里的模板把它转成自然语言小结这样两边都轻松。3.3 加上极简配置与结果输出让模型端到端使用脚本只是半成品真正让这个技能“好用”的是SKILL.md里对使用流程的编排。我给它写了一版操作流程先运行python scripts/scan_repo.py扫描仓库拿到原始JSON再结合JSON产出一份Markdown报告报告要包含仓库概览、按语言分类的行数统计表、调试残留下标清单带文件路径和行号、密钥风险提示最后如果发现了高危密钥必须建议用户立即轮换而不是把密钥原样输出在报告里。为了让模型产出的报告风格统一我在references/report_template.md里给了一个模板里面用占位符标好了各个区块的位置模型只要照着填就行。实际跑下来不同仓库的最终报告差异主要是数据不同结构基本稳定。我还把忽略目录的配置单独抽成了config/ignore_patterns.json这样如果某个仓库有特殊的生成目录直接改配置就好不用动SKILL.md也不用改脚本。4. 让Skill真正落地的调试心得模型调用触发、工具边界与失败兜底4.1 模型为什么就是不加载我的Skill先看这四个原因写完了技能包你以为就万事大吉了不是的真正的折腾从部署之后才开始。我做第一批skill时最常遇到的情况是明明技能放在目录里模型偏不加载非得我手动指名道姓说“使用repo-inspector技能”它才动。排查下来问题基本出在以下四个地方。第一description写得太泛。比如只写“代码分析工具”模型在真实对话里根本没法把“帮我看看这个仓库有没有问题”和“代码分析工具”建立强关联它很可能觉得直接读文件就行。要让description里出现用户视角的触发词比如“检查仓库”“扫描调试代码”“密钥泄露”。第二技能数量太少不存在“不得不选”的场景。这个有点反直觉但确实存在。当系统里只有一个技能时很多模型反而不太会主动去加载它因为普通的文件读取工具也能凑合干事。我加了几个技能形成“技能库”之后模型那种“遇事不决先看技能表”的习惯反而被培养起来了因为在它眼里可供选择的方案变多了。第三技能包的放置位置或发现机制不对。不同客户端加载技能的方式不同有的要求放在特定目录下有的靠配置文件声明。如果你发现模型死活看不到技能先检查技能是否被正确挂载节点有没有同步成功这个低级错误我犯过不止一次。第四任务触发条件太模糊。比如你想让模型用它来做某类文件整理但SKILL.md里没有写清楚“只处理这类任务、其他任务不要管”模型就会犹豫到底该不该用。我给每个技能都加了“适用范围”和“不适用范围”两部分说明从此触发准确率高了不少。4.2 Skill内部的工具边界不是让AI为所欲为而是给它划好跑道技能包里既然可以引用脚本就要面对一个边界问题脚本的权限边界、操作边界到底怎么定。我的原则是“只读优先、最小写入、明确禁区”。在代码巡检这个例子里我明确告诉模型扫描脚本只能读文件不允许修改任何源码报告可以直接生成在用户指定目录但要在文档里说明改动了哪些地方。这样即使某个仓库状态很差也不会因为模型自作主张改了代码导致更严重的破坏。另外内部脚本出现异常时不要指望模型能自己“灵机一动”把脚本逻辑修好。脚本应该把错误拆成两类环境错误和数据错误。环境错误比如找不到命令、缺某个依赖这类错误建议在脚本启动时主动检测并输出“Missing dependency: ripgrep. Please install with ...”数据错误比如某些二进制文件编码无法解析直接跳过并记录即可不用中断整个流程。这种把异常处理前置到脚本里的做法能省掉模型大量的无效递归尝试。4.3 失败兜底与日志AI小工出错时你得能快速定位Agent跑任务不回报错但产出的结果就是不对劲这种“软失败”比硬报错更难查。我后面所有技能包的脚本都养成了一个习惯输出机读的JSON结果但同时把详细的执行日志写到单独的文件里。比如扫描任务结束后会多出一个scan_log.json里面记录每一步运行了多久、扫了多少文件、跳过了哪些目录、有没有文件因权限问题没读成。这样如果最终报告和其他人肉检查结果对不上我能直接打开日志看模型到底执行了什么而不是靠猜。另外一个很实用的兜底策略是给技能包写一个“自检模式”。我加了几个样例目录里面故意放了调试代码和一个伪造的测试密钥技能跑完自检后会输出一个验证结果。升级技能包或换环境时先跑一遍自检能快速确认脚本在这个环境里还能不能正常执行也方便做回归测试。4.4 实测这个巡检Skill放到真实仓库里跑出来是什么样技能写好后我拿一个中等规模的前端仓库做了次实测。仓库大概有四百多个文件主体是TypeScript和少量Python脚本。模型按要求先跑了一遍扫描脚本输出显示忽略目录占了很大比例真正扫描的有效文件是两百多个调试残留检查找到三十多处代码中的调试输出和若干处注释标记密钥扫描模块因为规则配置得比较克制只报了三个可疑字符串人工复核后其中两个是测试环境用的假密钥一个是真正的内部API Key。那次实测最让我满意的地方是模型能照着模板把JSON转成一份干净的报告并把高危密钥单独列在最前面提醒优先处理还会主动问要不要用另一个技能包去自动轮换密钥。整个流程从开始扫描到报告成型大概只花了两分钟里面大部分时间是在跑脚本模型的判断基本没有浪费步骤。这比我之前纯靠提示词驱动的那版体验好了不止一个量级。5. 多技能库的治理经验命名规范、心智占用与版本管理5.1 命名规范比想象中重要当技能从一个变成十几个之后命名就是第一道管理门槛。我见过有人给技能起名叫fetch-news有人叫news_grabber_v3_final还有人叫get_breaking_news_with_search_and_summary最后全乱套了。我后来定的规范很朴素全小写、用连字符分隔、一个动词加一个名词最多三四个单词。比如repo-inspector、weekly-report-generator、csv-cleaner。看起来简单但当你需要在一个配置文件里列出十几个技能时这种命名方案读起来非常省脑子。每个技能包的根目录里我还会放一个极简的README.md用三五句话讲清楚这个技能包管什么、不负责什么、入口文件在哪。SKILL.md是给模型看的主文档不用顾虑但README是给人看的索引两个分开写各干各的活。5.2 心智占用一两个精品比一百个玩具强技能包越攒越多之后我发现一个现象模型在决定加载哪个技能时也是要“看”技能描述列表的。如果列表太长描述又写得差不多模型选择困难症就来了甚至会先随机选一个不合适的技能跑一遍失败了再换。这个行为会明显拉高调用延迟和出错概率。所以我现在对技能包质量的要求是宁缺毋滥。一个技能如果满足不了“三周内至少被真实用到两次”这个条件我就会考虑把它删掉或者合并。技能的粒度也应该偏向“高频、标准、独立”。比如把“生成每日站会摘要”单独作为一个技能是合理的因为它流程固定但把“项目管理工具”全部塞进一个超级技能包就很不合理因为内部流程差异太大模型根本没法在一份SKILL.md里消化。5.3 版本管理与回滚SKILL.md也是会“养歪”的最后一个治理经验是关于版本管理。技能包虽然不是传统代码库但它里面的脚本、提示词、规则配置都会随着需求调整不断变化。我会给每个技能包单独开一个Git仓库或子目录每次改动都留下commit记录尤其是对SKILL.md的改动要习惯写清楚“改了哪段话、为什么要改”。原因很简单一个技能包的表现依赖“文档描述和脚本行为的一致性”有时你觉得只是优化了描述实际上会让模型的执行路径发生明显偏移。没有版本记录出了问题就只能从头排查。我还养成了一个习惯每次改完SKILL.md都要重新跑一遍上一节提到的自检模式并至少用三个不同的真实任务验证触发率和产出质量。如果发现某些描述改完后模型触发频率反而下降了我会回退到之前那版重新改。技能包是活的需要像养产品一样持续迭代而不是建完就撒手不管。以我最近一段时间反复折腾Agent Skills的体感来说这套东西最值钱的地方在于它把一个模糊的“AI助手”真正变成了可以工程化管理的“能力工具箱”。每个技能包就是一个模块加载、使用、卸载都非常清晰出问题时也能精准定位是方法论没讲明白还是脚本本身有bug。如果你刚开始接触建议先挑自己日常最高频、流程最固定的一个任务从写一份极简的SKILL.md加一个脚本做起跑通之后再慢慢扩充技能库。等你的技能包积累到十几个并且都能稳定触发时再去对比之前纯提示词驱动的Agent你会明显感受到什么叫“靠谱的AI外挂”。