企业官网建设流程全解析

从去年开始大量使用 Claude Code 跑项目以来，我攒了不少 Skill（技能包）。这东西说白了就是给 Claude Code 插上一组“行为模板”，让它在特定场景下不用你反复交代，直接按预设的方法论干活。去年底做了一轮大清理，把几十个 Skill 精简到 17 个真正高频使用的，整理成了清单和一键安装脚本。今天把这套东西完整拆一遍，包括 Skill 机制的原理、17 个包的筛选逻辑、安装方式、以及我踩过的坑，适合刚从 Cursor 或裸 Claude Code 切换到 Skill 工作流的同学参考。

1. Skill 机制：先搞懂 Claude Code 的技能包是什么

1.1 从“会聊天”到“会干活”：Skill 设计逻辑

很多人第一次接触 Skill 时容易把它理解成“提示词模板”，这个理解方向对，但不完整。Skill 是一组带结构化元数据、带文件环境、按需触发的指令包，它不仅仅是告诉 Claude“你要怎么做”，还告诉它“你在什么条件下可以调用这套做法”。

Claude Code 本身是一个终端里的 AI 编程代理，它天然具备读文件、写文件、执行命令的能力。但它默认的“行动方式”是通用的——遇到一个问题，它用通用的推理路径去解决。Skill 的意义在于把某一类高频任务的处理流程固化成标准操作，Claude Code 读到相关关键词或你主动指定时，就会加载这段指令，按照里面的步骤、规范、示例去执行。

举个例子，我写代码时经常要生成 API 文档。裸 Claude Code 需要我每次输入“请分析 src 目录下所有路由文件，提取参数，按照 xx 格式生成 Markdown 文档，中文输出，放在 docs 目录”。装上文档生成 Skill 之后，我只需要说“生成 API 文档”，Claude Code 会自己加载 Skill 里的流程：先扫描目录结构，找路由定义文件，读取注释和类型定义，按预设模板输出。传统提示词是“你每次教我怎么做”，Skill 是“我把 SOP 写好，你按 SOP 来”。

1.2 Skill 与 Agent 不是一回事：核心差异对比

热词排行榜里“skill 和 agent 的区别”排得很靠前，说明确实有大量用户混淆了这两个概念。一个常见的误区是：Skill 和 Agent 都是“给 Claude 加能力”，那它们是不是同一种东西换了名字？不是。

简单说，Skill 是“流程化的操作手册”，Agent 是“能自主运行的角色实例”。你加载一个 Skill，Claude Code 还是同一个会话，只是临时学会了某套标准动作；你启动一个 Agent，则是在主对话之外开辟一条独立的执行线，有自己的目标、工具权限和循环逻辑，跑完再把结果汇总回来。

实操中我的体会是：

• 如果你要的是“把某类任务标准化”，例如统一文档格式、统一代码审查流程，用 Skill 更轻，不占额外上下文，也不会把执行过程变成黑盒。
• 如果你要的是“让我并行去调研一个技术栈，出一个评估报告”，这种有明确目标、需要多轮工具调用、多层推理的任务，才值得上 Agent。

另外，Skill 的一个重要特性是按需加载。Claude Code 会在每次对话开始扫描所有 Skill 目录，但不是一口气把所有内容塞进上下文，而是根据对话内容动态匹配，匹配到了才读取对应 Skill 的完整指令。这一点非常关键，我会在第 3 节细说。

1.3 Skill 在 Claude Code 里的真实工作流程

为了让第 2 节的清单和第 3 节的安装教程更好理解，这里先讲一下 Skill 的加载链路。

Claude Code 会读取一系列目录（分全局和项目级，下面会详细讲），每个 Skill 是一个独立的文件夹，里面必须有一个SKILL.md文件。这个文件的开头是一个 YAML 格式的 front-matter，里面写name和description；description的作用类似“索引标签”，Claude Code 用对话中的语义去匹配这些标签，命中后会把整个文件内容作为指令注入。

