1. 从“skills”这个热词说起它到底是什么最近半年不管是在技术社区、开发者群聊还是各种工具分享帖里“skills”这个词出现的频率高得离谱。你随便翻翻热搜榜能看到Agent Skills、codex skills、claude agent skills、skills开发、skills推荐这些词扎堆冒出来。很多人第一次看到会懵这说的是人的技能还是某个新框架其实都不是或者说不完全是。我先把结论摆在前面这里说的skills指的是一套围绕 AI Agent智能体构建的可插拔能力模块。你可以把它理解成给 AI 助手装的“技能包”——每个 skill 就是一份结构化的说明文档加配套资源告诉 AI 在遇到某类任务时该怎么做、用哪些工具、遵循什么流程。它不是一个编程库也不是一个 API而更像是一份写给 AI 看的“操作手册 工具箱说明书”。这个概念的走红跟几个主流 AI 编程工具的推动直接相关。Claude 的 Agent Skills、Codex 的 skills 机制、以及 Google Cloud 那边对 agent 能力的标准化尝试让“给 AI 装技能”从一种零散的 prompt 技巧变成了一套有目录结构、有元数据、有加载规则的工程化实践。热搜里那个claude agent skills: a first principles deep dive就说明已经有人开始从第一性原理去拆解它了。那它到底解决什么问题说白了就是让 AI 在特定领域里表现得更专业、更稳定、更可复用。你不可能每次都把一整套复杂流程塞进对话里那样既啰嗦又容易漏。skills 的思路是把“怎么做某件事”的知识固化下来需要的时候按需加载。比如你要 AI 帮你写论文就加载一个论文写作 skill要它做前端组件就加载一个前端开发 skill要它跑自动化测试就加载一个测试 skill。适合谁来了解三类人最该看一是天天跟 AI 编程工具打交道的开发者二是想把 AI 能力产品化的团队三是好奇“AI 到底怎么被调教得更听话”的技术爱好者。哪怕你只是想让手里的 AI 助手少犯点低级错误理解 skills 的机制也能帮上大忙。下面我就按“设计思路—核心细节—实操落地—问题排查”这条线把 skills 这套东西掰开揉碎讲清楚。2. skills 的整体设计与思路拆解2.1 为什么是“技能包”而不是“大 prompt”要理解 skills 的设计得先想明白一个根本矛盾AI 的能力是通用的但任务往往是专用的。一个通用模型什么都懂一点但真到具体场景它不知道你们团队的代码规范、不知道这个项目的目录约定、不知道某个工具的正确调用姿势。传统做法是把这些信息全塞进 system prompt 或者对话上下文里但这么做有几个硬伤。第一是上下文污染。你把十种任务的说明全塞进去AI 在干某一件具体事的时候会被无关信息干扰反而容易出错。第二是不可复用。这次对话里调教好的流程下次开新会话就没了得重新来一遍。第三是维护困难。流程一改你得去翻所有塞过这段 prompt 的地方改漏一处就出问题。skills 的设计思路正好对症下药把能力拆成独立的、自包含的模块按需加载用完即走。每个 skill 是一个文件夹里面有说明文档通常叫SKILL.md或类似名字、可能有脚本、模板、参考文件。AI 在启动时只看到每个 skill 的简短描述名字 一句话说明判断当前任务需要哪个才去读那个 skill 的完整内容。这就好比你的书架上摆了几十本书你不需要把每本书都背下来只需要知道每本书讲什么用到的时候抽出来翻。这个“渐进式披露”progressive disclosure的机制是 skills 最核心的设计。它让 AI 的上下文保持干净同时又能随时调用深度知识。热搜里find skills、skills大全、skills推荐这些词的火爆本质上就是大家在找“有哪些现成的好技能包可以装”。2.2 目录结构背后的工程考量一个标准的 skill 目录长什么样虽然不同平台细节有差异但骨架大同小异。我按最常见的约定来说my-skill/ ├── SKILL.md # 核心说明文件必须有 ├── scripts/ # 可执行脚本可选 │ └── helper.py ├── references/ # 参考资料可选 │ └── api-doc.md └── assets/ # 模板、图片等静态资源可选SKILL.md是整个 skill 的灵魂。它通常分两部分frontmatter元数据和正文指令内容。元数据里最关键的是name和description。description写得好不好直接决定 AI 能不能在正确的时机选中这个 skill。我见过太多人在这上面偷懒写一句“帮助处理文档”结果 AI 永远不知道该不该用它。正确的写法应该包含触发场景和关键词比如“当用户需要把 Markdown 转成带样式的 PDF、涉及分页和页眉页脚设置时使用”。正文部分就是给 AI 看的操作指南。这里有个反直觉的点它不是写给人类看的文档而是写给 AI 看的指令。所以语气要直接步骤要明确该用祈使句就用祈使句。你可以写“第一步检查输入文件是否存在第二步调用 scripts/convert.py 并传入路径参数”而不是“本工具可以帮助用户完成转换工作”。后者是给人看的介绍前者才是给 AI 执行的操作序列。为什么要有scripts/目录因为有些操作 AI 直接做不可靠比如精确的数值计算、复杂的文件格式转换、需要调用外部命令的任务。把这些封装成脚本AI 只需要知道“什么时候调用、传什么参数”具体执行交给确定性代码。这是把 AI 的不确定性和代码的确定性结合起来的典型思路。热搜里npx playwright install失败这种问题往往就出现在 skill 依赖外部工具的时候。2.3 加载机制AI 是怎么“学会”一个技能的理解加载机制才能理解为什么 skills 能工作。整个流程大致是这样AI 启动时系统会扫描所有已安装 skill 的元数据把name和description拼成一份清单放进上下文。这份清单很短可能就几十行。当用户提出一个任务AI 先判断这个任务跟清单里哪个描述匹配。匹配上了它才会去读取那个 skill 的SKILL.md完整内容然后按照里面的指令执行。这里有个关键设计元数据和正文是分离的。元数据常驻上下文正文按需加载。这解决了前面说的上下文污染问题。你装一百个 skill常驻的也只是那一百行描述不会把一百份完整文档全塞进去。那 AI 怎么判断匹配靠的是语义理解。所以description的措辞就极其重要。它要包含用户可能用的同义表达。比如一个做数据可视化的 skill描述里最好同时出现“图表”“可视化”“plot”“chart”“画图”这些词这样不管用户怎么说AI 都能对上号。这也是为什么skills推荐类内容里大家特别强调描述要写得“有钩子”。还有一个容易被忽略的点skill 之间可以互相引用。一个复杂的 skill 可以在正文里说“如果需要处理日期参考 date-utils skill”。这形成了一张能力网络。但引用要克制引用太多会导致加载链路过长反而拖慢响应。我的经验是单个 skill 直接引用的其他 skill 不超过三个超过就该考虑合并或者重构了。3. 核心细节解析与实操要点3.1 SKILL.md 的写法从“能跑”到“好用”写SKILL.md是 skills 开发里最见功力的地方。我踩过的坑总结下来有几个必须遵守的原则。第一描述要具体到场景不要泛泛而谈。对比一下差“帮助用户处理图片”好“当用户需要批量压缩图片、调整尺寸、或转换格式PNG/JPG/WebP时使用支持指定最大宽度和压缩质量”后者的描述里包含了动作压缩、调整、转换、对象图片、格式PNG/JPG/WebP、参数最大宽度、压缩质量。AI 看到这样的描述匹配精度会高很多。第二正文步骤要可执行避免模糊词汇。“适当地处理文件”这种话对 AI 来说等于没说。要写成“读取文件前 100 行检查是否包含 YAML frontmatter如果有则解析没有则跳过”。每一步都要有明确的判断条件和动作。第三把易错点显式写出来。AI 不会自己知道你们项目的特殊约定。比如“本项目的配置文件一律放在config/目录下不要放在根目录”这种约束必须写进 skill。我习惯在SKILL.md末尾加一个“注意事项”小节把踩过的坑都列上效果很好。第四控制篇幅。一个SKILL.md正文最好控制在 500 行以内。太长了 AI 读取慢而且容易抓不住重点。如果内容确实多把细节挪到references/目录正文里只写“详细 API 说明见 references/api-doc.md”。下面是一个简化但可用的SKILL.md示例以“Markdown 转 PDF”为例--- name: md-to-pdf description: 当用户需要将 Markdown 文件转换为带样式的 PDF涉及分页、页眉页脚、代码高亮时使用。触发词包括 markdown转pdf、md导出pdf、生成pdf报告。 --- # Markdown 转 PDF ## 使用场景 用户提供 .md 文件路径要求输出 .pdf 文件。 ## 操作步骤 1. 确认输入文件存在且扩展名为 .md 2. 检查是否安装了 pandoc 和 wkhtmltopdf未安装则提示用户 3. 调用 scripts/convert.sh传入输入路径和输出路径 4. 转换完成后验证输出文件大小大于 0 5. 向用户报告输出路径 ## 参数说明 - 默认页面尺寸 A4 - 默认边距 2cm - 代码块使用 highlight.js 高亮 ## 注意事项 - 如果 Markdown 里有本地图片路径必须是绝对路径否则 PDF 里图片会丢失 - 中文字体需要系统已安装否则会显示方块 - 转换大文件超过 50 页时耗时较长需提前告知用户这份文件不长但信息密度很高。AI 读完就知道该干什么、怎么干、注意什么。3.2 脚本与资源的组织让确定性接管不确定性scripts/目录是 skills 里最容易被低估的部分。很多人觉得 AI 什么都能干不需要脚本。但实测下来凡是涉及精确计算、格式转换、外部命令调用的交给脚本比交给 AI 靠谱得多。举个例子你要做一个“生成项目周报”的 skill。如果让 AI 自己去算本周的代码提交次数、统计各文件改动行数它可能会算错尤其是数据量大的时候。但如果写一个scripts/collect_stats.py用 git 命令把数据拉出来AI 只负责把结果组织成周报文字准确率就上去了。脚本的调用方式要在SKILL.md里写清楚。我建议统一约定脚本放在scripts/下用相对路径调用参数用命令行传入。比如python scripts/collect_stats.py --since 7 days ago --format jsonAI 看到这条指令就知道该怎么执行。这里有个细节脚本的输出格式最好是结构化的JSON、CSV而不是一大段自然语言。结构化数据 AI 更容易解析和二次处理。references/目录放的是“查阅型”资料比如 API 文档、字段说明、历史案例。这些内容 AI 不一定每次都读但需要的时候能查到。assets/放模板文件、图片、字体等静态资源。这两个目录的存在让 skill 从“一段说明”升级成“一个完整的知识包”。3.3 安装与分发skills 怎么进到你的环境里热搜里claude 国内安装skills 官方市场、skills下载平台有哪些、skills安装包下载这些词说明大家最关心的还是“怎么装”。不同平台的安装方式不一样但核心逻辑相通把 skill 目录放到 AI 工具能扫描到的位置。以常见的约定来说通常有一个全局 skills 目录比如~/.agent/skills/或者项目级的.skills/目录。你把 skill 文件夹复制进去重启 AI 工具或者触发一次重新扫描它就能识别了。有些平台支持通过命令行安装类似npx skills install skill-name这种形式。热搜里npx频繁出现就是因为很多工具链用 npx 来做包管理和命令执行。这里要提醒一个坑目录名和SKILL.md里的name最好保持一致。我遇到过目录叫pdf-tool但 name 写的是md-to-pdf结果 AI 在清单里看到的名字和实际目录对不上加载时找不到文件。这种低级错误排查起来很费时间。分发方面目前主要有几种渠道官方市场平台方审核过的 skill 集合、社区仓库GitHub 上的开源 skill 合集、个人分享博客、群聊里传的单个 skill。github skills这个热搜词说明 GitHub 是主要的集散地。我的建议是优先用官方市场或高星社区仓库的 skill因为经过多人验证坑少。个人分享的 skill 要自己审一遍SKILL.md和脚本尤其是脚本别直接跑来源不明的代码。4. 实操过程与核心环节实现4.1 从零开发一个 skill 的完整流程光说理论不够我拿一个真实场景走一遍开发一个“自动生成 Git 提交信息”的 skill。这个需求很常见热搜里codex好用的skills、skills开发都跟这类实用技能相关。第一步明确边界。这个 skill 要做什么读取当前暂存区的改动生成一条符合 Conventional Commits 规范的提交信息。不做什么不执行git commit只生成信息让用户确认。边界清晰skill 才不会越权。第二步设计目录结构。git-commit-msg/ ├── SKILL.md ├── scripts/ │ └── get_diff.sh └── references/ └── commit-convention.md第三步写get_diff.sh。这个脚本负责把暂存区的 diff 拉出来控制输出长度避免超长 diff 撑爆上下文。#!/bin/bash # 获取暂存区 diff限制每个文件最多 200 行 git diff --cached --stat echo ---DIFF--- git diff --cached | head -n 500为什么要限制行数因为一个大的重构可能产生几千行 diff全塞给 AI 既慢又贵而且 AI 也抓不住重点。限制在 500 行以内配合--stat的文件概览足够 AI 判断改了什么。第四步写references/commit-convention.md。把 Conventional Commits 的规范放进去feat、fix、docs、style、refactor、test、chore 各是什么意思格式是什么样。这样 AI 生成的时候有据可依。第五步写SKILL.md。--- name: git-commit-msg description: 当用户需要根据暂存区改动生成 Git 提交信息、涉及 Conventional Commits 规范、需要分析 diff 内容时使用。触发词包括 生成提交信息、写commit、commit message。 --- # Git 提交信息生成 ## 操作步骤 1. 运行 scripts/get_diff.sh 获取暂存区改动 2. 如果输出为空提示用户没有暂存改动结束 3. 阅读 references/commit-convention.md 了解规范 4. 分析 diff判断改动类型feat/fix/docs等 5. 生成一条不超过 72 字符的标题必要时补充正文 6. 把生成的信息展示给用户等待确认 ## 注意事项 - 不要自动执行 git commit - 标题用英文正文可用中文 - 如果改动涉及多个类型选最主要的那个 - 破坏性变更要在正文里标注 BREAKING CHANGE第六步测试。把 skill 放进 skills 目录重启工具然后在一个有暂存改动的仓库里问 AI“帮我写个 commit message”。观察它是否选中了这个 skill、是否正确调用了脚本、生成的信息是否合规。测试是agent skills测试这个热搜词的核心不测就上线坑的是自己。4.2 参数选择与性能权衡skills 开发里有几个参数需要权衡我列个表说明。参数/选项常见取值影响我的建议描述长度20-100 字太短匹配不准太长占上下文控制在 50 字左右含触发词正文行数100-500 行太长加载慢太短信息不足300 行以内细节外置脚本输出全量/截断全量准确但慢截断快但可能丢信息按任务定diff 类截断到 500 行引用深度0-3 层太深加载链长响应慢不超过 2 层资源文件按需多了占空间少了不够用只放真正会被读取的这些数字不是拍脑袋来的是我在多个项目里试出来的经验值。比如描述长度我试过写 10 个字的AI 经常匹配不上写 200 字的又发现清单太长影响其他 skill 的匹配。50 字左右是个甜点区。4.3 一个进阶技巧让 skill 自我进化skills 有个很有意思的玩法让 AI 在使用的过程中把新的经验写回 skill。比如一个代码审查 skill每次审查完如果发现了新的常见问题模式就把它追加到SKILL.md的注意事项里。这样 skill 会越用越聪明。实现方式是在SKILL.md里加一条指令“如果本次审查发现了之前未记录的代码问题模式将其追加到本文件的‘已知问题模式’小节”。当然这需要 AI 有写文件的权限而且要小心别让它乱改。我的做法是让它写到一个单独的learnings.md里定期人工审核后再合并进主文件。这样既享受了自我进化的好处又不会失控。热搜里superpower skills、今天学会了skills打开新世界这种表达反映的就是这种“skill 越用越强”的体验。当你有一套精心维护的 skill 库AI 在你熟悉的领域里表现会明显不一样。5. 常见问题与排查技巧实录5.1 skill 不被触发怎么办这是最高频的问题。你装了个 skill问 AI 相关任务它却不用。排查思路按顺序来先查描述。十有八九是description写得太泛或者缺触发词。把用户可能用的说法都加进去。比如一个做“分镜”的 skill热搜里有分镜skills下载说明用户会用“分镜”这个词那描述里就必须有“分镜”不能只写“storyboard”。再查目录位置。skill 是不是放对了地方有些工具要求放在特定目录放错了扫描不到。检查一下工具的文档确认 skills 目录路径。然后查元数据格式。frontmatter 的格式对不对name和description字段名有没有拼错YAML 对缩进敏感一个空格错了就解析失败。我建议用工具自带的校验命令过一遍。最后查冲突。是不是有另一个 skill 的描述跟它很像AI 选了那个如果是把两个 skill 的描述差异化或者合并成一个。5.2 脚本执行失败的排查npx playwright install失败这类问题本质是 skill 依赖的外部环境没配好。排查步骤手动跑一遍脚本。脱离 AI直接在终端执行看报什么错。这一步能排除 80% 的问题。检查依赖是否安装。脚本里用到的命令python、node、pandoc 等在系统里有没有版本对不对检查路径。脚本里用的是相对路径还是绝对路径AI 调用时的工作目录可能跟你手动跑时不一样。建议脚本内部统一用相对于脚本自身位置的路径。检查权限。脚本有没有执行权限chmod x加一下。检查输出。脚本是不是把错误信息输出到了 stderr而 AI 只读了 stdout在SKILL.md里注明“如果脚本返回非零退出码读取 stderr 内容并报告给用户”。我把常见问题整理成速查表现象可能原因解决方向skill 不被触发描述缺触发词补充同义表达和场景词加载报错frontmatter 格式错用 YAML 校验工具检查脚本找不到路径写错改用相对脚本自身的路径脚本报权限错没执行权限chmod x输出乱码编码不一致统一用 UTF-8响应很慢正文太长或引用太深精简正文减少引用层级结果不稳定依赖 AI 做精确计算把计算挪到脚本里5.3 几个只有踩过才知道的坑坑一描述里的关键词别堆砌。有人为了匹配把几十个词塞进 description结果 AI 反而困惑了。描述要像人话自然包含关键场景词就行。坑二别在 skill 里写死绝对路径。你的机器路径跟别人的不一样写死了 skill 就没法分享。用相对路径或者环境变量。坑三脚本要幂等。同一个脚本被调用两次结果应该一致不能产生副作用。比如“创建目录”要先判断存在不存在“追加内容”要小心重复追加。坑四给 AI 的指令要防呆。AI 有时候会“过度发挥”。在SKILL.md里明确写“不要做 X”比事后纠正有效得多。比如“不要自动提交代码”“不要删除任何文件”。坑五版本管理。skill 也是代码要进 Git。改了什么、为什么改都记清楚。团队协作时skill 的变更要像代码一样走 review。6. 关于 skills 生态的一些个人观察skills大全、skills推荐、find skills这些词的热度说明 skills 已经从“少数人的技巧”变成了“有生态的东西”。有生态就有分工有人专门开发 skill有人专门做 skill 市场有人专门写 skill 评测。这个趋势跟当年 npm 包、VS Code 插件的发展路径很像。但 skills 跟它们有个本质区别skill 的“消费者”是 AI不是人。这意味着 skill 的质量标准不一样。一个 npm 包只要 API 好用就行但一个 skill 还要考虑“AI 能不能理解”“AI 会不会误用”“AI 读了之后行为是否可预测”。这给 skill 开发者提出了新要求你得同时懂业务、懂 AI 的行为模式、还得懂怎么写指令。我个人的判断是未来 skills 会往两个方向分化。一个是通用基础 skill比如文件处理、格式转换、数据统计这些会被平台内置或者形成事实标准。另一个是垂直领域 skill比如法律文书、医疗记录、特定行业的代码规范这些需要领域专家来写价值也更高。热搜里codex写论文的skills、自动挖洞skills就是垂直化的例子。对普通开发者来说现在是个不错的入场时机。生态还在早期好的 skill 不多你写一个解决实际痛点的 skill很容易被看到。而且 skills 开发的门槛不高不需要复杂的编程核心是把流程想清楚、把指令写明白。我见过不少非科班出身的人因为对自己领域的工作流特别熟写出来的 skill 比程序员写的还好用。最后分享一个我自己的习惯我会给每个常用 skill 建一个CHANGELOG.md记录每次修改的原因和效果。比如“2024-06-01在描述里加了‘批量’这个词触发率明显上升”。这些记录积累下来就是一套属于自己的 skill 开发方法论。skills 这东西说到底拼的不是技术是对任务的理解深度和把理解转化成清晰指令的能力。 
长河君 · 2026/10/29 15:36:28 · 阅读 1.2k AI Agent Skills 完全指南：从设计原理到开发实战
1. 从“skills”这个热词说起它到底是什么最近半年不管是在技术社区、开发者群聊还是各种工具分享帖里“skills”这个词出现的频率高得离谱。你随便翻翻热搜榜能看到Agent Skills、codex skills、claude agent skills、skills开发、skills推荐这些词扎堆冒出来。很多人第一次看到会懵这说的是人的技能还是某个新框架其实都不是或者说不完全是。我先把结论摆在前面这里说的skills指的是一套围绕 AI Agent智能体构建的可插拔能力模块。你可以把它理解成给 AI 助手装的“技能包”——每个 skill 就是一份结构化的说明文档加配套资源告诉 AI 在遇到某类任务时该怎么做、用哪些工具、遵循什么流程。它不是一个编程库也不是一个 API而更像是一份写给 AI 看的“操作手册 工具箱说明书”。这个概念的走红跟几个主流 AI 编程工具的推动直接相关。Claude 的 Agent Skills、Codex 的 skills 机制、以及 Google Cloud 那边对 agent 能力的标准化尝试让“给 AI 装技能”从一种零散的 prompt 技巧变成了一套有目录结构、有元数据、有加载规则的工程化实践。热搜里那个claude agent skills: a first principles deep dive就说明已经有人开始从第一性原理去拆解它了。那它到底解决什么问题说白了就是让 AI 在特定领域里表现得更专业、更稳定、更可复用。你不可能每次都把一整套复杂流程塞进对话里那样既啰嗦又容易漏。skills 的思路是把“怎么做某件事”的知识固化下来需要的时候按需加载。比如你要 AI 帮你写论文就加载一个论文写作 skill要它做前端组件就加载一个前端开发 skill要它跑自动化测试就加载一个测试 skill。适合谁来了解三类人最该看一是天天跟 AI 编程工具打交道的开发者二是想把 AI 能力产品化的团队三是好奇“AI 到底怎么被调教得更听话”的技术爱好者。哪怕你只是想让手里的 AI 助手少犯点低级错误理解 skills 的机制也能帮上大忙。下面我就按“设计思路—核心细节—实操落地—问题排查”这条线把 skills 这套东西掰开揉碎讲清楚。2. skills 的整体设计与思路拆解2.1 为什么是“技能包”而不是“大 prompt”要理解 skills 的设计得先想明白一个根本矛盾AI 的能力是通用的但任务往往是专用的。一个通用模型什么都懂一点但真到具体场景它不知道你们团队的代码规范、不知道这个项目的目录约定、不知道某个工具的正确调用姿势。传统做法是把这些信息全塞进 system prompt 或者对话上下文里但这么做有几个硬伤。第一是上下文污染。你把十种任务的说明全塞进去AI 在干某一件具体事的时候会被无关信息干扰反而容易出错。第二是不可复用。这次对话里调教好的流程下次开新会话就没了得重新来一遍。第三是维护困难。流程一改你得去翻所有塞过这段 prompt 的地方改漏一处就出问题。skills 的设计思路正好对症下药把能力拆成独立的、自包含的模块按需加载用完即走。每个 skill 是一个文件夹里面有说明文档通常叫SKILL.md或类似名字、可能有脚本、模板、参考文件。AI 在启动时只看到每个 skill 的简短描述名字 一句话说明判断当前任务需要哪个才去读那个 skill 的完整内容。这就好比你的书架上摆了几十本书你不需要把每本书都背下来只需要知道每本书讲什么用到的时候抽出来翻。这个“渐进式披露”progressive disclosure的机制是 skills 最核心的设计。它让 AI 的上下文保持干净同时又能随时调用深度知识。热搜里find skills、skills大全、skills推荐这些词的火爆本质上就是大家在找“有哪些现成的好技能包可以装”。2.2 目录结构背后的工程考量一个标准的 skill 目录长什么样虽然不同平台细节有差异但骨架大同小异。我按最常见的约定来说my-skill/ ├── SKILL.md # 核心说明文件必须有 ├── scripts/ # 可执行脚本可选 │ └── helper.py ├── references/ # 参考资料可选 │ └── api-doc.md └── assets/ # 模板、图片等静态资源可选SKILL.md是整个 skill 的灵魂。它通常分两部分frontmatter元数据和正文指令内容。元数据里最关键的是name和description。description写得好不好直接决定 AI 能不能在正确的时机选中这个 skill。我见过太多人在这上面偷懒写一句“帮助处理文档”结果 AI 永远不知道该不该用它。正确的写法应该包含触发场景和关键词比如“当用户需要把 Markdown 转成带样式的 PDF、涉及分页和页眉页脚设置时使用”。正文部分就是给 AI 看的操作指南。这里有个反直觉的点它不是写给人类看的文档而是写给 AI 看的指令。所以语气要直接步骤要明确该用祈使句就用祈使句。你可以写“第一步检查输入文件是否存在第二步调用 scripts/convert.py 并传入路径参数”而不是“本工具可以帮助用户完成转换工作”。后者是给人看的介绍前者才是给 AI 执行的操作序列。为什么要有scripts/目录因为有些操作 AI 直接做不可靠比如精确的数值计算、复杂的文件格式转换、需要调用外部命令的任务。把这些封装成脚本AI 只需要知道“什么时候调用、传什么参数”具体执行交给确定性代码。这是把 AI 的不确定性和代码的确定性结合起来的典型思路。热搜里npx playwright install失败这种问题往往就出现在 skill 依赖外部工具的时候。2.3 加载机制AI 是怎么“学会”一个技能的理解加载机制才能理解为什么 skills 能工作。整个流程大致是这样AI 启动时系统会扫描所有已安装 skill 的元数据把name和description拼成一份清单放进上下文。这份清单很短可能就几十行。当用户提出一个任务AI 先判断这个任务跟清单里哪个描述匹配。匹配上了它才会去读取那个 skill 的SKILL.md完整内容然后按照里面的指令执行。这里有个关键设计元数据和正文是分离的。元数据常驻上下文正文按需加载。这解决了前面说的上下文污染问题。你装一百个 skill常驻的也只是那一百行描述不会把一百份完整文档全塞进去。那 AI 怎么判断匹配靠的是语义理解。所以description的措辞就极其重要。它要包含用户可能用的同义表达。比如一个做数据可视化的 skill描述里最好同时出现“图表”“可视化”“plot”“chart”“画图”这些词这样不管用户怎么说AI 都能对上号。这也是为什么skills推荐类内容里大家特别强调描述要写得“有钩子”。还有一个容易被忽略的点skill 之间可以互相引用。一个复杂的 skill 可以在正文里说“如果需要处理日期参考 date-utils skill”。这形成了一张能力网络。但引用要克制引用太多会导致加载链路过长反而拖慢响应。我的经验是单个 skill 直接引用的其他 skill 不超过三个超过就该考虑合并或者重构了。3. 核心细节解析与实操要点3.1 SKILL.md 的写法从“能跑”到“好用”写SKILL.md是 skills 开发里最见功力的地方。我踩过的坑总结下来有几个必须遵守的原则。第一描述要具体到场景不要泛泛而谈。对比一下差“帮助用户处理图片”好“当用户需要批量压缩图片、调整尺寸、或转换格式PNG/JPG/WebP时使用支持指定最大宽度和压缩质量”后者的描述里包含了动作压缩、调整、转换、对象图片、格式PNG/JPG/WebP、参数最大宽度、压缩质量。AI 看到这样的描述匹配精度会高很多。第二正文步骤要可执行避免模糊词汇。“适当地处理文件”这种话对 AI 来说等于没说。要写成“读取文件前 100 行检查是否包含 YAML frontmatter如果有则解析没有则跳过”。每一步都要有明确的判断条件和动作。第三把易错点显式写出来。AI 不会自己知道你们项目的特殊约定。比如“本项目的配置文件一律放在config/目录下不要放在根目录”这种约束必须写进 skill。我习惯在SKILL.md末尾加一个“注意事项”小节把踩过的坑都列上效果很好。第四控制篇幅。一个SKILL.md正文最好控制在 500 行以内。太长了 AI 读取慢而且容易抓不住重点。如果内容确实多把细节挪到references/目录正文里只写“详细 API 说明见 references/api-doc.md”。下面是一个简化但可用的SKILL.md示例以“Markdown 转 PDF”为例--- name: md-to-pdf description: 当用户需要将 Markdown 文件转换为带样式的 PDF涉及分页、页眉页脚、代码高亮时使用。触发词包括 markdown转pdf、md导出pdf、生成pdf报告。 --- # Markdown 转 PDF ## 使用场景 用户提供 .md 文件路径要求输出 .pdf 文件。 ## 操作步骤 1. 确认输入文件存在且扩展名为 .md 2. 检查是否安装了 pandoc 和 wkhtmltopdf未安装则提示用户 3. 调用 scripts/convert.sh传入输入路径和输出路径 4. 转换完成后验证输出文件大小大于 0 5. 向用户报告输出路径 ## 参数说明 - 默认页面尺寸 A4 - 默认边距 2cm - 代码块使用 highlight.js 高亮 ## 注意事项 - 如果 Markdown 里有本地图片路径必须是绝对路径否则 PDF 里图片会丢失 - 中文字体需要系统已安装否则会显示方块 - 转换大文件超过 50 页时耗时较长需提前告知用户这份文件不长但信息密度很高。AI 读完就知道该干什么、怎么干、注意什么。3.2 脚本与资源的组织让确定性接管不确定性scripts/目录是 skills 里最容易被低估的部分。很多人觉得 AI 什么都能干不需要脚本。但实测下来凡是涉及精确计算、格式转换、外部命令调用的交给脚本比交给 AI 靠谱得多。举个例子你要做一个“生成项目周报”的 skill。如果让 AI 自己去算本周的代码提交次数、统计各文件改动行数它可能会算错尤其是数据量大的时候。但如果写一个scripts/collect_stats.py用 git 命令把数据拉出来AI 只负责把结果组织成周报文字准确率就上去了。脚本的调用方式要在SKILL.md里写清楚。我建议统一约定脚本放在scripts/下用相对路径调用参数用命令行传入。比如python scripts/collect_stats.py --since 7 days ago --format jsonAI 看到这条指令就知道该怎么执行。这里有个细节脚本的输出格式最好是结构化的JSON、CSV而不是一大段自然语言。结构化数据 AI 更容易解析和二次处理。references/目录放的是“查阅型”资料比如 API 文档、字段说明、历史案例。这些内容 AI 不一定每次都读但需要的时候能查到。assets/放模板文件、图片、字体等静态资源。这两个目录的存在让 skill 从“一段说明”升级成“一个完整的知识包”。3.3 安装与分发skills 怎么进到你的环境里热搜里claude 国内安装skills 官方市场、skills下载平台有哪些、skills安装包下载这些词说明大家最关心的还是“怎么装”。不同平台的安装方式不一样但核心逻辑相通把 skill 目录放到 AI 工具能扫描到的位置。以常见的约定来说通常有一个全局 skills 目录比如~/.agent/skills/或者项目级的.skills/目录。你把 skill 文件夹复制进去重启 AI 工具或者触发一次重新扫描它就能识别了。有些平台支持通过命令行安装类似npx skills install skill-name这种形式。热搜里npx频繁出现就是因为很多工具链用 npx 来做包管理和命令执行。这里要提醒一个坑目录名和SKILL.md里的name最好保持一致。我遇到过目录叫pdf-tool但 name 写的是md-to-pdf结果 AI 在清单里看到的名字和实际目录对不上加载时找不到文件。这种低级错误排查起来很费时间。分发方面目前主要有几种渠道官方市场平台方审核过的 skill 集合、社区仓库GitHub 上的开源 skill 合集、个人分享博客、群聊里传的单个 skill。github skills这个热搜词说明 GitHub 是主要的集散地。我的建议是优先用官方市场或高星社区仓库的 skill因为经过多人验证坑少。个人分享的 skill 要自己审一遍SKILL.md和脚本尤其是脚本别直接跑来源不明的代码。4. 实操过程与核心环节实现4.1 从零开发一个 skill 的完整流程光说理论不够我拿一个真实场景走一遍开发一个“自动生成 Git 提交信息”的 skill。这个需求很常见热搜里codex好用的skills、skills开发都跟这类实用技能相关。第一步明确边界。这个 skill 要做什么读取当前暂存区的改动生成一条符合 Conventional Commits 规范的提交信息。不做什么不执行git commit只生成信息让用户确认。边界清晰skill 才不会越权。第二步设计目录结构。git-commit-msg/ ├── SKILL.md ├── scripts/ │ └── get_diff.sh └── references/ └── commit-convention.md第三步写get_diff.sh。这个脚本负责把暂存区的 diff 拉出来控制输出长度避免超长 diff 撑爆上下文。#!/bin/bash # 获取暂存区 diff限制每个文件最多 200 行 git diff --cached --stat echo ---DIFF--- git diff --cached | head -n 500为什么要限制行数因为一个大的重构可能产生几千行 diff全塞给 AI 既慢又贵而且 AI 也抓不住重点。限制在 500 行以内配合--stat的文件概览足够 AI 判断改了什么。第四步写references/commit-convention.md。把 Conventional Commits 的规范放进去feat、fix、docs、style、refactor、test、chore 各是什么意思格式是什么样。这样 AI 生成的时候有据可依。第五步写SKILL.md。--- name: git-commit-msg description: 当用户需要根据暂存区改动生成 Git 提交信息、涉及 Conventional Commits 规范、需要分析 diff 内容时使用。触发词包括 生成提交信息、写commit、commit message。 --- # Git 提交信息生成 ## 操作步骤 1. 运行 scripts/get_diff.sh 获取暂存区改动 2. 如果输出为空提示用户没有暂存改动结束 3. 阅读 references/commit-convention.md 了解规范 4. 分析 diff判断改动类型feat/fix/docs等 5. 生成一条不超过 72 字符的标题必要时补充正文 6. 把生成的信息展示给用户等待确认 ## 注意事项 - 不要自动执行 git commit - 标题用英文正文可用中文 - 如果改动涉及多个类型选最主要的那个 - 破坏性变更要在正文里标注 BREAKING CHANGE第六步测试。把 skill 放进 skills 目录重启工具然后在一个有暂存改动的仓库里问 AI“帮我写个 commit message”。观察它是否选中了这个 skill、是否正确调用了脚本、生成的信息是否合规。测试是agent skills测试这个热搜词的核心不测就上线坑的是自己。4.2 参数选择与性能权衡skills 开发里有几个参数需要权衡我列个表说明。参数/选项常见取值影响我的建议描述长度20-100 字太短匹配不准太长占上下文控制在 50 字左右含触发词正文行数100-500 行太长加载慢太短信息不足300 行以内细节外置脚本输出全量/截断全量准确但慢截断快但可能丢信息按任务定diff 类截断到 500 行引用深度0-3 层太深加载链长响应慢不超过 2 层资源文件按需多了占空间少了不够用只放真正会被读取的这些数字不是拍脑袋来的是我在多个项目里试出来的经验值。比如描述长度我试过写 10 个字的AI 经常匹配不上写 200 字的又发现清单太长影响其他 skill 的匹配。50 字左右是个甜点区。4.3 一个进阶技巧让 skill 自我进化skills 有个很有意思的玩法让 AI 在使用的过程中把新的经验写回 skill。比如一个代码审查 skill每次审查完如果发现了新的常见问题模式就把它追加到SKILL.md的注意事项里。这样 skill 会越用越聪明。实现方式是在SKILL.md里加一条指令“如果本次审查发现了之前未记录的代码问题模式将其追加到本文件的‘已知问题模式’小节”。当然这需要 AI 有写文件的权限而且要小心别让它乱改。我的做法是让它写到一个单独的learnings.md里定期人工审核后再合并进主文件。这样既享受了自我进化的好处又不会失控。热搜里superpower skills、今天学会了skills打开新世界这种表达反映的就是这种“skill 越用越强”的体验。当你有一套精心维护的 skill 库AI 在你熟悉的领域里表现会明显不一样。5. 常见问题与排查技巧实录5.1 skill 不被触发怎么办这是最高频的问题。你装了个 skill问 AI 相关任务它却不用。排查思路按顺序来先查描述。十有八九是description写得太泛或者缺触发词。把用户可能用的说法都加进去。比如一个做“分镜”的 skill热搜里有分镜skills下载说明用户会用“分镜”这个词那描述里就必须有“分镜”不能只写“storyboard”。再查目录位置。skill 是不是放对了地方有些工具要求放在特定目录放错了扫描不到。检查一下工具的文档确认 skills 目录路径。然后查元数据格式。frontmatter 的格式对不对name和description字段名有没有拼错YAML 对缩进敏感一个空格错了就解析失败。我建议用工具自带的校验命令过一遍。最后查冲突。是不是有另一个 skill 的描述跟它很像AI 选了那个如果是把两个 skill 的描述差异化或者合并成一个。5.2 脚本执行失败的排查npx playwright install失败这类问题本质是 skill 依赖的外部环境没配好。排查步骤手动跑一遍脚本。脱离 AI直接在终端执行看报什么错。这一步能排除 80% 的问题。检查依赖是否安装。脚本里用到的命令python、node、pandoc 等在系统里有没有版本对不对检查路径。脚本里用的是相对路径还是绝对路径AI 调用时的工作目录可能跟你手动跑时不一样。建议脚本内部统一用相对于脚本自身位置的路径。检查权限。脚本有没有执行权限chmod x加一下。检查输出。脚本是不是把错误信息输出到了 stderr而 AI 只读了 stdout在SKILL.md里注明“如果脚本返回非零退出码读取 stderr 内容并报告给用户”。我把常见问题整理成速查表现象可能原因解决方向skill 不被触发描述缺触发词补充同义表达和场景词加载报错frontmatter 格式错用 YAML 校验工具检查脚本找不到路径写错改用相对脚本自身的路径脚本报权限错没执行权限chmod x输出乱码编码不一致统一用 UTF-8响应很慢正文太长或引用太深精简正文减少引用层级结果不稳定依赖 AI 做精确计算把计算挪到脚本里5.3 几个只有踩过才知道的坑坑一描述里的关键词别堆砌。有人为了匹配把几十个词塞进 description结果 AI 反而困惑了。描述要像人话自然包含关键场景词就行。坑二别在 skill 里写死绝对路径。你的机器路径跟别人的不一样写死了 skill 就没法分享。用相对路径或者环境变量。坑三脚本要幂等。同一个脚本被调用两次结果应该一致不能产生副作用。比如“创建目录”要先判断存在不存在“追加内容”要小心重复追加。坑四给 AI 的指令要防呆。AI 有时候会“过度发挥”。在SKILL.md里明确写“不要做 X”比事后纠正有效得多。比如“不要自动提交代码”“不要删除任何文件”。坑五版本管理。skill 也是代码要进 Git。改了什么、为什么改都记清楚。团队协作时skill 的变更要像代码一样走 review。6. 关于 skills 生态的一些个人观察skills大全、skills推荐、find skills这些词的热度说明 skills 已经从“少数人的技巧”变成了“有生态的东西”。有生态就有分工有人专门开发 skill有人专门做 skill 市场有人专门写 skill 评测。这个趋势跟当年 npm 包、VS Code 插件的发展路径很像。但 skills 跟它们有个本质区别skill 的“消费者”是 AI不是人。这意味着 skill 的质量标准不一样。一个 npm 包只要 API 好用就行但一个 skill 还要考虑“AI 能不能理解”“AI 会不会误用”“AI 读了之后行为是否可预测”。这给 skill 开发者提出了新要求你得同时懂业务、懂 AI 的行为模式、还得懂怎么写指令。我个人的判断是未来 skills 会往两个方向分化。一个是通用基础 skill比如文件处理、格式转换、数据统计这些会被平台内置或者形成事实标准。另一个是垂直领域 skill比如法律文书、医疗记录、特定行业的代码规范这些需要领域专家来写价值也更高。热搜里codex写论文的skills、自动挖洞skills就是垂直化的例子。对普通开发者来说现在是个不错的入场时机。生态还在早期好的 skill 不多你写一个解决实际痛点的 skill很容易被看到。而且 skills 开发的门槛不高不需要复杂的编程核心是把流程想清楚、把指令写明白。我见过不少非科班出身的人因为对自己领域的工作流特别熟写出来的 skill 比程序员写的还好用。最后分享一个我自己的习惯我会给每个常用 skill 建一个CHANGELOG.md记录每次修改的原因和效果。比如“2024-06-01在描述里加了‘批量’这个词触发率明显上升”。这些记录积累下来就是一套属于自己的 skill 开发方法论。skills 这东西说到底拼的不是技术是对任务的理解深度和把理解转化成清晰指令的能力。