企业官网建设流程全解析

先说个有意思的现象：过去半年里，"skills"这个单词在 AI 编程圈子里出现的频率，已经快要赶上"prompt"了。如果你最近刷 GitHub、逛 X（推特）或者混 V2EX，一定见过类似这样的帖子：《Claude Agent Skills: A First Principles Deep Dive》《Codex 好用的 Skills 推荐》《学会了 Skills，打开新世界》……说实话，"Skills"这个说法本身不是什么新技术，GPT 的 Custom Instructions、Claude 的 System Prompt、各种 Agent 的 Tool Calling，本质上都是在做同一件事——给模型"说明书"。但为什么偏偏"Skills"这个概念今年火起来了？它到底和之前那些方案有什么区别？作为一个从 2015 年就开始折腾智能客服机器人、这几年又一直在搞 AI Agent 的老兵，我想用一篇动手实践为主的文章，把这件事彻底讲透。

这篇文章不会堆概念。我会从"Skills 到底是什么"讲起，然后拆解它的文件结构、编写规范、部署方式，最后用几个能直接上手的案例带大家走一遍完整流程。重点是——我会把我踩过的坑、琢磨出来的捷径、还有那些文档里不会明确写出来的细节，一并交代清楚。适合三类人看：一是已经在用 Claude Code / Codex 但总觉得"能力不够"的开发者，二是想给团队内部 Agent 快速统一技能规范的工程负责人，三是纯粹好奇"AI Agent 的能力边界到底怎么扩展"的技术爱好者。无论你是哪一类，读完这篇文章，你应该能自己动手写一个像样的 Skill，而不是只会复制粘贴别人做好的。

1. 概念拆解："Skills"到底在解决什么问题

1.1 为什么叫"Skills"而不叫"Plugins"或"Tools"

最早做 Agent 能力扩展的时候，大家习惯说"插件"或者"工具"。MCP（Model Context Protocol）火起来之后，又开始流行"连一个 MCP Server"。这些方案都有各自的道理，但也各有各的别扭：插件意味着"一段写死的代码"，你得维护接口、处理依赖、考虑版本兼容；MCP Server 更灵活，但光是起服务、配鉴权、调试连通性这一套，就能劝退一大批非后端出身的人。

Skills 的定位很微妙——它是一套"以 Markdown 文档为中心"的能力封装。核心只有一个文件：SKILL.md。里面写清楚这个 Skill 能做什么、在什么场景下触发、需要模型的哪些行为、有哪些注意事项。就这么简单。模型在运行的时候会读取这份文档，然后按照文档里的指引调整自己的行为方式。没有繁重的代码编译，没有独立的进程，没有任何网络服务。本质上，Skills 是在**"给模型写说明书"这个维度上做到极致**，而不是**"给模型接外部工具"**。

这就不难理解为什么 2025 年这个方案突然冒头了——因为 Claude 的上下文窗口已经足够大，模型本身的代码能力也已经足够强。与其费劲接一堆外部工具，不如把"怎么做这个领域的事情"直接写进文档里喂给模型。人怎么带新人？给一份新人手册。模型怎么学会一个新技能？给一份 SKILL.md。逻辑一模一样。

1.2 一套 Skills 体系的适用范围

Skills 不是只属于某一家公司的封闭协议。实际上，"用 Markdown 文档描述能力边界"这个思路是非常通用且开放的。我做过的实验里，同样一份 SKILL.md，在 Claude Code、Codex、开源的 OpenHands、甚至自己写的 Agent 框架里，都能直接复用。区别只在于各家对"如何引入这份文档"的路径命名不同——有的叫.claude/skills/，有的叫.codex/，但文档内容本身是可以互通的。

