企业官网建设流程全解析

Claude Code 的 Skills 这个能力，我是从把长段指令堆进 CLAUDE.md 开始吃透的。过去每次新开一个项目，都要把一套提示词模板复制过去，复制得多了，维护就开始失控，改一个规则得同步好几个仓库，漏一处就是一次不稳定的体验。后来真正开始用 Skill，尤其是把“项目级”和“全局”这两种安装方式搞明白之后，才意识到它解决的不只是反复复制的问题，而是让指令本身变得有结构、有归属、可管理。这篇就围绕怎么装、怎么从项目级切换成全局来写，把底层逻辑和实际操作的弯路一并讲清楚。

我会先解释 Skill 的组成和它跟 CLAUDE.md 这类普通指令文件的区别，再讲项目级怎么落地，接着重点拆解切到全局的几种方式和适用场景，最后用一个完整的实践案例加问题排查来做收尾。如果你已经在每次对话前把一长串规则贴进去，或者正在为“这堆技能到底放哪”发愁，这篇文章应该能帮你省不少时间。

1. 理解 Skill 的本质与文件结构

1.1 什么是 Claude Code 的 Skill

如果你把 Claude Code 本身看成一个“能看懂项目并帮你写代码”的执行者，那 Skill 就是它的能力包。一个 Skill 本质上是一个目录，目录里有一份核心说明文件 SKILL.md，外加可选的支持文件，比如模板、脚本、示例、参考文档。每次打开 Code 的时候，它会扫描两个维度下的技能目录，把描述信息加载进来，等到对话里出现匹配场景，技能就会被激活，指导模型按其中定义的流程去落地。

这里容易有一个误区：Skill 不是插件机制，也不是独立的代码快速执行规则文件。它更像是“给模型的一份带前置条件和流程约束的操作手册”。Skill 里的内容并不决定模型会不会写代码，而是在模型已经具备能力的前提下，规定它用什么顺序做、做什么检查、按什么风格输出，以及要避免什么坑。

1.2 SKILL.md 的核心结构

一个标准的 Skill 我通常以这种方式组织：

my-skill/ SKILL.md templates/ scripts/ examples/

SKILL.md 是入口。它的开头有一段 YAML 格式的 frontmatter，里面最核心的两个字段是 name 和 description。description 的作用比大多数人以为的大得多，后续会专门展开，现在就记住一句话：它是技能被选中的路由条件，写得太宽泛，模型就容易在无关场景里用它。

正文部分是 Markdown，写清楚这几类信息：

• 技能在什么情况下被激活、产出什么结果
• 执行步骤，建议用编号列出，保证顺序稳定
• 对已有代码或配置不得改动哪些部分
• 输出格式规范、检查清单，以及常见的兜底处理

一个重要的建议是，不要在 SKILL.md 里写“你是一个 XXX 专家”这类空泛的角色设定，而是写“在执行任务时优先使用哪些方法、按什么顺序执行”。前者没有操作约束力，后者才能真正改变每次运行的表现。

1.3 Skill 和 CLAUDE.md 的差异

很多人会问，既然 CLAUDE.md 也能写规则，为什么还要单独搞 Skill？它们最大的差异在触发机制。CLAUDE.md 是每次会话都会自动加载，等于模型的默认背景音，什么任务都会带上；而 Skill 是靠描述被按需调用的，平时只占用一句描述信息，真正执行时才把整份手册交给模型。

这个区别直接影响指令维护的方式。放进 CLAUDE.md 的规则要短，要普适，否则无关任务比重太高，既浪费上下文，又会让响应风格变得拖沓。放进 Skill 的内容则可以把场面铺大，步骤、细节、边界条件都可以写足，因为它只会在需要时被展开。

从另外一个角度看，CLAUDE.md 更像是“团队的开发公约”，而 Skill 是“特定场景的专项工作手册”。如果你发现自己写了很多带条件前缀的规则，比如“如果要重构某个模块，请先做 X”，这种就是典型的该拆成 Skill 的内容。

