企业官网建设流程全解析

最近技术圈里有个事讨论得特别热闹：Claude 内部那套让团队效率翻倍的 Skill 机制，开源了。起因是有人把一批 Claude Code 里实际在用的 Skill 脚本整理成仓库放了出来，仓库一上线就被各路开发者围观、转发、改造成自己的版本。如果你最近在折腾 Claude Code，肯定见过skill、SKILL.md、Agent Skills这几个词，但 Skill 到底是什么、它跟普通提示词有什么区别、拿到开源 Skill 之后怎么装进自己的项目里，很多人的理解还停留在“好像是个插件”的层面。

这篇文章我打算从一个实际使用者的角度，把 Skill 这套机制掰开揉碎讲清楚：底层怎么工作、SKILL.md 怎么写、怎么把开源 Skill 改造成自己的、以及我在真实项目里踩过的坑。不管你是在终端里重度使用 Claude Code 的开发者，还是刚准备入坑 AI 编程的新手，这篇文章都值得读完再动手。先说结论：Skill 本质上是一套“按需加载的能力包”，它比堆提示词优雅得多，也是目前社区里最值得花时间研究的 Claude Code 进阶玩法。

1. Skill到底是什么：一次内部刷屏背后的机制

1.1 为什么Skill先在Claude内部火起来

所谓 Skill，在 Claude Code 的语境里，本质上是一套“按需加载的能力包”。它不是一个常驻的指令集合，而是放在特定目录下的一组文件——最核心的是SKILL.md，里面用结构化格式描述了这个技能什么时候该用、该怎么用。Claude Code 在运行时会根据当前任务自动判断要不要调用某个 Skill，而不是把所有规则一股脑塞进上下文中。

这套机制之所以先在 Claude 内部火起来，是因为它解决了一个非常实际的问题：Claude Code 的上下文窗口虽然大，但也不是无限大。你不可能把所有项目的规范、代码风格、审查清单、命令模板全部写进全局配置里。Skill 的思路是“按需取用”——写前端的时候调前端规范，做代码审查的时候自动加载审查清单，互不干扰。

我在自己机器上第一次跑通 Skill 的时候，说实话挺震撼的。以前我在CLAUDE.md里堆了几百行规则，结果模型每次对话都要把这些内容从头读一遍，既浪费 token 又容易让指令互相打架。换成 Skill 之后，只有在任务匹配时相关规则才会进入上下文，响应质量和速度都有明显提升。更关键的是，团队里其他人拿到同一个 Skill 文件夹，就能复现一模一样的执行标准，这就是它能在内部快速传播的原因。

1.2 Skill、Subagent、MCP三者怎么分工

很多刚接触 Claude Code 的人会把 Skill 和 Subagent、MCP 混在一起，因为它们看起来都是在“给 Claude 加能力”。我在用的过程中整理了一个比较简单粗暴的区分方式：

这种分工理解了之后，你在设计自己的 Skill 时就会更清楚边界：如果只是想规范模型的行为方式，用 Skill；如果想并行处理多个独立子任务，用 Subagent；如果需要读写外部系统，用 MCP。三者不是互斥的，实际项目里经常是配合使用——Skill 规定了审查流程，Subagent 并行审查不同模块，MCP 把审查结果写回工单系统。我见过最顺滑的用法是三者串成一条流水线，各管一段，互不越权。

2. Skill的核心规范：SKILL.md才是灵魂

2.1 一个Skill的本质是一个文件夹

在 Claude Code 里，一个 Skill 就是一个文件夹，文件夹里必须有一个SKILL.md文件。这个文件是整个 Skill 的灵魂，它决定了模型什么时候会想起这个技能、调用之后按什么方式执行。目录结构大致长这样：

~/.claude/skills/ └── code-review/ ├── SKILL.md ├── review-checklist.md └── prompts/ └── security-review.md

~/.claude/skills/是用户级别的全局 Skill 目录，里面的所有 Skill 对所有项目生效。如果你只想在某个项目里用某个 Skill，就把它放到项目根目录的.claude/skills/下。这种全局与项目分离的设计我非常喜欢，因为它天然解决了“团队规范共享”和“个人偏好隔离”之间的矛盾——团队规范放项目里，个人顺手的小工具放全局目录。