这给了整个开发者社区一个很大的想象空间：那就是"技能"本身可以脱离某个具体工具而存在。GitHub 上已经出现了大量 Skills 仓库，分类整理着前端开发、论文写作、分镜脚本、爬虫、安卓逆向脱壳、安全测试等各种各样的技能包。你要做的，只是找到一个对口的技能包，下载下来，放到你的 Agent 配置目录里。想象一下以前装软件的体验——只不过这次装的不是软件，装的是"模型的一项新能力"。

这里我补充一个个人观点：Skills 尤其适合那些"模型本来就会，但总是做不好"的任务。比如写分镜脚本，模型知道分镜是什么，但往往写出来缺乏镜头感；比如写论文，模型知道学术论文的结构，但总写得像高中生作文。这些任务的特点就是：能力模型已经具备，缺的只是"高手的心法"。而 SKILL.md 恰好就是一个可以无限堆心法的地方。

1.3 Skills、MCP 和系统提示词：三者的核心差异对比

很多人会把 Skills 和 MCP 混为一谈，这是最容易被绕晕的地方。我做了一张对比表，把三条路线放在一起看，差异就一目了然了：

从这张表可以看出来，这三者并不是互斥关系，而是在不同层面做事情。我目前用得比较顺手的一套组合是：系统提示词定人设和基础规则，Skills 定义不同任务下的最佳实践，需要外部数据的时候再按需接一个 MCP Server。各管一摊，互不冲突。

很多人会问：既然系统提示词也能干活，为什么还要多一层 Skills？答案在于"模块化"和"按需加载"。如果你把几十个技能的说明书全塞进系统提示词里，每次都全部读取，一是浪费 Token，二是会让模型注意力涣散。Skills 则能做到"平时不占窗口，用的时候才会被检索到并加载"。

2. 深入解析：SKILL.md 是怎么做到"给模型写心法"的

2.1 一份标准 SKILL.md 的文件结构与分层逻辑

虽然各家平台对 Skills 的目录位置有不同要求，但SKILL.md的核心结构基本是一致的。我以自己写过的、也是目前社区里接受度比较高的格式为例，拆解一份合格技能文档应有的骨架：

Frontmatter 元信息区。YAML 格式，写清楚技能名称、描述、适用模型、触发关键词。这一段非常重要，因为 Agent 在判断"当前任务要不要加载这个技能"时，靠的就是这一段描述与用户请求的语义相似度。关键词写得太窄，技能永远不会被触发；写得太宽，每个任务都会优先加载它，反而拖慢响应。

触发条件与禁用条件。明确写清楚"什么时候用"和"什么时候不要用"。这里有个很容易被忽略的细节：好的 SKILL.md 必须写禁用条件。例如一个"前端代码审查"技能，如果用户只是问"什么是 React"，就不该触发；如果用户说"帮我看看这个组件有没有内存泄漏"，就一定要触发。模型对边界越清楚，行为就越可靠。

核心执行步骤。这是整份文档的灵魂，把任务的执行流程、分析思路、判断标准逐步写清楚。要具体到"模型每一步应该做什么、做到什么程度算合格"。比如写代码审查技能，我会写"先检查 props 类型定义，再检查 useEffect 依赖数组，最后检查事件监听器是否清理"。这些指令看起来简单，但模型执行出来的效果完全不同——因为之前它不知道"审查"这个词到底该看什么、按什么顺序看。

输出格式要求。决定最终交付物的样子。是输出纯文本报告？还是 Markdown 表格？还是直接给出可运行的代码块？有没有必须包含的章节？有没有必须避开的表达方式？这些都要写死。模型非常吃这一套，只要输出格式约束得足够明确，结果就从"杂乱"变成"专业"。

示例与反例。一个正面示例比几百字描述效果都好。正面示例展示"完美答案长什么样"，反例展示"绝对不能这么写的原因"。很多社区的 Skill 作者偷懒不写示例，这个其实是最不应该省的部分，尤其对于写作类、设计类这种主观性强的技能，示例就是模型最好的老师。