整个流程可以概括为：

1. 用户发起对话或切到某个任务上下文
2. Claude Code 对已有 Skill 的description做语义相关性匹配
3. 命中一个或多个 Skill 后，加载对应的SKILL.md
4. Skill 内的指令开始约束 Claude 的后续行为，比如指定先做哪个步骤、调用哪些命令、输出什么格式
5. 任务结束，Skill 的约束自动失效（除非该 Skill 设计为常驻）

这个机制带来的好处是：你的上下文不会被无关技能占用。装了 17 个 Skill，平时对话的不见得会全读进去，只有任务相关时才会加载，这对 token 消耗和数据隐私都是友好的。

2. 17 个值得装的 Skill 清单：选型思路与推荐

2.1 我的筛选标准：为什么从几十个里只留 17 个

我最早装 Skill 是“看到推荐就装”，结果装了三四十个。典型症状是：Claude Code 启动变慢、匹配混乱、同一个任务同时命中三四个 Skill 导致行为冲突。后来我定了几条筛选标准，凡是不满足的都删了：

• 必须是高频场景——我的日常工作是前后端开发、文档撰写、配置调优、脚本编写，凡是年使用次数不超过 5 次的 Skill 一律不装。
• 必须有明确的格式约束或流程约束——如果这个 Skill 只是“提示词废话”的包装，那没有任何价值。
• 必须能独立验证效果——装完必须能在我的真实项目里跑一次，效果不行立刻卸载。
• 必须控制依赖体积——某些 Skill 要下载几百兆的模型或工具链，我直接不碰，因为会影响日常启动速度。

基于这几条，最后留下了 17 个，按用途分成四类：通用编码效率、文档与知识管理、配置与环境、专业垂直场景。

2.2 效率类：把重复劳动压缩到一次指令

这类 Skill 的目标很纯粹，就是把那些“每次都要重新描述一遍”的工作固化下来。我自己留下 4 个：

Code Reviewer（代码审查）：团队代码合并前的审查流程，这个 Skill 会按预设规则检查变更文件：是否有明显的逻辑错误、异常未捕获、硬编码密钥、未处理 null 值、是否缺少测试覆盖。最让我满意的是它的输出格式很稳定，每次都是一张问题清单表，按严重级别排序，附文件行号和修改建议。后来我把公司的编码规范也改进了 SKILL.md 里，等于把团队规范直接“移植”给了 AI。

Refactor Helper（重构辅助）：这是我最常用的一个。它内置了“先理解变更影响面，再拆小步重构，每步可验证”的流程，而不是一上来就重写整个文件。装上之后，我每次说“帮我重构这个模块”，它就自动先画出模块依赖情况，列风险，然后要求我确认再动手。这一点太重要了，裸 Claude Code 容易“热情过度”一把梭，重构完直接改坏一片。

Git Workflow Pro（Git 规范工作流）：这个对多人协作特别有帮助。它把提交信息格式、分支命名规范、冲突处理顺序都固定下来了。我经常让它“根据当前改动生成提交信息”，它会先跑git diff --stat和git diff看变更内容，再按规范生成，而不是凭空猜。用过之后，我再也没手写过提交信息。

Debug Detective（调试侦探）：完整的错误排查链路：先复现、再缩小范围、构造最小复现用例、二分定位、最后才提修复方案。它有个好处是排查过程保留日志，方便回溯。对于 Node.js 和 Python 项目的报错信息，它还会主动建议用哪个调试器。

2.3 专精类：垂直场景下的开箱即用

这类 Skill 覆盖面比较广，也是最能体现“Skill 价值大于提示词”的地方，因为它们的内部指令往往包含非常专业的操作步骤。