需要注意一个细节：目录名最好和 Skill 的name字段保持一致，用短横线连接的小写单词。比如技能名叫code-review，目录就命名为code-review。这样做不是为了好看，而是为了让模型在路径识别时降低混淆概率。我在早期把目录命名为CodeReview，结果偶尔出现模型找不到辅助文件的情况，改成小写短横线风格之后就没再出过问题。

2.2 描述写得越好，触发越准

SKILL.md的文件内容一般分为两部分：开头的 YAML frontmatter 和正文。YAML 部分最关键的两个字段是name和description。name是技能标识，description决定了模型在什么情况下会加载这个 Skill。这里有一个特别重要的经验：description不是写给人看的简介，而是写给模型看的“触发条件说明书”。

我见过很多失败的 Skill，问题几乎都出在description写得太空泛。比如：

--- name: code-review description: 用于代码审查 ---

这种描述等于没说。模型遇到任何和代码沾边的任务都可能触发它，或者反过来，根本不触发。正确写法是明确“什么场景适用、任务目标是什么、大概会有哪些步骤”，让模型能把当前任务和描述里的关键词做精确匹配。

--- name: code-review description: 在合并Pull Request之前执行代码审查。当用户要求review代码、检查PR、查找潜在bug或安全隐患时使用。包含逐文件检查、逻辑验证、安全扫描和结构化结论输出。 ---

写 description 的时候我的一个心法是：把自己想象成搜索引擎的爬虫，描述里要包含用户最可能说的关键词，同时用“仅当”“不适用于”这类限定词划清边界。比如加上“不适用于代码编写或功能开发任务”，能明显减少误触发。

2.3 辅助文件什么时候才需要

SKILL.md的正文部分是执行指南，但并不是所有内容都要堆在SKILL.md里。如果 Skill 涉及大量模板、检查单、示例代码，我会把它们拆成独立的辅助文件，然后在SKILL.md里用相对路径引用。

这里有一个细节很多人不知道：辅助文件不会在加载时全部读入上下文，而是在需要时由模型主动去读取。所以把大块内容拆到辅助文件里，既能保持SKILL.md精简，又能避免一次性消耗过多 token。实测下来，一个优雅的 Skill 文件结构能让大任务的上下文占用降低不少，尤其是那种任务链路很长的场景。

那什么时候该拆、什么时候该留在原地？我的经验是：执行步骤、判定条件、禁止事项这些“模型必须时刻记住的东西”放正文；检查细项、报告模板、示例代码、参考资料这些“用到才查的东西”放辅助文件。掌握这个原则之后，你的 SKILL.md 会从长篇大论变成精炼的操作指引，可读性和实际效果都会上一大截。

3. 手把手实战：写一个Code Review Skill

3.1 明确边界：这个Skill负责什么、不负责什么

动手写之前，第一步不是写代码，而是把边界想清楚。我这个 Code Review Skill 的定位是：在代码合并前做一次快速但系统的审查，覆盖逻辑正确性、安全隐患、性能隐患、代码风格四个方面。它不负责修改代码——只输出问题和修改建议，改不改、怎么改由开发者决定。这个边界很重要，因为我踩过坑：一开始我在 Skill 里写了“发现问题后直接修复”，结果模型在审查时顺手改了一堆代码，反而把正常逻辑破坏了。

Skill 的边界决定了正文的写作风格。既然定位是“审查并输出报告”，正文就应该强调“逐文件分析、输出结构化结论”，并明确告诉模型“不要直接修改源码”。这一步想清楚之后，写出来的 Skill 才有清晰的行为边界，而不是让模型自由发挥。

3.2 目录结构与文件命名

我最终落地的目录结构是这样：

~/.claude/skills/code-review/ ├── SKILL.md ├── checklist.md └── examples/ └── report-template.md

checklist.md里是具体的检查要点，比如“检查是否存在 SQL 注入风险”、“检查错误处理是否完整”、“检查是否有明显的性能瓶颈”。report-template.md是输出报告的模板，类似一个填空题，让每次审查的结果格式一致。这两个辅助文件让 Skill 的输出质量非常稳定——模型每次审查时，都会按 checklist 逐项过一遍，再按模板把结论填进去。