元认知提示。这一部分可以理解为"指导模型如何思考"。比如"在开始之前，先列出你打算审查的代码文件清单""如果发现不确定的地方，标记为待确认而不是直接下结论"。这类提示能显著提升模型在复杂任务中的稳定性。这部分的本质，是把人类专家做事的思维链过程，沉淀成了文档。

2.2 核心设计原则：渐进式披露（Progressive Disclosure）

我前面提到过，SKILL.md 是一份文档，但文档也有文档的学问。你不可能把所有细节全部塞进一个文件里——那样的 Skill 会变得臃肿，读取效率低下，而且模型在长文本里容易迷失重点。这里要引入一个在 UI 设计领域非常经典、用在 Skills 设计上同样适用的概念：渐进式披露。

简单说，就是"刚开始只给最必要的信息，更深的细节，在模型需要的时候再让它自己去翻"。实现方式很直接：SKILL.md主文件只写核心思路和关键步骤，然后通过引用链接指向若干个子文档。例如：

## 执行流程 1. 先阅读 [检查准备](preflight.md)，确认环境配置 2. 接着按 [漏洞分析手册](vuln_analysis.md) 中的清单逐项排查 3. 最后参考 [报告模板](report_template.md) 输出结果

这种设计最直接的好处，是让模型在"需要哪个知识的时候才去加载哪个文件"，不用整个技能包几十 K 的文本一次性全读完。它的理解开销和 Token 消耗都能被控制在合理范围内。我自己实测过：一个带完整子文档的技能，触发后首次决策的速度比"一坨超大文档"快大约 30%。这在日常用 Claude Code 这种即时交互场景里，体感差别还是很明显的。

除了效率，渐进式披露还带来一个额外的好处：可维护性。你想更新某一个环节的操作规范，只需要改对应的子文档，不用动主文件。多技能之间的公共部分还能抽出来共享，比如"安全性检查"这个子文档可以被前端审查、代码审查、渗透测试三个 Skill 同时引用。

2.3 为什么 "SKILL.md 必须是文本文件" 这件事是核心优点

我看过不少人的疑惑："搞个 JSON 配置文件不是更结构化吗？" 这里面的取舍，我多说两句。当你面对的是模型，而不是传统编程语言的编译器时，"易读性"远比"严格的类型结构"重要。模型在文本上的理解能力极强，而且对于自然语言的歧义是有容忍度的——"组件是否清理了事件监听"和"cleanup_listeners": true相比，前者反而更容易被模型转化为具体的代码检查动作。JSON 虽然工整，但从模型理解的角度来说，它反而是一种"编码"过的信息，需要模型先解析再执行。

所以 SKILL.md 选择 Markdown 是一个非常聪明的决定。Markdown 本身就是给人类设计的最轻量级的富文本格式，但同时模型对 Markdown 的解析能力也已经足够成熟。在这两者之间，Markdown 是平衡点。当然，如果你要写的技能涉及复杂参数传递（比如给模型提供 API 调用的 schema），那在子文档里嵌入 JSON 区块是完全可以的。但主文件用自然语言 + Markdown 结构来"激活"模型行为，始终是最优解。

3. 实操准备：环境搭建与目录规范

3.1 Claude Code、Codex 的 Skills 目录结构对比

先明确一个基本事实：Skills 虽然语义通用，但各家 Agent 的"放技能包的位置"还是不一样的。我当前主要的使用环境是 Claude Code 和 Codex，就以这两个为代表做个说明。

对于 Claude Code，技能目录在项目根目录下的.claude/skills/，或者在用户级目录~/.claude/skills/（这会让技能对所有项目生效）。目录内每个技能一个文件夹，结构大致如下：

.claude/skills/ └── memory-leak-review/ ├── SKILL.md ├── preflight.md ├── checklist.md └── examples/ ├── good_report.md └── bad_report.md

