企业官网建设流程全解析

1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个标题，很多人会懵——这词太泛了。但结合热搜词里的 Claude、Agent Skills、SKILL.md、Claude Code 来看，这里说的 skills 不是泛指"技能"，而是特指AI 编程助手生态里的技能包机制。简单讲，就是给 Claude Code 这类命令行 AI 工具装上一套"可复用的能力模块"，让它从"什么都能聊两句"变成"在某个具体领域真能干活"。

我最初接触这个概念时也走了弯路。当时以为 skills 就是提示词模板，写几段话存起来，用的时候粘进去。后来才发现完全不是一回事——真正的 skills 是一套有目录结构、有元数据声明、有触发条件的文件系统，AI 会根据当前任务自动判断该加载哪个 skill，而不是你手动去翻。这个差别很关键，前者是"你伺候工具"，后者是"工具伺候你"。

那 skills 到底能做什么？举几个我实际用过的场景：数学建模比赛前，装一套建模专用的 skills，AI 就能按标准流程帮你做假设检验、写论文摘要；做前端开发时，装一套组件规范 skills，AI 生成的代码会自动符合团队的目录约定和命名风格；甚至做 AI 漫剧脚本，也有对应的 skills 帮你把分镜描述转成结构化输出。它的本质是把领域知识固化成 AI 可调用的资产。

适合谁来学？三类人最该看：一是天天用 Claude Code 但总觉得"它不够懂我"的开发者；二是想把自己团队规范沉淀下来、让 AI 自动遵守的技术负责人；三是刚入门 AI 编程、想少踩坑的新手。这篇文章我会从 skills 的目录结构讲起，到怎么写第一个 SKILL.md，再到安装、调试、避坑，全部按我实际操作的顺序来，不跳步。

提示：本文提到的所有路径、命令均基于通用实践整理，不同版本的工具在细节上可能有差异，以你本地实际环境为准。

2. skills 的目录结构与 SKILL.md 到底长什么样

2.1 一个 skill 的最小构成

很多人卡在第一步：不知道一个 skill 该放哪些文件。我拆过十几个开源 skills 后总结出一个规律——最小可用单元就两个东西：一个文件夹，一个 SKILL.md。文件夹名就是 skill 的标识，SKILL.md 是入口说明书。除此之外的所有文件都是可选的，按需添加。

一个典型的目录长这样：

my-skill/ ├── SKILL.md # 必需，技能说明与元数据 ├── scripts/ # 可选，辅助脚本 │ └── helper.py ├── templates/ # 可选，模板文件 │ └── report.md └── references/ # 可选，参考资料 └── spec.md

为什么强调"最小可用"？因为我见过太多人一上来就想搞个大而全的技能库，结果目录建了七八层，SKILL.md 却写得含糊，AI 根本不知道该在什么时候调用它。先跑通一个最简单的，再往上加东西，这个顺序不能反。

2.2 SKILL.md 的头部元数据：决定 AI 会不会用它

SKILL.md 最关键的部分是开头的元数据块，通常用 YAML 格式写在文件顶部，被三条横线包起来。这块内容直接决定 AI 在什么场景下会激活这个 skill。我踩过的最大坑就是：元数据写得像散文，AI 完全抓不到触发点。

一个能用的元数据大概是这样：

--- name: math-modeling-assistant description: 用于数学建模竞赛的辅助技能，当用户需要做假设检验、数据预处理、论文摘要撰写时使用 version: 1.0.0 tags: - 数学建模 - 数据分析 - 论文写作 ---

这里每个字段都有讲究。name要短、要唯一，别用中文和空格，否则某些工具解析会出问题。description是重中之重——它不是给你看的，是给 AI 判断"要不要加载"用的。所以描述里必须包含"什么时候用"这个信息。我一开始写的是"数学建模辅助工具"，结果 AI 几乎不主动调用；改成"当用户需要做假设检验、数据预处理时使用"之后，命中率立刻上来了。

tags字段看起来可有可无，但在 skill 数量多了之后，它是你做分类检索的唯一抓手。我现在的习惯是至少打三个标签：领域、任务类型、使用阶段。

2.3 正文部分：写给 AI 看的操作手册

元数据下面是正文，用 Markdown 写。这部分的核心原则是：把 AI 当成一个聪明但完全不了解你业务的新同事。你要告诉它这个技能解决什么问题、按什么步骤做、有哪些禁忌。

我常用的正文结构是四段：适用场景、操作步骤、输出格式、注意事项。举个真实例子，我写过一个"代码审查"的 skill，正文里明确规定了"先看命名规范，再看边界条件，最后看性能问题"这个顺序。为什么定这个顺序？因为实测下来，如果让 AI 自由发挥，它经常一上来就纠结性能，把明显的命名问题漏掉。顺序本身就是一种知识，这是普通提示词给不了的。

正文里还可以引用同目录下的其他文件，比如"详细规范见 references/spec.md"。这样 SKILL.md 本身能保持精简，AI 需要细节时再去读引用文件。这个设计很像编程里的"懒加载"，避免一次性把所有内容塞进上下文。