3.3 挂载Skill与首次调用

把文件夹放到~/.claude/skills/之后，Skill 并不需要“安装”或“注册”这类操作，Claude Code 会在每次对话开始时扫描技能目录。我习惯的做法是新建一个会话，然后直接说“帮我 review 一下当前分支的改动”。如果 Skill 被成功触发，模型会按照SKILL.md里的指引逐步执行，并且在思考过程中会引用 Skill 名称。

如果你是 Windows 环境，全局目录通常在当前用户目录下的.claude\skills，路径含义和 macOS、Linux 一致。第一次放置好之后，我建议在项目里跑一个最简单的验证：输入claude进入交互模式，直接问一句“你有哪些 skills 可用”，看模型能不能列出你刚放的技能。能列出来，说明挂载成功；列不出来，大概率是路径或者 YAML 格式出了问题。

3.4 验证效果：用一份“带病”代码测试

写完之后别急着觉得自己大功告成。我每次写完新 Skill 都会用一个故意埋了问题的测试项目去验证它到底有没有被触发、触发后有没有按流程走。我用过一个故意埋了 SQL 拼接、缺少错误处理、还有一处死循环的 demo 项目做测试。结果第一次跑的时候就发现问题：模型虽然触发了 Skill，但输出报告时没有按report-template.md的格式来。排查后发现是我在SKILL.md里只写了“参考模板”，没有明确“必须按照模板格式输出”。把措辞改成“严格按照 examples 目录下的 report-template.md 格式输出”之后，效果立刻正常了。

这个案例很好地说明了 Skill 编写的核心逻辑：模型不是人，它不会自动领会你没写清楚的要求，每个细节都要在文档里落到位。写 Skill 本质上是在写一份“机器的操作 SOP”，措辞越明确，行为越可控。

4. 开源生态里的Skill怎么选、怎么避坑

4.1 值得关注的几类开源Skill

这次开源出来的那批 Skill 里，我觉得最值得关注的是这么几类：

• Code Review 类：定义了一套完整的审查流程，包括逐文件分析、安全扫描、性能评估和结论输出。这类 Skill 对团队协作价值最高，因为审查标准可以被统一。
• 技术栈专项类：比如针对 React、Vue、Django 等框架的最佳实践。这类 Skill 对新手特别友好，相当于把资深工程师的经验沉淀成了可复用的规则。
• 文档与规范类：负责生成 commit message、编写项目文档、整理 CHANGELOG。这些任务看起来简单，但模型经常会产出风格不一致的内容，有了 Skill 约束之后效果好很多。
• Agent 编排类：这类 Skill 本身不做具体任务，而是教模型怎么把一个大任务拆解成多个子任务、怎么分配给不同的 Subagent，算是一种元能力。

我个人的建议是，第一次接触开源 Skill 生态时，先拿一个 Code Review 类和一个文档规范类练手。这两个方向需求最普遍、效果最容易量化，跑通之后你对 Skill 的理解会有一个质的飞跃，再去看其他类型就轻松多了。

4.2 判断一个Skill是否值得用的四条标准

面对 GitHub 上越来越多的 Skill 仓库，你不可能每个都装进本地目录，装多了反而是负担。我建议你用这四条标准快速过滤：

1. 看 description 是否具体：如果 description 写得很泛，这个 Skill 大概率不好用，因为模型不知道该什么时候触发它。
2. 看文件是否拆解：好的 Skill 会把大段内容拆成辅助文件，而不是全部堆在一个超长的 SKILL.md 里。
3. 看是否有输出模板：有模板意味着作者认真考虑过“模型产出的结果应该长什么样”。
4. 看 issue 区：如果作者在持续维护、回复问题，这个 Skill 的生命力会更强；如果长期不更新且 issue 无人回复，谨慎使用。

这四条标准帮我避开了不少“看起来很酷但实际没用”的仓库。尤其是第一条，几乎可以过滤掉一半以上的低质量 Skill——很多人只是把一段提示词包装成 SKILL.md 就发出来了，根本没考虑过触发机制。