而 Codex 的姿势和 Claude Code 有一点不同，它主要用的是~/.codex/skills/，而且对SKILL.md的 frontmatter 有稍微具体的要求：description 字段得好，驱动 agent 判定的核心就在里面。不过大致模式一样，都是"一个文件夹一个技能，以SKILL.md为入口"。

这里建议小团队先统一标准：主文件固定叫SKILL.md，辅助资料用自己的文件名命名，并通过主文件引用。没必要完全照搬其他人的目录结构，只要你自己清楚、模型能够通过主文件路径寻到即可。

3.2 写第一个 Skill 之前的准备工作清单

我拿自己做过的一个"前端组件代码审查 Skill"举个例，带大家过一遍写技能之前该备齐哪些材料。

目标任务的详细流程。你得先把"前端审查"这个动作拆成可执行的步骤：入口文件读取、组件结构分析、props 类型检查、Hooks 依赖审查、事件监听清理确认、潜在内存泄漏标记、最终报告输出。如果没有提前拆解过流程，后面写文档时会发现漏洞百出。

这个领域的"优秀答案样例"和"常见错误样例"。从实际项目中挑一份你非常满意的代码审查报告，把好的部分拆开看：好在哪里？是语气专业？是问题定位准？还是建议给得具体？再挑一份劣质输出，把"模型容易犯的毛病"都整理一遍——太笼统、没有具体行号、只提问题不给修改建议、语气过于确定没有留有余地。这些都是写反例的绝佳素材。

边界情况清单。什么时候必须触发、什么时候坚决不触发、遇到不确定的依赖该怎样处理。把这些边界情况想清楚，然后在 SKILL.md 里写清楚。

准备好这三样，就可以动手写 SKILL.md 了。在写之前再打开一个 Claude Code 会话，把这三个问题的答案发给模型，请它帮你生成一版框架草稿——比自己从空白开始写效率高很多。注意：草稿必须经过人工修改，不能直接用。模型写出的指令往往过于"通用"，缺少你个人的经验和取舍。Skills 的核心价值恰恰就在那些"专属心法"里。

3.3 编写一个可直接落地的 "前端代码审查" Skills 示例

下面这个示例我是按社区普遍接受的格式写的。大家看的时候不用逐字复制，关键在于体会"写清楚到什么程度才算到位"。

--- name: frontend-review description: > 执行前端代码审查，重点检查 React 组件中是否存在内存泄漏、 不合理的状态管理、props 类型缺失以及事件监听器未清理等问题。 当用户要求审查前端代码/推荐改进/排查卡顿或内存问题时触发。 当用户只是询问前端概念或语法解释时，不要触发。 --- # React 前端代码审查 ## 触发条件 - 用户请求查看组件代码并给出优化建议 - 用户提到"内存泄漏""卡顿""性能优化"等关键词 - 代码中涉及 useEffect、addEventListener、setInterval 等异步资源 ## 禁止触发 - 用户要求解释某段代码的含义 - 用户要求生成新代码而非修改现有代码 ## 执行步骤 1. 先读取所有待审查的源文件，确认组件类型（函数组件/类组件） 2. 逐项检查： - 是否存在 `addEventListener` 或全局订阅，且没有在 `useEffect` return 中清理 - 是否存在 `setInterval` / `setTimeout` 且未在组件卸载时清除 - 是否存在大对象被直接放入 state 且无 memo 化 - 是否存在 props 缺少 PropTypes 或 TypeScript 类型定义 - 是否存在 useEffect 的依赖数组不完整（可参考 eslint-plugin-react-hooks 规则） 3. 输出报告时，每个问题需要写清楚： - 所在文件和行号 - 问题现象和潜在影响（能用用户能感知到的卡顿/崩溃来描述，不要只写理论） - 可执行的修复建议和示例代码 4. 如果发现不确定的问题，标记 [待确认] 而不是直接断言 ## 输出格式 使用 Markdown 表格，按严重程度从高到低排列： | 严重度 | 文件位置 | 问题说明 | 修复建议 | |---|---|---|---| | 高 | src/hooks/useChat.js:42 | setInterval 未清理 | 在 useEffect 返回函数中 clearInterval | ## 示例 好的审查报告： > 发现 `useChat.js` 第 42 行存在 `setInterval`，但 `useEffect` 的清理函数未清除该定时器。 > 这会导致聊天组件反复挂载/卸载时，定时器持续堆积，最终造成内存占用不断上涨。 > 建议在清理函数中调用 `clearInterval`。 坏的审查报告： > 这段代码有内存泄漏风险，建议优化。 > （没有定位到具体行号，也没有给出可执行的修改方案）