3. 从零写第一个 skill：完整实操链路

3.1 先想清楚"这个 skill 替我省什么"

动手之前先问自己一个问题：没有这个 skill，我每次要重复做什么？这个问题的答案就是 skill 的价值所在。我见过有人写 skill 纯粹为了"看起来专业"，结果写完之后自己从来不用，因为那个任务他一个月才做一次，根本不值得固化。

判断标准很简单：如果一个任务你每周至少做两次，且每次都要跟 AI 解释一遍背景，那就值得写成 skill。比如我每周要处理好几份数据报表，每次都要说明"日期列要转成标准格式、空值用中位数填充、最后按周聚合"，这套话说了几十遍之后，我就把它固化成了 skill。

3.2 建目录、写元数据、填正文

确定要写之后，操作其实很直接。第一步建目录，我习惯放在统一的 skills 根目录下，比如~/.claude/skills/或者项目内的.skills/目录。放哪里取决于你是想全局复用还是项目专用——全局的放用户目录，项目专用的放仓库里跟着代码走。

第二步写 SKILL.md。这里有个小技巧：先写 description，再写正文。因为 description 逼你把"什么时候用"想清楚，想清楚了正文自然好写。我经常看到有人正文写了一大堆，description 却只有四个字，这就是本末倒置。

第三步填正文。我建议新手先用最笨的办法：把你平时跟 AI 解释这个任务时说的话，原封不动记下来，然后整理成步骤。这些"原话"往往就是最有价值的部分，因为它们是你真实踩过坑之后形成的表达。

3.3 本地测试：怎么知道 skill 生效了

写完不代表能用。测试环节我一般分三步走。第一步，直接问 AI 一个该 skill 覆盖范围内的问题，看它有没有主动引用这个 skill。如果没有，八成是 description 写得不够具体。第二步，手动指定使用某个 skill，看它执行步骤对不对。第三步，故意问一个边界问题，看它会不会错误地激活这个 skill。

第三步最容易被忽略，但恰恰最重要。我写过一个"数据库优化"的 skill，结果发现只要问题里出现"慢"这个字，它就被激活，哪怕用户说的是"网速慢"。后来我在 description 里加了限定词"仅当涉及 SQL 查询性能时"，误触发就少多了。skill 的精准度靠的是排除法，不是包含法，这个认知我是踩了几次坑才建立的。

4. 安装与集成：把 skills 接进你的工作流

4.1 手动安装 GitHub 上的 skills

热搜里有个高频问题："怎么手动装 GitHub 上的 skills"。这个操作本身不复杂，但有几个细节容易翻车。基本流程是：找到目标 skill 仓库，把整个目录克隆或下载下来，放到你的 skills 根目录，然后重启工具让它重新扫描。

翻车点在哪？第一，目录层级。有些仓库的结构是repo/skills/xxx/SKILL.md，你直接整个克隆进去，工具扫描时可能找不到 SKILL.md，因为它在两层目录之下。正确做法是把最内层那个包含 SKILL.md 的文件夹单独拎出来放。第二，文件名大小写。SKILL.md 必须全大写，写成 skill.md 或 Skill.md 在某些系统上就识别不了。第三，权限。如果 skill 里带了可执行脚本，克隆下来之后记得检查执行权限。

我一般的操作顺序是：先克隆到临时目录，进去确认 SKILL.md 的位置，再把正确的文件夹移动到 skills 根目录，最后重启验证。多这一步确认，能省掉后面一堆"为什么没生效"的排查。

4.2 在编辑器里配置与调用

如果你用的是带 AI 插件的编辑器，skills 的集成方式通常是配置一个 skills 目录路径。这里的关键是路径要用绝对路径，相对路径在不同工作区下会失效。配置完之后，建议开一个测试文件，随便问一个该 skill 覆盖的问题，看侧边栏或日志里有没有加载记录。

有个我踩过的坑值得说：某些工具会缓存 skill 列表，你新增了 skill 但没重启，它就是不认。所以我的习惯是每次改完 skill 都完整重启一次工具，而不是指望热加载。虽然麻烦，但比"改了半小时发现根本没生效"要省时间。

4.3 多 skill 共存时的优先级问题

当你装了十几个 skill 之后，新问题来了：两个 skill 的触发条件重叠怎么办？比如一个"通用代码审查"和一个"Python 专项审查"，遇到 Python 代码时该用哪个？

我的处理原则是专项优先于通用。具体做法是在专项 skill 的 description 里写清楚"当涉及 Python 时优先使用本技能"，同时在通用 skill 里注明"Python 场景请转用专项技能"。这种显式的互相引用，比让 AI 自己猜要可靠得多。实测下来，明确写了优先级规则的 skill 组合，误用率能降一大半。

5. 调试与排错：skill 不生效时的排查链路

5.1 第一步永远是确认文件被扫描到了

skill 不生效，先别急着改内容。先确认工具到底有没有看到这个文件。大多数工具都有日志或者调试模式，能看到它扫描了哪些目录、加载了哪些 skill。如果日志里压根没有你的 skill，那问题在路径或文件名，跟内容无关。