2. 项目级 Skill 的安装与使用

2.1 一步步搭一个项目级 Skill

项目级的安装路径很容易确认。在项目根目录下创建 .claude/skills 目录，把一个 Skill 放进去，就能让这个项目内的所有会话看到它。

mkdir -p .claude/skills/docs-format cd .claude/skills/docs-format touch SKILL.md

里面的具体内容，也可以用 Claude Code 自己生成，把需求描述清楚让模型帮忙起草。我第一次搭的时候，直接手工写了一个文档格式 Skill，结果走了不少弯路；后来改成让它先输出草稿，自己再做一轮删改，效果好得多。

把 SKILL.md 填好之后，重启一个会话，可以在对话中直接尝试触发它，确认是否能被识别。一个注意点是，会话中途新增或修改了 Skill 目录，当前会话不一定能立刻加载到，重启会话是最稳妥的验证方式。

2.2 检查已生效的 Skill

想确认当前项目加载了哪些 Skill，可以查看配置文件。Claude Code 会维护一份加载清单，列出项目级和全局有效的技能。用命令查看属于最常见的做法：

claude config get skills

输出里能看到每个 Skill 的路径来源，是项目级还是全局项一目了然。这里有个判断优先级的问题：项目级和全局如果出现同名 Skill，一般情况下项目级会覆盖全局。规则很简单，越靠近项目、越贴近具体上下文的配置，优先度越高。遇到同名冲突，优先检查是不是项目目录里残留了一份旧版本，这是最容易被忽略的坑。

2.3 为什么先从项目级开始

我强烈建议，凡是新写的 Skill，第一站都放到项目级。原因不是项目级更方便，而是它给了你足够的试错空间。Skill 是会被模型反复执行的操作手册，一旦有流程或描述错误，影响面非常广。

放到某个具体项目里后，先跑两三个真实任务，观察输出的稳定程度。如果这个 Skill 会让每个任务的执行时间变长、或者导致模型过度解读步骤，当场就能察觉。另外，项目级天然适合和当前仓库的代码风格绑定验证，比如代码审查类技能只有放到真实代码仓库里，才有足够的样本来检验它的规则是否合理。

等它在真实项目里稳定运行了，再考虑是否纳入全局。

2.4 项目级 Skill 的团队协作

项目级还有一层价值是它可以进版本库。.claude 目录提交到仓库后，团队所有成员拉下代码就能获得同样的技能配置，不需要单独分发。

这里要提醒一点：既然是团队共享，里面就不要写个人风格太强的要求，比如“换行统一用两行空行”这种无关痛痒的偏好，写多了反而容易让模型输出变得死板。真正该放的是对质量有实质影响、团队一致认可的约束，比如安全规则、命名约定、必须执行的检查步骤。

如果某个 Skill 包含带保密性质的内容，比如内部工具的使用方式、线下服务的连接方式，要谨慎评估能不能进仓库。团队内部使用通常没问题，但如果项目开源，技能目录也会被一并公开，提前清理敏感信息是必须做的。

3. 从项目级切换到全局的完整流程

3.1 全局 Skill 的存放位置

切换的第一步是先搞清楚全局在哪。在常用的 Claude Code 目录结构中，全局 Skill 放在用户主目录下的 .claude/skills 目录。以 Unix 类系统为例：

mkdir -p ~/.claude/skills

这个目录里放置的每个 Skill 会对该用户所有项目生效，不需要在项目根目录重复摆放。

需要留意的是，“全局”不等于“每个项目”。它指的是用户账户级别，从这个维度理解，你在这个机器上开启的任何会话都能感知到它。

3.2 用配置命令把项目级技能加到全局

最常见的做法是直接修改配置，把当前项目里的技能路径注册到全局范围。在 Claude Code 中，这类操作一般通过 config 相关子命令完成：

claude config add -g skills ~/.claude/skills/my-skill

-g 的含义就是全局。执行完这条命令后，新开的任意项目会话都可以使用对应技能。

如果想移除某个已加载的技能，使用对应删除命令：