第一次写 skill 的朋友，我强烈建议把这个"坏报告"的反例原样保留。我自己坐在电脑前实测过，这个反例对模型的纠偏效果非常明显。很多模型严格审查后默认输出的就是第二种"正确的废话"，但你把反例摆在它面前之后，它的输出质量会立即上一个台阶。

4. 核心环节：从零到一构建一个真正好用的 Skill

4.1 需求定义：如何把一个抽象领域"拆"成模型能执行的步骤

到了实战环节，第一个挑战往往不是"怎么把指令写清楚"，而是"我居然连自己的领域该怎么拆解都说不太清楚"。这里我分享一个拆解方法论，我在构建多个技能的过程中反复使用，屡试不爽。

假设我们要做一个"论文写作 Skill"。大多数人第一反应是写"帮用户写论文"——这个描述太笼统，模型执行时就只能靠"自由发挥"了，效果可想而知。正确做法是往下拆：一篇论文从选题到成稿，至少可以拆成六个阶段——文献检索、论文大纲、论点论证、语言润色、引用管理、格式校对。每个阶段有不同行为标准，拆完之后，你把每个阶段对应的任务写清楚，这个 Skill 的基本框架就成形了。

再往下，每个阶段还要继续细化"该看什么、该问什么、该输出什么"。比如大纲阶段：先确定论文类型是实证研究、综述还是观点性文章，再按学科惯例构建 outline 层级结构。文献检索阶段：要收集哪些字段（作者、年份、期刊、核心结论），检索结果的整理格式是什么。这些细节就是区别于通用模型的地方。

我个人的建议是：拿一张纸，把这些"阶段"和"操作"全部写出来。这一步不需要任何技术含量，但它是整个 Skills 工程中最重要的工作。你甚至可以把它看作是在"给一个人写工作手册"，想清楚这个问题之后，你离写一个专业技能包就只差最后一步——把他的操作转换成模型的指令语言。

4.2 交互式引导设计：让模型在任务不明确时主动追问

好的 Skill 除了能处理清晰任务，还得在任务信息不足时，会向用户主动提问。很多新手写的 SKILL.md 有个通病——假设模型面对的用户需求总是足够清楚的，但现实中完全不是这样。

比如用户说"帮我写个策略"——什么策略？用户说"做一下安全测试"——测哪个系统？测试范围多大？有没有授权？这些信息不明确时，如果模型硬干，结果往往差强人意。好的做法是在 SKILL.md 里明确写一条："当用户意图存在歧义，或者关键参数缺失时，列出你最需要的三个信息，向用户提问后再继续，而不是直接假设。"

这一点在"自动挖洞 Skills"、安全审计这类高风险高不确定性任务里尤为重要。没有边界确认就乱扫，轻则输出一堆没用的东西，重则碰到诡异系统甚至误操作。我写这类技能时都会在文档里固定一个"输入确认"的环节，先列出需要用户提供的资产范围、授权情况、时间窗口，确认完毕再往下走。

更好的做法，是提供几个预设的"问题模板"，让模型直接选用而不是自然发挥。比如：

• "我需要确认以下信息后才能开始：1）被测目标地址和范围；2）是否具有测试授权；3）测试的时间窗口和允许的测试深度。"
• "项目背景我不太确定：您希望我按照哪种格式输出最终交付？报告类还是表格类？"