我遇到过最隐蔽的一次是：目录名里带了个空格，工具扫描时把空格后面的部分截断了，导致 skill 名对不上。这种问题看日志一眼就能发现，但如果不看日志，你会一直以为是 description 写得不好，改半天白费劲。

5.2 description 写得太"文艺"导致不触发

确认文件被加载之后，如果还是不触发，九成是 description 的问题。常见的毛病有三种：一是太抽象，比如"提升代码质量"，AI 根本不知道什么时候该用；二是太宽泛，什么都能沾边，结果到处误触发；三是中英文混用导致关键词匹配失败。

我的修复方法是把 description 当成搜索关键词来写。想象用户会怎么描述他的需求，把这些说法都塞进去。比如"数据清洗"这个 skill，description 里我会写"当用户提到数据清洗、缺失值处理、异常值检测、格式标准化时使用"。这些词就是用户真实会说的，命中率自然高。

5.3 内容太长被截断的隐形问题

还有一个不容易发现的问题：SKILL.md 太长，超出了工具的加载上限，导致后半部分根本没被读进去。这种情况的表现是"skill 好像生效了，但步骤执行到一半就乱了"。

判断方法很简单：把 SKILL.md 精简一半，如果行为变正常了，那就是长度问题。解决思路是把细节挪到 references 目录下的独立文件，SKILL.md 只保留主干流程和引用指针。我现在给自己定的规矩是 SKILL.md 正文不超过 200 行，超了就拆。

6. 让 skill 真正好用的几个经验

6.1 把"反面案例"写进去比写正面步骤更有效

这是我用了一年多之后最大的体会。一开始我写 skill 全是"第一步做什么、第二步做什么"，后来发现 AI 经常在某个特定地方犯错。于是我在 skill 里加了一段"常见错误"，明确写"不要这样做，因为会怎样"。结果那类错误几乎绝迹了。

原因其实不难理解：正面步骤告诉 AI"该做什么"，但 AI 的默认行为可能跟你的期望有偏差；反面案例直接纠正它的默认倾向，效果更直接。所以现在我写 skill，正面步骤和反面案例的比例大概是七三开。

6.2 版本管理别偷懒

skill 是要迭代的。我最早的几个 skill 改了十几版，如果没有版本记录，根本记不清哪版改了什么、为什么改。我的做法是在 SKILL.md 的元数据里维护 version 字段，同时在文件末尾用注释记一句"本次改动原因"。别小看这一句，三个月后你回头看，它就是你的记忆。

6.3 定期清理比不断新增更重要

热搜里有个词叫"清理 skills 的方法"，说明很多人已经意识到 skill 堆积的问题。我的经验是：每季度过一遍所有 skill，把三个月没用过的删掉或归档。skill 不是越多越好，太多会导致触发混乱，而且维护成本直线上升。我现在稳定保持在十个以内，每个都是高频使用的。

清理的判断标准也简单：打开 skill 列表，逐个问自己"上次用它是什么时候"。想不起来的，基本就可以删了。删之前把内容备份到一个 archive 目录，万一以后要用还能找回来。

6.4 分享与复用：把团队规范变成 skill

个人用熟了之后，最有价值的延伸是把团队规范固化成 skill。比如团队的代码提交规范、接口文档格式、测试用例写法，这些以前靠文档和口头传达，现在写成 skill，AI 生成的内容自动符合规范，新人上手也快。

我帮一个小组做过这件事，把他们的接口规范写成一个 skill 之后，AI 生成的接口代码一次通过率明显提升。关键是把规范里那些"只可意会"的部分也写进去，比如"参数命名要能看出业务含义，不要用 a、b、c"。这种细节文档里通常不写，但恰恰是新人最容易犯的错。

7. 关于 skills 学习路径的一点个人建议

如果你刚开始接触，我的建议是别急着收集别人的 skill，先自己写一个。哪怕写得粗糙，这个从零到一的过程会让你真正理解 skill 的运作机制。我见过太多人收藏了几十个 skill 仓库，结果一个都没跑起来，因为不理解原理，遇到问题就卡住。

写第一个 skill 的时候，选一个你每天都在做的、流程固定的小任务。不要选那种"偶尔做一次、每次都不一样"的任务，那种任务写不成 skill。等你写完第一个、跑通、用上一周，再去看别人的 skill，你会发现一眼就能看出哪些写得好、哪些是花架子。

至于学习资源，与其看教程，不如直接读几个高质量开源 skill 的 SKILL.md 源码。看别人怎么组织元数据、怎么分步骤、怎么处理边界情况，比任何教程都直观。我自己的写法就是从读别人的 skill 里一点点模仿、改进出来的。

最后说个我自己的习惯：每次写完一个 skill，我会故意隔一周再用它。如果一周后我还能顺畅地用起来、不需要回忆"当时是怎么设计的"，说明这个 skill 的 description 和结构是合格的。如果我自己都要想半天，那 AI 肯定也懵。这个"隔周测试法"帮我淘汰了不少自嗨型的 skill。