API Doc Generator（API 文档生成）：前面提过，专门用于扫描代码里的路由和类型定义，生成结构化的接口文档。它能自动读取 OpenAPI 注释、JSDoc 或 Python docstring，同步到 Markdown 文件。我的一个旧项目有 300 多个接口，之前手写文档耗时一周，用这个 Skill 一个晚上就出来了，虽然有些描述还需要人工润色，但骨架完全可用了。

DB Schema Manager（数据库结构管理）：这个我主力用于迁移脚本生成和表结构评审。它会先读取现有 models 或 migrations 目录，理解当前 Schema 状态，再生成需要的迁移文件，而不是凭空创建。听起来简单，但很多裸 Claude Code 生成的迁移脚本经常直接冲突，这个 Skill 带“先读后写”的约束，冲突率明显下降。

Book to Skill（把书籍方法论转成 Skill）：这个挺有意思，它的用途是“把一本技术书的核心方法论，变成一个可执行的 Skill”。我看完《重构》之后用这个工具把书中“坏味道清单”和“重构手法索引”注入一个自定义 Skill 里，以后代码审查的时候 Claude 会自动用书里的标准来检查。这个方法强烈推荐，等于把你读过的书“实体化”成了工具。

WorkBuddy Skill（工作流打包）：这更像一个“元 Skill”，把多个子任务编排成一个完整工作流。比如“完成一个功能迭代”，它内部会拆解出：分析需求 -> 设计接口 -> 实现 -> 写测试 -> 更新文档。适合那些经常需要按同一套流程走完的完整任务。

PPT Skill（演示文稿生成）：专门负责把 Markdown 大纲转成结构清晰的演示文稿。它的流程是先确认大纲逻辑，再逐页填充内容，而不是一次性吐出一堆没有层级的文本。配合导出工具链，效率提升非常明显，但要注意它本身只负责内容组织，最终样式还需要你在导出工具里微调。

还有一类就是像Unity Skill Attack Indicators（游戏开发战斗指示器）这种游戏开发垂直场景，数学建模 Skill、STM32 嵌入式开发的 Skill、倪海厦医疗知识库这类知识问答型 Skill，都属于“特定人群高频使用”的典型，这里不展开，但你按自己的领域搜索关键词，大多能找到成熟版本。

2.4 避坑提示：同名 Skill 在不同仓库可能有完全不同的行为

这是我在清理那三四十个 Skill 时发现的最大坑：同类 Skill 没有统一标准，同名 Skill 在不同作者手里可能完全是两套行为。

比如“code review”这个名字，我见过三种实现：一种只做静态检查，一种会主动运行测试，还有一种会调用外部 API 做语义分析。作者不同、数据来源不同、更新频率不同，效果天壤之别。

所以我不建议“谁火装谁”，而是看实现、看说明、看更新日期。安装前花两分钟读一下这个 Skill 的 SKILL.md 全文，想想它的触发方式是否合理、输出是否贴合你的使用习惯，比装完再试错高效得多。另外，不要一次装太多，我最终的 17 个清单是从几十个里面淘汰出来的，建议你也按上面那四条标准去做一轮“断舍离”。

3. 一键安装与手动部署：两种方式都讲透

3.1 一键安装脚本：适合复制到新环境

受益于 Skill 目录结构的统一性，批量安装并不复杂。我先解释一下 Claude Code 的目录约定：

• 全局 Skills 目录：在用户配置文件下，所有项目都能访问
• 项目级 Skills 目录：在.claude/skills下，只对当前项目生效

社区里大部分 Skill 都是直接放在 GitHub 仓库里的，每个 Skill 一个独立文件夹，内含 SKILL.md 和可能的辅助脚本、模板文件。安装的本质就是把这些文件夹拷贝到 Claude Code 的 Skills 目录里。

下面是我自己维护的安装脚本（Linux/macOS 下运行）：