这种交互式设计还有个副产品——模型会更"像人"。因为它在接触一个新任务时会表现出"接手一个活后先问清楚"的素养，而不是瞎猜一通后交出一份自作主张的结果。真实用户体验差异非常大。

4.3 技能版本管理与多人协作：Git 仓库、Code Review 与灰度发布

现在很多团队已经不止一个人在做 Skills 了，甚至已经出现了团队的"技能仓库"。这时候就得考虑工程化管理。我的做法是：主技能库放在一个独立的 Git 仓库里，每个技能一个目录，README.md里记录这个技能的负责人、变更历史和适用场景，SKILL.md 自身的 frontmatter 里还加一个last_updated字段。

多人协作时，最关键的是 Code Review。Skill 文档虽然不写代码，但 review 起来和代码 review 一个套路：这个技能的行为边界是否清晰？有没有过度触发的情况？示例是否容易误导模型？一个好的 PR 通常包含：更新的 skill 文档、三个以上的测试样例记录、以及一个"验证报告"（说明改完之后模型干活的输出对比）。这个习惯能极大减少"直观感觉挺好但实际一用就翻车"的情况。

灰度发布同样重要。我在正式给团队全量推送某个新技能之前，习惯先准备一个"影子目录"，只让少数几个开发者用新版本，其他人沿用旧版本。等收集到足够的使用反馈、跑通核心路径之后，再通过 Git 发布公告把改动合并。而这个"影子目录"的实现很简单，就是让测试人员在自己项目下的.claude/skills/里单独复制一份新技能，主仓库的版本暂时不动。这种玩法几乎零成本，但能规避大量潜在线上事故。

4.4 优化细节：如何给 Skills 写高质量的"触发描述"和"禁用条件"

触发描述好坏的差异，我直接用一个对比来说。

• 不推荐：description: 用于代码审查
• 推荐：description: 用于 React 组件代码审查，重点检查内存泄漏、性能瓶颈、状态管理不合理、props 类型缺失等问题。当用户请求对前端 React 代码进行优化、排查卡顿或内存问题时触发。当用户仅要求解释代码含义时不触发。

差别在哪？前者的描述会让模型在"用户问一个不具备明确审查性质的代码问题时"也会想办法加载技能，最后带来的是 Token 浪费和输出跑偏；后者不但把触发场景写清楚了，还把最重要的"不触发"场景也写进去了。模型对禁令的敏感度远高于指令。一条描述精准的技能，在执行时"不打扰"用户的频次才会低，使用体验才会有本质提升。

这里再分享一个技巧：写触发描述时，多想想"用户在什么情况下会想要这个技能"。是遇到了具体报错？是想要一个特定格式的交付物？还是想开启一轮特定思维模式的头脑风暴？把这些具体情境写进描述里，模型的匹配精度会高很多。如果拿不准，写完描述后拿几个"会不会触发"的测试问题去实测，看模型的加载日志，微调描述。这个过程多搞两三轮，描述质量就基本到位了。

5. 好用的技能来源：去哪里找现成的 Skills

5.1 主流开源仓库与下载平台盘点

自己从零写 Skill 很爽，但更多时候，大家的第一步大概率是找一个现成技能装上试试。那么问题来了：去哪找？目前主流渠道有这几类：

GitHub 开源技能库。搜索关键词skills、claude-skills、codex-skills，能找到大量聚合仓库，有的已经做到了几百个技能的规模。这些库通常按领域归类，看 README 就能大概判断技能质量。比较妙的经验是：别光看 star 数，要看最近 commit 时间，以及是否有人提 issue 反馈某一类场景失效。AI 领域的文档时效性极强，半年不更新的技能大概率已经跟不上模型版本。

官方市场和内置集成。部分 Agent 服务商开始支持"官方技能市场"，下载安装可以走官方命令或 Web 界面。这类技能通常维护较好、兼容性高，但数量有限，且比较偏大众场景。如果需求小众，大概率还是得去开源社区找。