claude config remove -g skills my-skill

具体的命令名称根据版本不同可能有差异，运行claude config --help或者直接看补全提示就能获得准确写法。我更想强调的是操作思路：它本质上是维护一份技能清单文件，命令只是修改这份清单的快捷键，理解了底层是文件配置，排查问题时就不会被命令参数带偏。

补充一个细节，配置全局技能时不一定要求这个路径本身就挂在 ~/.claude/skills 下。理论上你可以把特定项目里的技能路径直接注册为全局项，只要该路径在启动时会保持稳定存在。但从维护角度，我依然建议按默认约定把文件放到全局目录，路径统一，未来盘技能列表更清楚。

3.3 手动迁移的常规步骤

如果不用配置命令，手动把技能目录挪到全局目录也是可行的，操作路径如下：

1. 确认源目录结构和内容完整，特别注意 SKILL.md 是否存在且格式正确
2. 复制目录到全局技能目录，比如：

cp -r .claude/skills/xxx ~/.claude/skills/

3. 在项目配置中移除该技能的项目级注册，避免同名覆盖导致后续更新不生效
4. 开启一个新项目或新会话，查看 config get skills 的输出，确认全局项已被识别

手动搬运很简单，但它有一个我踩过几次的坑：内容同步。项目级那份和全局那份如果都保留，后续在任一位置更新了 SKILL.md，另一个位置会变成旧版本，下次排查问题就会出现“明明改了却没用”的困惑。所以，如果决定迁到全局，就要彻底从项目里清除它，不要留双份。

3.4 用软链接替代复制，实现单点维护

如果你希望技能先全局生效，但还要保留在项目的维护入口，推荐用软链接的方式来做单点维护。先在全局目录放一份源技能文件，再在项目目录做一个软链接指向它。

ln -s ~/.claude/skills/xxx ./.claude/skills/xxx

这样做的好处是只维护全局路径那一份，项目里的链接永远指向同一份文件。对于跨多个项目复用同一技能、且每个项目都希望有本地引用入口的场景，这个方案非常顺手。

缺点也很实际：软链接放进版本库后，团队其他人拉下来时链接可能无效，因为你机器上的绝对路径在别人那里不一定存在。个人使用很香，需要团队共享时还是得回归复制/手动装配的方案。

3.5 从项目级升级为全局的判断标准

什么时候该把一个项目级技能切到全局？我的判断标准很简单：当它在一个项目里已经验证稳定，并且它在另一个不相关的项目里同样适用时，就可以升级为全局了。

代码风格类技能通常不太适合全局，因为每个项目的风格约定差异很大；而通用的开发流程类技能，比如写规范的提交信息、按结构生成变更日志、做后台接口的冒烟测试，这些跨项目体验几乎一致，就非常适合全局。

还有一个反向经验：如果一个技能从全局切到某项目后反而表现变差，比如它要求检查的流程对当前项目不适用，不要急着改技能本身，先在当前项目里配置局部覆盖或者直接移除，保持全局版本不变，是最好的处理方式。

4. 实操案例：做一个跨项目可用的代码审查技能

有了全局和项目级切换的基础，接下来用一个实际案例把整个流程串起来。我以代码审查 Skill 为例，演示从零到全局部署的完整过程，这个类型也比较有普适性，不管你做前端、后端还是脚本，都能直接套思路。

4.1 设计 SKILL.md 的触发描述

h2 和大多数技能的失效问题，都出在触发条件写得不够精确。给这个代码审查技能写描述的时候，我是这样处理的：

--- name: code-review-lite description: 当用户需要审查代码变更、评估Pull Request中修改的逻辑正确性、检查边界条件和资源释放问题，或者要求逐行点评代码时使用。用于需要结构化审查意见的场景，不用于单纯解释代码。 ---

重点在后半句“不用于单纯解释代码”。这等于给模型一个负向拦截，避免你把代码贴进来问“这段怎么运行”的时候它反而启动审查流程，输出一堆跟提问无关的意见。