#!/bin/bash # 17 个 Skill 一键安装脚本 # 用法: ./install-skills.sh 或 bash install-skills.sh SKILLS_DIR="${HOME}/.claude/skills" mkdir -p "${SKILLS_DIR}" # 仓库映射表：名称 -> GitHub 仓库地址 declare -A REPOS=( ["code-reviewer"]="https://github.com/example/skill-code-reviewer.git" ["refactor-helper"]="https://github.com/example/skill-refactor.git" ["git-workflow-pro"]="https://github.com/example/skill-git-workflow.git" ["debug-detective"]="https://github.com/example/skill-debug-detective.git" ["api-doc-generator"]="https://github.com/example/skill-api-doc.git" ["db-schema-manager"]="https://github.com/example/skill-db-schema.git" ["book-to-skill"]="https://github.com/example/skill-book-to-skill.git" ["workbuddy-skill"]="https://github.com/example/skill-workbuddy.git" ["ppt-skill"]="https://github.com/example/skill-ppt.git" ["math-modeling"]="https://github.com/example/skill-math-modeling.git" ["stm32-dev"]="https://github.com/example/skill-stm32.git" # ... 其余 6 个省略 ) for name in "${!REPOS[@]}"; do target="${SKILLS_DIR}/${name}" if [ -d "${target}" ]; then echo "[跳过] ${name} 已存在" continue fi echo "[安装] ${name}" git clone --depth 1 "${REPOS[$name]}" "${target}" done echo "全部处理完成。重启 Claude Code 会话后生效。"

这个脚本的核心逻辑很直白：定义一个仓库映射表，遍历仓库地址，git clone到 Skills 目录。用--depth 1是为了只拉取最新代码、不拉历史记录，对于安装 Skill 来说完全够用，还能省时间。

3.2 手动安装：理解目录结构才能长期维护

一键脚本方便，但它隐藏了很多细节，一旦遇到问题你可能不知道从哪排查。所以我建议至少手动装过一次，把目录结构搞清楚。

假设你想手动安装一个名为my-skill的 Skill，步骤如下：

1. 创建目录：~/.claude/skills/my-skill/
2. 在目录里创建SKILL.md文件（这是唯一必需的文件）
3. 如果有辅助脚本或模板，放到同目录或子目录，并在 SKILL.md 中用相对路径引用
4. 重开 Claude Code 会话，让新 Skill 被扫描到

一个最小可用的 SKILL.md 长这样：

--- name: my-skill description: 用于生成项目周报。当用户要求生成周报、项目进度总结时使用。 --- # 项目周报生成 ## 任务目标 根据 git log 和项目备注生成结构化周报。 ## 执行步骤 1. 运行 `git log --since="7 days ago" --oneline` 获取本周提交记录 2. 按模块分类整理提交记录 3. 用以下模板输出周报： - 本周完成 - 当前风险 - 下周计划 ## 输出格式 使用 Markdown 表格，中文输出。

注意description里这句“当用户要求...时使用”，这就是触发条件。Claude Code 靠它做语义匹配，所以这句话写得越具体，匹配越精准。如果写得过于宽泛（比如“用于帮助用户”），任何对话都可能触发它，反而干扰正常聊天。

3.3 参数选择背后的逻辑：为什么推荐软链而不是复制

前面脚本用的是git clone直接复制，实际上在我的长期工作流里，对那种还在频繁更新的 Skill，我更推荐软链接方式。

原理很简单：git clone之后目录是独立的，上游仓库更新了，你要重新拉取；如果用软链指向你自己的一个 git 仓库，每次上游更新只需要git pull，甚至可以用定时任务自动同步。

具体做法：

cd ~/workspace/skill-repos git clone https://github.com/example/skill-code-reviewer.git code-reviewer ln -s ~/workspace/skill-repos/code-reviewer ~/.claude/skills/code-reviewer

这样你维护的是仓库本体，Claude Code 目录里看到的只是一个链接。好处有两个：一是跨机器同步时只需要同步你的仓库集合，二是你自己改过的 Skill 内容不会因为重装系统被抹掉。

