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 这东西，说到底拼的不是技术，是对任务的理解深度和把理解转化成清晰指令的能力。