4.2 SKILL.md 正文的核心流程

正文我倾向用编号步骤来写，让模型限定在一个固定的执行序列里：

# 代码审查技能 你正在执行一次结构化代码审查。无论变更规模多大，始终按以下顺序执行： 1. 通读变更涉及的函数或文件，标出与本次改动直接相关的核心逻辑 2. 逐一检查边界条件：空值、超长输入、并发冲突、异常分支 3. 检查资源释放：打开的文件、临时目录、动态创建的连接是否都能正常回收 4. 检查错误处理：抛出的异常是否被合适的地方捕获，失败路径是否可观察 5. 按严重程度分类输出：阻断性问题、建议改进、可选优化 6. 输出以列表形式组织，每条意见对应到函数名和行号，不写泛泛而谈的评语 禁止： - 只写'代码写得不错'这类无信息量的评价 - 在没有理解完整改动意图时提修改建议 - 把代码风格调整纳入阻断性问题

用这个步骤跑下来，模型输出的审查意见稳定度高了很多。以前让它审查一段代码，它总容易直接开始改代码，给出几个优化建议；加了步骤约束之后，它会先做逻辑审查再给意见，关注的维度明显更完整。

4.3 在项目里试用和迭代

这个 Skill 我先在某一个内部项目里以项目级方式使用。前几次试下来有两个问题：一是模型把“检查资源释放”理解得过于宽泛，连普通数组遍历都开始提醒释放；二是有时候输出还是偏概括。

针对第一个问题，我在正文里加了“资源释放仅限主动申请资源的场景，例如文件句柄、网络连接、锁对象”，模型的理解立刻收敛。针对第二个问题，我把输出的强制格式改成“意见 = 位置 + 问题 + 影响 + 建议”，配合一个示例，效果也明显改善了。

这类调试在项目级做非常划算，因为影响面只有一个项目，内容怎么改都不用担心污染其他场景。

4.4 升级为全局技能

技能稳定之后，我把它注册为全局：

claude config add -g skills ~/.claude/skills/code-review-lite

这里有一个交互细节我最早没搞清楚：把技能路径注册到全局后，并不是当前所有旧会话立即生效，新建会话才会正确识别。如果你在一个会话中途想测试某个改动是否已感知，直接开一个新会话最省事。

我之后抽查了几个不同类型的仓库，发现这个技能在脚本项目和前端项目中表现基本一致，在个别框架项目里审查意见差异也主要来自项目上下文，而不是技能规则本身。这让我确定它适合留在全局。

4.5 从全局撤回项目级的反向流程

全局技能偶尔也会造成过度干预。我遇到过另一个技能，它包含的流程在某些项目里会改变模型响应结构，导致局部场景反而不好用。遇到这种情况不需要删掉全局技能，更合理的是在当前项目的配置里禁用或覆盖它。

操作和注册对等，把项目级配置指向空或换成项目专属版本即可。这种“全局默认、项目覆盖”的思路，才是实践中最灵活的搭配方式。

5. 常见问题与排查技巧

5.1 技能没生效怎么排查

技能配置好后完全没有被触发，这是出现频率最高的问题。先别怀疑模型，按照下面的顺序排查：

1. 确认目录结构符合规范，SKILL.md 直接放在技能目录下而不是嵌套在子目录里
2. 确认 frontmatter 里的 name 和 description 格式正确，没有多余的空行或字段
3. 在新会话中测试，避免旧会话没有加载
4. 用 config get skills 确认技能路径确实在加载列表中
5. 检查是否出现同名覆盖，项目级有一个同名旧技能压住了全局的新技能

这五步走完，大部分“不生效”的情况都能找到原因。我碰到最隐蔽的一次，是路径里多了一层目录，用的还是复制快捷方式导致的混乱，这类情况靠第一条检查就能抓住。

5.2 描述写得宽泛导致误触发

误触发比不触发更让人头疼。有一次我给一个文档生成类技能写描述时写了一句“帮用户写东西时使用”，结果模型把写提交信息、写邮件都判定为匹配场景，输出一套完整文档模板，完全牛头不对马嘴。