但软链有一个注意点：Claude Code 扫描目录时对“符号链接”的支持依赖各版本实现，有些版本对软链目录的递归扫描会出问题，表现为 Skill 不生效。所以如果你第一次装完发现没生效，先把软链换成真目录试一次，不要直接调试半天。

3.4 Windows 和 VSCode 环境下的差异

热词里“vscode 配置 claude code”“windows claude code cc-connect 飞书”这些都反映出 Windows 用户不少。Windows 上的目录路径和 macOS/Linux 差异很大，默认的全局目录通常在C:\Users\你的用户名\.claude\skills。在 PowerShell 里安装时，ln -s不可用，需要手动建目录或者用New-Item -ItemType SymbolicLink。

另外，如果你主要用 VSCode 里的 Claude Code 插件，记得 VSCode 可能有自己独立的扩展配置目录，Skill 不一定从系统 CLI 的~/.claude读取。这时最简单的方式是：直接问 Claude Code 当前读取的 skills 路径——它可以通过环境信息获取，或者你检查工作区下的.claude/skills，这是项目级目录，两边都会认，最稳妥。

4. 从用到写：如何写一个自己的 Skill 并调试

4.1 SKILL.md 的结构：YAML 头 + Markdown 正文

如果你想更深入使用 Skill，迟早会想写一个自己的。不用怕，这可能是 Claude Code 所有自定义能力里最容易上手的一种——它的本质就是“一份有格式的 Markdown 文件”。

SKILL.md 分为两大部分：YAML front-matter 和 Markdown 正文。

YAML 头只包含两个关键字段：

--- name: 技能名称（唯一） description: 一句话描述这个技能做什么，以及什么场景下触发 ---

正文部分是技能的核心内容，可以包含：

• 任务目标：一句话说明这个技能要解决什么问题
• 适用场景：在什么条件下使用、什么条件下不使用
• 执行步骤：按顺序写清楚操作流程，代码、命令行、文件操作都行
• 输出规范：明确输出的格式、保存位置、命名规则

这里有一个非常重要的经验：正文里不要写抽象描述，要写可执行的步骤。比如“检查代码质量”这种描述是无效的，“运行 eslint --ext .js src/ 并处理 error 级问题”才是有效的。Claude Code 的推理能力很强，它会执行你的指令，你写得越具体，它执行得越稳定。

4.2 编写过程的几个关键设计

我踩过很多次坑之后，总结出一个“编写自己的 Skill”的常用框架，尤其是写完那套 Book to Skill 的过程让我彻底想通了这个逻辑：

1. 先确定触发场景和排除场景：这个 Skill 是要“用户主动指定”还是“自动匹配”触发，决定description的措辞。如果是自动匹配，描述里要把边界写清楚地“不适用的场景”也要写，否则任何沾边的话题都会触发，就成了噪音。
2. 写步骤时脑子里走一遍 Claude 的执行链路：它看到你的步骤，第一步会做什么、会读取哪些文件、命令是否真的存在。写完之后，你自己先手动模拟一遍这个流程，如果中途有卡点，说明步骤还不够完整。
3. 给输出设定固定格式：用模板、用表格、用固定小标题，这决定了输出质量是否稳定。我见过大量 Skill 输出风格飘忽，今天写分析、明天写结论，就是因为没有格式约束。
4. 外部资源引用要相对路径：如果你在 Skill 中提到了辅助脚本或参考模板，路径要相对于 Skill 所在目录写，不要写绝对路径，否则换个机器就失效。

然后是调试。写完之后直接新起一个对话去触发它是最直接的验证方式。启动一个全新会话，输入触发词，看它是否加载了预设步骤。如果没加载，多半是description写得太泛或太偏；加载了但行为不符，就打开 SKILL.md 调整正文步骤，重新开一个会话再试。调 Skill 和调试业务代码一样，要一次只改一个变量。