4.3 从开源Skill改造成自己的

拿到一个开源 Skill，我不建议直接复制粘贴到自己的目录里当成品用。更合理的做法是：先读一遍SKILL.md，理解作者的思路，然后结合自己的项目规范做调整。比如开源 Skill 里审查的是通用前端代码规范，但你的团队有自己的 ESLint 规则和命名约定，那就把这些内容补充到正文或者辅助文件里。这样得到的 Skill 才是真正适合你的。

另外一个容易忽略的点：开源 Skill 的描述可能和你的工作流不完全匹配，这时候就要修改description，补充你常用的触发词。比如团队里习惯说“帮我看下这个 MR”，那你就在 description 里加上“MR”这个关键词。实测下来，触发词的本地化是 Skill 改造里性价比最高的操作。这个过程不会超过十分钟，但效果差异非常明显——模型从“偶尔想起来用”变成“一遇到就说就触发”。

5. 常见问题与排查经验

5.1 Skill没有被自动加载

这是最多人遇到的第一个问题。现象是 Skill 已经放进目录了，但对话时模型完全不知道它的存在。排查顺序一般是：先确认目录路径是否正确——项目级是.claude/skills/，全局是~/.claude/skills/；再确认SKILL.md文件名是否大小写完全正确；最后确认 YAML frontmatter 格式是不是标准的三横线开头。这三个地方任何一个出错，Skill 都可能静默失效，而且 Claude Code 不会报错。

我整理了一个更直观的速查表，方便你对照排查：

5.2 触发了不该触发的Skill

另一个常见问题是“负触发”——不该调用 Skill 的时候它跳出来了。这几乎都是description写得太宽泛导致的。比如你在 description 里写了“帮助用户解决代码问题”，结果任何代码相关的对话都会触发它，甚至在用户只是闲聊技术话题时也会强行加载。解决思路是给 description 增加更严格的限定词，比如“仅当用户明确要求进行代码审查时使用”，并列举出哪些场景不适合触发。

这类问题我建议在写完描述之后做一个简单的自测：把 description 单独拿出来读一遍，问自己“如果我是模型，一个什么样的任务会让我想加载这个技能？”如果答案不清晰，说明描述还需要收紧。

5.3 与CLAUDE.md的冲突处理

如果项目根目录的CLAUDE.md里已经写了一套审查流程，而 Skill 里又定义了另一套，模型会面临指令冲突。我的经验是：CLAUDE.md里只写项目的全局约定和约束，把操作层面的标准化流程尽可能交给 Skill 去承载。如果两者确实存在重叠，建议在CLAUDE.md里加上一句“代码审查请遵循 code-review Skill 的流程”，把这个优先级明确写出来，模型就不会左右为难了。

这个“全局约定 + 按需技能”的组合，是我目前觉得最稳的用法。全局文件保持轻薄，技能文件负担执行细节，两者各司其职，冲突自然就少了。

5.4 Skill变多之后会不会拖慢速度

我刚开始大量收集开源 Skill 的时候，也担心过目录里堆了几十个 Skill 会不会让每次对话都变慢。实际用下来发现，Claude Code 对 Skill 的加载是延迟的——它先扫描目录建立索引，再根据当前任务匹配描述，只有匹配上的 Skill 才会真正进入上下文。所以 Skill 数量本身不会直接拖慢速度，真正影响速度的是：多个 Skill 的 description 写得过于相似，导致一次任务匹配到了好几个，然后被一起加载。整理 Skill 的时候，我会刻意避免两个 Skill 的描述高度重叠，这是保持响应速度的关键。

最后分享一个我在实际使用中养成的习惯：每个 Skill 我都会在首次落地后用两到三个真实任务做验证，跑完立刻回到SKILL.md里改措辞。Skill 跟代码一样，第一版永远不是最优解，它是靠一遍遍迭代打磨出来的。另外一个小技巧是，给 Skill 的辅助文件加日期版本号，这样改过之后能快速定位到自己维护到哪一版，也方便回溯。Skill 这套机制最迷人的地方在于，它把“人的经验”变成了“可复用的流程”，而这恰恰是团队合作里最值钱的东西。