修正方式就是让描述可验证。不要写“需要帮助时使用”，而要写“当用户明确要求生成规范的技术设计文档、接口说明、或需要结构化 Markdown 输出时使用”。另外在描述里补上“不适用于日常对话、××类型任务”，能有效缩小触发范围。

5.3 全局多个技能之间互相干扰

技能越装越多，一个会话里同时匹配多个技能的情况就会变多。我的处理原则是唯一职责：一个好技能只干一件事，不要把多个流程塞进一个 SKILL.md。

如果已经出现两个技能职责重叠，比如一个管“生成测试用例”，另一个管“补充测试边界”，把它们的触发描述做严格区分，或者直接把边界描述写在各自的正文开头。还有个小技巧是在 description 中使用动词短语而非名词短语，比如“当需要生成单元测试时使用”比“单元测试工具”更容易被准确匹配。优先保证它们在互不重叠的场景中才被触发，不要设置那种听起来像总开关的宽泛技能。

5.4 隐私与安全注意

放到全局的技能里如果包含私密信息，比如内部系统的路径或鉴权方式，一定要谨慎。全局技能的加载范围覆盖所有项目和会话，这个范围看起来方便，泄露面也有多大。更合理的方式是，把这些内容放在项目级，必要时在项目级做注册或调用，避免把内部细节带进无关项目里。

5.5 多机器环境的同步建议

如果你有多台电脑，全局技能同步是一个值得规划的问题。我的做法是把整个 .claude/skills 目录纳入一份个人配置仓库，换机器时直接拉下来放到用户主目录下即可。

这一步做完以后，新机器只需要跑一遍配置命令，就能恢复所有技能。这里再补充一句：工具链的版本差异也可能影响技能加载，不同版本的解析规则可能存在细小差异，换了机器后先开一个新会话做冒烟测试，再正常开始工作，可以避免在关键时刻发现技能没装上。

6. 关于技能目录设计的几条实操心得

技能放哪、怎么放、放多少，实践后我有几条比较明确的体会。首先，技能数量宜精不宜多。那些真正能提升每次会话质量的，是我在多次项目里反复使用、逐步沉淀下来的少数几个。装了一堆技能但大部分时间段用不到，相当于给模型背上额外的描述信息负担，反而会带来噪声。

项目级的技能适合和服务场景强绑定。比如某个技能依赖特定项目的目录结构、命名规范、接口约定，这样的技能放到项目级里，团队成员共享时才不会产生冲突。

全局技能适合保存方法论层面的东西，比如代码审查、提交信息规范、文档生成、命令行工具的使用约定。它们不依赖具体项目上下文，抽象程度高，跨项目体验一致。

一个项目内的技能发现和排查，我还会微调目录结构，按功能模块组织子目录，把相关脚本和模板和 SKILL.md 放在同一个目录下，确保技能目录本身就是完整的、可独立搬运的。否则即使全局目录看到技能名称，运行起来依然会缺依赖。

最后，持续优化也很重要。技能不是写完就固定的，随着项目类型变化，同一个技能的规则随时可能需要调整。定期整理负担很重，容易越积越乱。我自己的习惯是每次使用时如果觉得输出里有一段结构明显的可以改进，就会顺手把地方标记下来，利用零散时间在项目级里做一次小版本更新，确认无误后再同步到全局版本。这套稳定的流程跑下来，技能库会一直保持可用状态，不会慢慢变陈腐。

把一个技能从项目级切到全局，真正的关键并不在于那一条命令怎么写，而在于你对“它属于谁”这个问题的判断。很多人的弯路是因为项目级和全局之间的边界没想清楚，装了用不上，删了又怕哪天需要。把技能按“项目专用”和“跨项目通用”分类，再配合目录和配置双向管理，Claude Code 的体验会有肉眼可见的改善。如果你正处在“项目里已经验证了一版 Skill、下个阶段要搬到全局”的节点上，希望这篇能给你一份不算曲折的路线图。