4.3 调试技巧：如何快速验证 Skill 是否被正确加载

有些读者可能已经装了 Skill，但不确定它到底有没有在生效。我提供一个快速排查方法：

1. 开一个新的 Claude Code 会话
2. 直接输入“你当前加载了哪些与 xx 相关的技能？”
3. 如果 Claude 回答中包含你安装的 Skill 名称并复述了它的步骤，说明加载成功
4. 如果回答中说“没有相关技能”，问题出在目录结构或description匹配

还有一个排查方向是看日志。Claude Code 的调试模式下会输出很多内部状态，包括 Skill 扫描和加载的过程。在命令行按Ctrl+Shift+D之类的调试快捷键（不同版本入口略有差异），可以看到它到底扫了哪些目录、匹配到了哪些描述。这个手段很底层，但对于那种“玄学不生效”的问题，一查一个准。

实际使用中，我遇到过最离谱的情况是：项目根目录下有个旧版的.claude/skills/code-reviewer，同时全局目录也有一个，两个同名 Skill 同时存在，结果 Claude Code 加载了旧版本。解决方式是优先保证项目级目录干净，或者全局目录与项目级目录不要同时放同名 Skill。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

5.2 三个值得单独说的重复踩坑

第一个坑是“Skill 互相覆盖”。最典型的场景是同时装了“文档生成类”和“注释规范类”两个 Skill，都有“读取并修改代码”的指令。跑同一个任务时，两个 Skill 的规则打架，Claude 一会儿按这个风格写注释，一会儿又按另一个风格改回来，输出质量很差。解决方式我已经在前面提过，控制数量 + description 明确边界。现在我只有 17 个，但真正在同一次任务中被同时触发的，通常不超过 2 个。

第二个坑是“调整后用旧缓存”。你改了 SKILL.md 的内容，但 Claude Code 依然按旧行为跑，这是因为长会话里 Claude 可能缓存了加载过的指令。我的经验是调整后不要贪图省 token 继续旧会话，直接开新会话，否则你会产生“改了没用”的错觉，然后反复乱改。

第三个坑是“对 Skill 期望过高”。Skill 不是外挂，它只是改变了 Claude 的“行为方式”，不能凭空增强它的智力。如果你让数学建模 Skill 去解决一个连你自己都说不清楚的建模问题，结果依然不会好。Skill 的价值在于“把好的工作方法编程化”，而不是“把不可能变成可能”。认清这点，你对 Skill 的投入产出比判断会更准确。

5.3 我留 17 个而不是 17 个“最好”的原因

最后再说一点选型上的个人体会。很多人问我“你的 17 个是不是网上最好的一批”，我的答案很直接：没有最好的 Skill，只有最匹配你工作流的 Skill。

比如我长期写文档和做知识管理，所以文档类 Skill 占比高；我做全栈开发但很少碰游戏，所以游戏开发类 Skill 再火我也不装；我做单片机相关的项目频次低，STM32 的 Skill 装了也属于摆设。我的 17 个清单本质上是“我过去半年真实工作流的缩影”，你直接照搬回自己电脑，效果未必好。

更建议的做法是：从我这里的 17 个里挑 10 个和你的工作相关度最高的装上，用一周看效果；再根据你的实际场景，从社区里补上你的专属高频场景 Skill；最后按第 2 节那四条标准筛一轮，留下自己的 12~15 个。这个过程比抄任何清单都有意义，因为只有自己筛过的清单，你才知道每个 Skill 什么时候该用、什么时候不该用。

就以我自己的体会来收个尾：Skill 的机制真正改变的不是“AI 能做多少事”，而是“好方法能被固化和复用”。就像老师傅手上那本翻烂了的笔记，上面的每个步骤都是无数次试错后的沉淀。把这套东西用好，你会发现同样的 Claude Code，装不装 Skill、怎么装，完全是两种体验。