最近我在好几个技术群里看到同一个词被反复翻出来skills。有人说自己在各种AI工具里装了十几个技能包也有人在评论里问skills下载平台有哪些问了一百遍还有人把superpowers这个集合包装得神乎其神。我一开始挺不以为然的——这不就是给AI准备的一套提示词模板外加几个文件吗真有那么玄结果自己从安装到动手开发一个skills完整走了一圈之后发现这里面的水比想象中深。表面看是怎么把指令写清楚实际上涉及提示词组织、上下文管理、脚本辅助、团队协作乃至工作流设计。这篇文章把我这两周折腾下来的完整过程、原理拆解和踩坑点都摊开说一遍给刚接触skills这个概念、或者已经装了但不知道下一步怎么办的朋友当一份实操参考。1. AI Agent里的Skills到底是什么1.1 从自定义指令到技能包的进化我先交代一下背景。过去一年我主要用AI编程工具和智能体做项目开发早期的做法非常朴素在一个叫CLAUDE.md或AGENTS.md的项目说明文件里写上本项目用某个框架、文件命名规则是什么、遇到问题先检查哪里。这套做法有效但弊端也很明显——项目说明文件会越写越长系统提示词被无限撑大最终挤压了模型处理实际任务的上下文空间。而skills的出现在思路上做了一个很重要的转变它不再要求把所有规范罗列在系统提示里而是把完成某类任务的方法论打包成一个可独立存在的文件夹模型收到相关任务时才去加载这个文件包。社区里流传很广的superpowers这类技能集合包本质就是把如何读文档、如何调试、如何做TDD这些工作方法论全部文件夹化、资产化了。理解这一点再看后面那些安装教程思路就完全通了。1.2 skills真正解决的三个痛点为什么这套设计最近突然爆发我自己的体感是它精准踩中了三个长期痛点。第一个是提示词膨胀。以前给AI描述怎么做事所有细节都得堆在系统提示里稍微复杂一点的项目提示词就超过几千行。模型面对大量不相关的指令反而容易忽略关键内容。skills按需加载平时不占上下文用到时才被调用等于是把提示词做了物理上的按需分页。第二个是流程不可复用。我自己以前踩过不少坑在某次对话里好不容易把一套论文大纲方法论调整到很好用结果换了个项目、换了会话这些东西全部归零。skills让这些经验变成一个可以在任意项目里复制粘贴的文件夹跨会话、跨工具、甚至跨成员复用。第三个是能力不互通。现在AI工具越来越多同一个需求在不同工具里要重复定义。skills采用的格式足够通用既能被主流的coding agent工具加载也能被一些轻量应用识别。这种一次开发、多处使用的体验正是很多人开始研究agent skills测试和skills开发的原因。1.3 它和插件、工具调用的本质区别很多人会把skills理解成插件。按我目前的认知这个类比不够准确。插件是程序层面的扩展它要注册真实函数、申请权限、对接外部服务skills则主要是提示词层面的操作手册里面最多放一两个轻量辅助脚本核心其实是告诉模型遇到这类活儿按这套流程办。换句话说插件是给软件增加了一个新功能skills是给AI增加了一种新的工作方式。这个区别决定了skills的开发门槛极低——你不需要会写复杂的API对接只要会组织文字、会写基本的Markdown就能做出一个很实用的技能包。这也解释了为什么热词里会同时出现skills开发和agent skills测试技术门槛低但质量差距可以非常大。2. skills的底层机制目录、说明、示例与脚本2.1 一个skills就是一个约定好结构的文件夹这是我认为理解skills最核心的一点一个技能包就是一层目录。我见过太多人一上来就问skills用什么语言写是不是要写Python/Node其实都不是。你只需要创建一个目录在目录里放一份SKILL.md作为主入口再根据需要放参考文件和辅助脚本。我把一个典型目录结构贴在下面以我自己做的论文提纲生成器为例skills/ └── paper-outline/ ├── SKILL.md ├── reference/ │ ├── outline-example.md │ └── structure-checklist.md └── scripts/ └── check_length.py模型运行时会读取SKILL.md再按里面的指引去读取reference里的文件、运行scripts里的脚本。整个过程不需要编译不需要安装依赖只要能读文件、能看懂Markdown就能运行。很多人在网上找skills安装包下载拿到的其实也就是这样的文件夹解压后放到指定路径即可使用。2.2 SKILL.md的正确写法决定了技能好不好用SKILL.md一般包含两部分开头的frontmatter参数区以及正文的说明区。frontmatter里最核心的是name和description两个字段。--- name: paper-outline description: 根据用户的零散笔记、关键词或初步想法生成结构清晰的学术论文/技术文章大纲。当用户提到写论文搭框架列提纲整理研究思路时使用。 --- 正文部分写操作步骤、输出要求、注意事项。这里有个非常容易犯的错误description写得太笼统。如果你只写生成大纲四个字模型看到任何类似字眼都可能触发或者反过来因为看不懂你技能的具体适用场景而完全不触发。我推荐的做法是在description里明确写清楚三件事适用范围、触发关键词、输出目标。实测下来这段描述写得好不好直接决定技能被调用的频率和质量可以说是整个skills里性价比最高的优化点。2.3 参考示例与辅助脚本的真实作用很多人在SKILL.md写完之后就直接收工这是不对的。reference目录里的示例文件看起来不起眼实际价值非常大。模型看一段干巴巴的操作说明远不如看一个完整的输入输出对照来得直接。举个例子我在reference里放了一篇论文的before/after对比前面是作者给的混乱笔记后面是整理好的大纲。模型有了这个样例输出的格式基本就不会跑偏。辅助脚本则用来做机械性的校验比如检查大纲是否有章节重复、字数是否在指定区间。这部分可有可无但对输出稳定性有强迫症的朋友强烈建议加。我自己的经验是加了参考示例后技能输出的稳定性提升非常明显比反复调整SKILL.md正文中的措辞更有效。2.4 第一性原理skills本质上是给AI的流程说明书如果把这件事剥到最底层skills本质上就是一套元提示词。它不给模型提供额外的推理能力而是把专家的行业经验、操作习惯、质量标准固化成了文字。就好比一位厨师不会因为看了一本菜谱而突然变强但他做菜时手边放着菜谱出品标准就会稳定得多——配菜顺序不会忘、调味比例不会飘、摆盘风格不会乱。模型也一样它有很强的生成能力但如果不给一个明确的操作框架很容易天马行空skills就是那个把天马行空约束成按部就班但质量稳定的框架。想清楚这一点你就会明白为什么skills不需要做得多复杂核心永远是把模糊的经验变成清晰的步骤。3. 怎么找到、安装并真正用起来现成skills3.1 值得关注的几个来源说实话我最初也是被skills下载平台有哪些这类问题吸引的。目前大家常用的渠道主要有三类。第一类是官方市场比如Claude在应用中提供的技能市场装起来最省事质量也有基本保障第二类是GitHub上的开源仓库像awesome-skills这类聚合项目会把社区里比较受欢迎的skills按领域分类你按需下载即可第三类是各技术社群、博客里博主自己放出来的技能包这类通常带着很强的个人色彩适合参考思路后再改进。国内的话Gitee上也有不少搬运或原创项目访问速度反而更稳。要提醒一句任何来源都先看目录结构和SKILL.md内容尽量选择纯提示词即可运行的轻量形态别一上来就跑脚本——你根本不知道它里面做了什么安全边界要先想清楚。3.2 安装的本质把文件夹放到约定路径安装一个skills说白了就是把目录放到能被你的AI工具扫描到的地方。以我自己在用的claude code为例全局技能放在用户目录下的~/.claude/skills里面项目级技能放在当前项目下的.claude/skills目录里。放进之后重启会话让新session重新扫描一遍目录技能就会进入可用状态。其他工具的原理也完全一致只是目录名可能不同有的叫.agent/skills有的叫skills。如果你用的是带图形界面的应用有的会提供技能市场按钮点击安装会自动写入正确路径。还有一些工具支持在配置界面里手动指定技能目录建议直接用查看配置目录之类的功能确认一下别凭感觉乱放不然半天不生效还找不到原因。3.3 实测几个热门技能的调用效果为了对比效果我装了大概二十个不同领域的skills包括社区里人气很高的superpowers系列以及一些写论文、写代码的特定技能。实测下来有几个感受比较有代表性superpowers这种方法论集合型技能适合面对一个不知道从哪下手的复杂问题时作为思维框架调用但它给你的不是具体代码而是先做什么再做什么的指引非常适合做项目冷启动写论文类的技能很依赖参考示例的质量示例好则输出结构极其规整示例差则模型输出会变得很教条。前端开发类的技能表现最稳定因为它们通常只是封装了组件命名、状态管理、样式规范这些约定模型按约定生成代码命中率明显高于裸奔状态。至于安全研究领域也有人在做技能包但这类工具的适用边界非常严格只建议在合法授权的前提下参考思路不要盲目套用。3.4 一个不太优雅但非常好用的验证方法装完之后怎么确认技能真的被AI感知到了我有一个土办法直接问当前使用的agent你现在可以使用哪些skills如果它能准确报出刚装的技能名说明扫描成功。另一种更实际的验证方式是制造一个强触发场景比如装了论文提纲类技能就直接丢一句帮我列个论文提纲看它的输出是不是明显带有你技能里规定的结构。如果触发不了大概率是description写得不够明确或者扫描路径不对。往下看踩坑章节基本能找到答案。4. 从零开发一个论文提纲生成器完整实操流程4.1 先划清边界再动手开发skills的第一步不是写Markdown而是想清楚这个技能管到哪、哪些不管。我给自己定的目标是接受零散的笔记、关键词、半成品想法输出一份带论证结构层次、有论点展开顺序的论文大纲明确不管排版细节不做文献自动检索不替用户决定结论。边界划得清楚后面写提示词的时候就不会越写越乱模型也不会因为指令过于宽泛而输出一堆套话。确定目标后我把使用场景限定在学术初稿、公众号长文、技术博客三类这样在示例选取和措辞上可以更具体不至于为了兼容所有情况而变得空泛。4.2 创建目录并编写SKILL.md我直接给出核心文件的完整内容因为这部分最值得抄作业--- name: paper-outline description: 根据用户的零散笔记、关键词或初步想法生成结构清晰的学术论文/技术文章大纲。当用户提到写论文搭框架列提纲整理研究思路时使用。 --- ## 工作流程 1. 先向用户收集背景信息目标读者、文章类型、核心论点、限制篇幅。 2. 提取用户给出的零散笔记中的核心概念去除重复或无关内容。 3. 输出大纲大纲必须包含 - 引言问题背景、研究缺口、本文贡献 - 主体至少三个论证模块每个模块说明论点、论据来源、小节划分 - 结论总结、局限、后续方向 4. 在大纲末尾附结构自检清单逐项打勾。 ## 输出约束 - 不使用综上所述等空话。 - 每一条目必须给出能落地的论证方向不能只写概念名词。 - 如果用户提供的素材不足允许追问两次最多两次。这段内容不算长但已经把触发条件、处理流程、输出格式、质量约束都锁死了。写完之后不要急着用下面两件事更重要。4.3 用reference文件铸入示例与检查清单接下来我在reference目录下放两个文件。第一个叫outline-example.md内容是一对混乱笔记 - 成品大纲的完整样例模型在生成时会自动模仿这个结构第二个叫structure-checklist.md相当于一份评分标准包括每个模块是否都有论证方向论点之间是否存在逻辑跳跃是否包含结论与局限等条目。放在这个目录里的文件会被模型当作参考依据而不是输出对象所以在写的时候要把它们当作标准答案来打磨。我给这个技能的实际使用体验里加了示例之后的输出比只给说明时的输出质量高一个档次这个差别非常值得注意。4.4 放进去实测然后循环迭代开发skills最忌讳的就是写完SKILL.md就以为完工。我把它放进~/.claude/skills/paper-outline/之后用了一段真实的研究草稿做测试。第一版输出结构对但有一处硬伤大纲里的某个章节明显是重复上一个模块的内容模型按照流程走了但没有做去重。我在SKILL.md里补了一行输出前必须有一步去重检查把相近论点归并第二版改善了。第三版我又发现它不会自动给出素材不足追问的对话而是闷着头生成一个空壳子大纲于是在流程第4步后加了一个强制追问条件。这种加约束-重启会话-再测试的小循环是打磨skills性价比最高的方式。每次改完SKILL.md记得清掉当前会话上下文再重测否则模型可能还在用旧的指令输出。4.5 收尾整理、打包、发布当技能稳定之后我在目录根加了个README.md写清楚适用场景、安装路径、参数说明然后把整个目录推到自己的GitHub仓库。这样我换一台电脑或者拉同事一起用只要一次clone就能复现整个技能。整理这一步别省过一次话术、补一版示例技能的可用性和传播性都会好很多。如果你主要用IDE类工具也可以直接把技能目录放到项目仓库的.claude/skills下面团队所有人拉到代码后自动就拥有了这个技能不需要额外配置。开发到现在这个技能已经在我的写作工作流里至少用了十几次每次输出的结构性都明显优于不使用技能时的裸提示词输出。这也是我觉得技能开发最值得投入的地方一次沉淀长期复用。5. 使用和开发skills最容易翻车的五个地方5.1 相对路径与资源引用别想当然我踩的第一个坑就是相对路径问题。模型在加载一个skill的时候它的工作目录不一定是skill所在目录如果不写清楚reference目录在哪个位置它往往读不到文件。解决办法很简单在SKILL.md里写清楚所有文件与SKILL.md位于同一目录下或者直接把绝对路径写进正文。社区里很多技能包喜欢把reference目录叫成examples自己创建时务必保持命名一致你写的路径和实际目录结构必须对得上。还有一个隐蔽问题有些技能的SKILL.md写的是Windows风格反斜杠路径放到macOS或Linux上就失效了所以写路径时尽量用正斜杠/兼容性最好。5.2 中文和文件名是个隐蔽坑中文用户经常会用一个带中文名的目录来存放技能例如论文提纲生成器。这在部分工具里没问题但一旦辅助脚本用Python打开中文路径文件编码问题就会冒出来——Windows环境下尤其明显GBK与UTF-8的纠缠能让人崩溃。我建议所有目录名、文件名一律用英文小写加连字符内容里的中文不受影响。脚本处理文本时统一指定UTF-8编码比如open(path, encodingutf-8)能避免90%的编码问题。另外脚本输出中文提示时也要注意终端编码否则模型读到乱码会误解执行结果。5.3 模型明明可以调用却不调用如果你确认技能已经安装成功但发现它总是不触发问题多半出在description上。太宽泛的描述会让模型拿不准该不该触发太狭窄又会被忽略。一个实用的写法是把可能的调用场景直接塞进description里例如当用户输入以下关键词时调用写论文、搭框架、列提纲、整理思路、起草长文。还有一些工具需要在设置里开启技能开关或者要求模型本身具备工具调用能力这两项状态需要确认一下。如果你改完description仍然不触发试着换个同义的触发词比如研究思路和阅读笔记表面相近但模型对前者的触发意愿会明显更高。5.4 过度设计会反过来伤害输出另一类常见问题是把所有希望都写进同一个技能。我有一次试图做一个万能内容创作技能要求它同时处理大纲、写作、润色、配图建议、SEO结果它在任何一个环节都表现平庸。技能不是操作系统没必要包揽万物。一个技能最好只解决一类问题把复杂度拆成两三个独立技能去组合使用反而更灵活。比如把大纲生成和文字润色拆开先调用前者得到框架再交给后者优化措辞效果就比一个巨型技能稳定得多。你在设计时可以用一句话描述技能用途如果这句话里出现了和或者等等这类词大概率就是设计过载了。5.5 脚本与外部调用要克制技能里可以放脚本但别什么都往里塞。脚本的目的应该是做机械性校验比如检查字数、格式化输出或者生成一个特定的数据文件而不是代替模型去完成需要语义理解的推理。如果你硬要脚本做判断这段文字逻辑是不是通顺你会在脚本的复杂度里挣扎很久结果还不好。只把脚本用于确定性的任务其余交给模型本身。另外除非必要不要让脚本请求外部网络接口否则一个技能就变成了一个潜在的信息泄露面。保持技能的本地性、确定性是它作为可复用资产的基本素养。6. 把skills融入日常工作的三种实际姿势6.1 写论文和长文结构先行素材后补在写长文这件事上我目前最顺手的方式是笔记丢进去-技能出框架-人工补血肉。先把脑子里所有零散的想法、引用的素材、待论证的点全扔给agent让论文提纲技能生成一个带论证方向的结构之后每一节再单独对话用agent协助把这些论点写成段落。这样做的副产品是我的写作不再从空白页开始而是从一份自己认可的提纲开始这种心理减负比AI输出本身更有价值。很多朋友问我写论文类skills有没有推荐的我会建议别直接抄别人的而是把自己的审稿习惯、常用结构、写作偏好写成技能那才是真正属于你的东西。6.2 前端开发把团队规范固化成技能前端开发是另一个我强烈推荐用skills的地方。我见过太多团队在项目说明文件里堆规范堆到最后模型一生成代码就四处踩线。把组件命名规则、目录结构、样式方案、状态管理约定封装成前端开发skills之后agent生成代码时就会自动遵守规范每次拉新成员加入也能快速上手统一生成风格。我在一个中小型项目里实测过让技能负责规范约束比反复在提示词里强调效果省心很多。这里要特别注意的是前端技能尽量钉死细节连文件名用驼峰还是下划线、样式变量怎么命名、组件放在哪个目录都要写清楚。越具体模型就越不会自由发挥。6.3 多技能协同与团队资产化最后一个姿势是让多个技能协同工作。比如做一次完整的技术方案我先用方案设计技能定架构用代码评审技能过一遍设计合理性再用测试用例生成技能补测试。这种串行调用方式比把方案设计、评审、测试写进一个大技能更清晰也不容易让模型在某一步被无关指令带偏。更重要的是当技能统一放在团队共享目录或仓库里时它就变成了团队的沉淀资产——新成员加入就能复用别人踩过坑总结出来的方法。这一点我觉得是skills长期价值里最容易被低估的部分。你单独一个人积累的经验有限但一个十人团队每人贡献三五个高质量技能这个集合就非常可观了。最后说一点个人体会。这半个月从怀疑到动手改造如今我已经养成习惯凡是让agent做三次以上的同类事情值得花半小时做成一个技能。技能本身不复杂复杂的是你愿不愿意把自己的工作方法论摊开来写清楚。写清楚之后你会惊讶地发现自己原本很多判断其实是隐性知识而把它们显性化之后不仅AI更听话连自己的流程感都强了不少。这大概是当前这个阶段里一个人最划算的自我投资之一。