个人博客与技术社区分享。很多一线开发者会把写在生产环境里验证过的技能包发到个人博客或者技术社区，并附上实际使用效果截图。这类来源的质量往往两极分化明显，要重点看作者的使用场景跟你的相似度有多少。他自己验证过的场景，可能压根不是你的场景，只凭"他写得不错"就直接拿到生产环境，容易踩坑。

这里我给大家一个安全准则：任何来源的技能包，第一件事是"读一遍 SKILL.md"，而不是"立刻扔进配置目录"。读懂这份文档之后，重点关注两件事——它建议的触发条件是否会误伤到你的正常使用？它的执行步骤里有没有在你的业务域里明显不合理的假设？你应该极少看到完全满足要求的文档，改一改很正常，直接改完再用就好。

5.2 如何判断一个现成 Skill 的质量高低

既然现在技能包市场鱼龙混杂，学一眼看出"这个 Skill 到底行不行"就很有必要。我的经验一般看这五条：

• 描述是否窄而深。好的技能描述只聚焦一个足够的领域，而不是大而全的万能模板。看到"适用于各种代码审查"这种描述，基本可以判断是粗制滥造。
• 有无反面示例。前面反复强调过，一个高质量技能必然包含"不该怎么做"的示例，如果没有，大概率作者只是把自己的一些思路草草转述，并没有在真实场景中反复打磨过。
• 步骤是否可验证。每个核心执行步骤，是否给出了"做到什么程度算合格"的检验标准？如果一个技能的全流程只是"分析问题、给出方案、输出报告"这种空话，那你装了它和没装几乎没区别。
• 是否提供了"追问机制"。我不只一次说过，好的技能在信息不足时知道先提问。如果整个文档通篇都是"他会很聪明地自己搞明白一切"的暗示，这种文档就是把你当外行。
• 有无版本更新记录。有没有历时多个版本的自然演进痕迹，再结合更新时间，判断作者是否还有持续维护。

结合这五条，基本能筛掉 80% 的垃圾技能包。剩下的也会比较自然地进入"你愿意在它身上投入时间再去二次定制"的候选名单。

5.3 我已经用过的、确实能提高效率的几个技能示例

这里不卖关子，直接说三个我已经在生产环境中长期用的技能包，以及它们带给我的具体收益。

第一个是代码审查类。我自己改造过的前端 React 审查技能，用了大半年。它并不是什么黑科技，但每一次审查输出的报告都非常稳定，它会自动标出问题所在文件和行号、给出修复方向，有的还会附上它实际检测到的代码片段供我快速跳转确认。最重要的是——它不会在高危问题上含糊其辞，每次确认到内存类问题都会写得格外详细，让我这个常年救火的人觉得非常省心。

第二个是分镜脚本类。社区里有个做短视频分镜的技能包，非常精巧。它会按"景别、运镜、时长、画面描述、音频、字幕"这样的结构输出分镜表。写完 SKILL.md 的过程中，我对"分镜脚本到底该包含哪些必要信息"做了一次系统性梳理，这个价值甚至超过了技能本身的使用价值。在使用效果上，之前模型直接生成的脚本总会漏掉"运镜逻辑"，但套上这个技能之后，每一版输出都规规整整。

第三个是论文写作辅助类。这个技能在 WorkBuddy 和 Codex 上都有适配版本，它把论文拆成了摘要撰写、引言逻辑、相关工作、方法论、结论、参考文献管理等环节，并且为每个环节制定了具体的输出约束。我拿它写过一篇技术综述，从框架生成到最终润色，全程的产出质量比较稳定，减少了"先写一段看看，不行再改"的来回拉锯。

客观讲这几个技能都不算"神乎其神"，但它们的共同特点很突出——就是把一个有经验的人本该知道的"窍门"全部显性化地写在了文档里。这恰恰是 Skills 最有价值的地方。

6. 常见问题与避坑经验

6.1 技能不触发或者误触发的原因排查

很多新手装完技能后发现：明明按照说明放了文件夹，但模型就是不用。排查思路是这样的：

第一步，检查目录结构和命名。SKILL.md是否拼错了？文件夹层级是否正确？有没有把技能错误地放到了某个不读取的位置？这些基础问题占了 70% 的故障来源。

第二步，检查 frontmatter 的description字段。你有没有写上足够明确的"触发条件"和"不触发条件"？单纯一个"用于代码审查"让模型很难对任务和技能做高精度匹配。试着把描述改得更具体，多提关键词和用户场景。

第三步，看模型的加载日志。绝大多数 agent 都会在调试模式下打印出来"已加载技能"还是"未加载技能"，以及对应的评分。这个日志是定位问题的最关键手段。如果你用的工具没有日志，就主动在会话里问一句"你现在加载了哪些技能？"——多数模型会如实回答。

反过来，如果技能"过度触发"（比如用户只是随口问个前端概念，它就要进入审查模式），多半是禁用了条件没写。老老实实把"什么时候不要触发"写在描述里，这个问题能解决一大半。

6.2 技能生效了但输出质量不稳定的原因与优化

技能已经加载，输出却不稳定，这通常不是模型"坏"了，而是我们的描述还是太模糊。举几个我自己踩过坑的例子。

第一种，输出格式约束不彻底。你说"请输出审查报告"，模型可能会输出大段大段的叙述型报告。你要的是表格还是列表？报告中是否需要行号？按严重度怎么排序？这些如果没写死，模型每一次输出风格都可能不一样。解法：把格式要求写成一整段强制指令+一个示例。

第二种，步骤顺序过于随意。如果 SKILL.md 里写的是"分析组件 -> 给出建议"，模型可能上来先写总结，再往回倒推细节，这会破坏执行逻辑。解法：把步骤写成"先 X，再 Y，最后 Z"的强制顺序，并且说明每一步的输出物是什么。

第三种，没有"终止判据"。模型经常会在你已经满意之后还反复提出修改建议，甚至"自问自答"。解法：在文档里写明"报告输出完成，且用户未提出进一步需求时，停止生成，等待用户反馈"。就这一句，能砍掉很多不必要的后续输出。

第四种，也是最重要的一点——上下文污染。如果你在一个已经长对话很久的会话里换用技能，模型很可能被更早的上下文风格带偏，这时候技能的作用会被明显削弱。切记，测试技能一定要开一个新的会话，用全新姿态去验证效果，否则你收获的判断都是错误的。这一点我在实际工程里反复踩坑后，已经写进了团队的使用规范。

6.3 一份"避坑速查表"：新手最容易犯的五个错误

写到这里，我其实特别想再强调一件事：Skill 是一个"活的文档"，不是一次写完就一劳永逸。模型底层升级了、任务场景变了、用户反馈的问题多了，都需要回过来改文档。我自己的习惯是每个月花一个下午把所有在用技能整体过一遍，把它们在使用中遇到的"又没按预期走"的情况记下来，试着在文档里补充或修正对应指令。这有点像调菜谱——盐放多少，火候多大，全是在一次次实际翻炒中试出来的。

Skills 体系的出现，侧面印证了一件事：在 AI Agent 这条路上，光靠"模型本身大而全"是不够的，真正的差异开始来自于"你能不能给模型一份足够专业、足够具体、足够可执行的心法"。而这份心法，可以是一个人独自积累的经验，也可以是一个团队共同维护的资产。下一个半年，我相信会有越来越多的组织和开发者进入这个领域，把"自己的独门绝技"封装成一个个规范、收敛、可复用的技能包。如果你还没有动手试过，这篇文章之后，不妨找一个最常做的领域，先写一份 SKILL.md，再让模型按你的方式试一试——你可能会有意外惊喜。