企业官网建设流程全解析

1. 从"技能仓库"到"能力装配线"：awesome-claude-skills 到底在解决什么

第一次看到awesome-claude-skills这个仓库名，很多人会下意识把它归类成"又一个 awesome 清单"——无非是收集一堆链接、按字母排个序、加个徽章就完事。但真正把 Claude Code 用进日常工作流的人会明白，这类仓库的价值根本不在"收集"，而在于它把散落在各处的技能（Skills）变成了可复用、可组合、可版本管理的能力单元。这两者之间的差别，就像"收藏夹里存了一堆菜谱"和"厨房里备好了切配好的半成品"——前者你得从头动手，后者下锅就能出菜。

先把概念对齐。Claude Code 里的 Skill，本质是一个带元数据的指令包，通常以目录形式存在，里面包含一份SKILL.md（描述这个技能干什么、什么时候触发、怎么执行），必要时还会挂上脚本、模板、参考文档等资源。它和 MCP（Model Context Protocol）不是一回事：MCP 解决的是"模型怎么连上外部工具和数据源"的协议问题，而 Skill 解决的是"模型在特定场景下应该按什么套路干活"的经验问题。打个比方，MCP 是给模型接上了电源和网线，Skill 则是告诉模型"这台设备在这个工位上该怎么操作"。两者配合，才能让一个通用 agent 变成某个垂直场景里的熟练工。

awesome-claude-skills这类仓库的核心贡献，是把社区里验证过的技能做了分类、去重、标注适用场景。它回答的是三个很实际的问题：我手上这个重复性任务，有没有人已经写好技能了？这个技能靠不靠谱、维护得勤不勤？我要自己写一个，应该照着什么结构来？对于刚接触 Claude Code 的人，它能省掉大量"从零摸索提示词结构"的时间；对于已经用了一段时间的人，它是查漏补缺、发现新玩法的入口。

这篇文章适合三类读者：一是刚装好 Claude Code、还不知道 Skill 能干嘛的新手；二是已经会写零散提示词、但想让它们工程化、可复用的进阶用户；三是团队里负责搭建 AI 工作流、需要一套可维护技能库的技术负责人。我会从技能的分类逻辑讲起，拆解一个 Skill 的目录结构和触发机制，然后给出自己写技能、调试技能、以及把技能和 MCP 组合起来的完整实操路径，最后聊聊这类仓库在实际使用中最容易踩的几个坑。全程按我自己的使用习惯来讲，不搞教科书那套。

2. 技能仓库的分类逻辑：为什么"按场景分"比"按字母分"重要

2.1 一个技能清单的可用性，取决于它的检索维度

我见过太多 awesome 清单死在"按字母排序"上。你打开一看，A 开头的一堆，Z 开头的一堆，想找"处理 PDF 的技能"得从头翻到尾。awesome-claude-skills这类仓库如果只是把技能名罗列出来，那它的价值会瞬间归零。真正好用的技能库，检索维度至少要有三个：任务类型（这个技能解决哪类问题）、触发场景（什么情况下会自动或手动调用）、依赖条件（需不需要额外的 MCP、API key、本地环境）。

拿实际例子说。一个"代码审查"技能和一个"提交信息生成"技能，从任务类型看都属于"开发流程"，但触发场景完全不同：前者通常在 PR 创建或代码 diff 出现时触发，后者在git commit前触发。如果你把它们混在一个"开发类"标签下，用户还是得逐个点进去看。所以我在整理自己的技能库时，习惯用"场景 + 动作"的二维标签，比如code-review/pr-diff、git/commit-message、docs/api-reference。这样检索的时候，脑子里想的是"我现在在干什么"，而不是"这个技能叫什么名字"。

2.2 技能的三层分类：原子技能、组合技能、工作流技能

从颗粒度上，我把技能分成三层，这个分法在整理仓库时特别有用。

原子技能是最小可执行单元，只做一件事，比如"把 Markdown 转成带样式的 HTML"、"从一段 JSON 里提取指定字段"。这类技能的特点是输入输出明确、依赖少、容易测试。仓库里数量最多的就是这一类。

组合技能是把几个原子技能串起来，完成一个稍大的任务。比如"生成 API 文档"这个技能，内部可能调用了"读取源码注释"、"提取函数签名"、"渲染 Markdown 模板"三个原子能力。组合技能的价值在于它封装了一套编排逻辑，用户不用自己拼。

工作流技能则更进一步，它带有状态和分支判断。比如"发布一个新版本"这种技能，会依次检查测试是否通过、更新 changelog、打 tag、触发构建，中间任何一步失败都要回滚。这类技能通常和 CI/CD 或本地脚本深度绑定，写起来复杂，但一旦跑通，收益也最大。

在awesome-claude-skills这类仓库里，如果你看到某个技能描述里出现了"orchestrate"、"pipeline"、"multi-step"这类词，基本可以判断它是组合或工作流级别的。新手建议从原子技能开始用，熟悉了再往上走。

2.3 判断一个技能值不值得用的四个信号

仓库里技能那么多，不可能每个都试。我总结了一套快速筛选的标准，看四个信号：

这四个信号里，我最看重的是依赖声明。很多技能跑不起来，不是技能本身写得差，而是它默认你已经装了某个 MCP server 或者配了某个环境变量，但文档里没写。你照着用，报错半天找不到原因。所以我现在养成一个习惯：拿到一个新技能，先看它的SKILL.md里有没有"Prerequisites"或"Requirements"章节，没有的话，直接去翻它的脚本文件，看它调用了哪些外部命令。

3. 拆开一个 Skill 看内部：SKILL.md 的结构与触发机制

3.1 SKILL.md 不是普通 README，它是给模型看的"操作手册"

很多人第一次写 Skill，会把SKILL.md当成项目 README 来写，堆一堆介绍性文字。这是个典型误区。SKILL.md的读者有两个：一个是人（快速判断这个技能干嘛的），另一个是模型（决定什么时候加载、怎么执行）。所以它的写法要兼顾两者，核心是前置元数据 + 触发条件 + 执行步骤三段式。

前置元数据通常用 YAML frontmatter 写在文件顶部，包含name、description、when_to_use这类字段。description要写得具体，不能是"帮助处理文档"这种废话，而应该是"将 PDF 文件转换为结构化 Markdown，保留标题层级和表格"。when_to_use则是给模型判断触发时机的，写得越贴近真实语境，自动触发越准。

触发条件这一段，是区分新手和老手的关键。新手往往只写"当用户要求处理 PDF 时使用"，但模型在实际对话里，用户可能说的是"帮我把这份报告转成能编辑的格式"，字面上没有"PDF"两个字。所以好的触发条件会列出同义表达和典型场景，比如"用户提到 PDF、扫描件、报告转换、格式整理等意图时"。这本质上是在给模型做意图匹配的提示。

3.2 触发机制：自动触发 vs 手动调用，各有各的适用场景

Claude Code 里技能的触发有两种方式。自动触发靠的是模型根据when_to_use描述和当前对话上下文做判断，适合那些"用户不一定知道有这个技能、但场景明显匹配"的情况。比如用户贴了一段报错日志，一个"日志分析"技能就应该自动介入。手动调用则是用户显式指定，比如输入/skill-name或者用自然语言说"用 XX 技能处理这个"。

我的经验是：高频、低风险的技能用自动触发，低频、高影响或容易误触发的技能用手动调用。举个例子，"格式化代码"这种技能自动触发没问题，就算误触发也就是多跑一次格式化。但"删除文件"、"执行数据库迁移"这类技能，绝对不能自动触发，必须手动确认。我在自己的技能库里，凡是涉及写操作、删除操作、外部 API 调用的，一律在SKILL.md里标注manual_only: true，避免模型自作主张。

还有一个容易被忽略的点：触发优先级。当多个技能的触发条件重叠时，模型怎么选？通常它会选描述最匹配的那个，但如果你发现经常触发错，可以在技能描述里加"排除条件"，比如"当用户明确要求 X 时，不要使用本技能"。这种负向描述在实际调试中非常有用。

3.3 一个最小可用 Skill 的完整目录长什么样

光说结构太抽象，直接看一个我实际在用的技能目录：

pdf-to-markdown/ ├── SKILL.md ├── scripts/ │ └── convert.py ├── templates/ │ └── output-header.md └── examples/ └── sample-output.md

SKILL.md里写清楚元数据、触发条件、执行步骤；scripts/放实际干活的脚本；templates/放输出模板；examples/放一两个输入输出示例，方便模型理解预期结果。这个结构不是强制的，但它是社区里比较通行的约定，照着来能减少很多沟通成本。

SKILL.md的内容大概长这样：

--- name: pdf-to-markdown description: 将 PDF 文件转换为结构化 Markdown，保留标题层级、列表和表格 when_to_use: 用户提到 PDF、扫描件、报告转换、格式整理，或需要把不可编辑文档转为可编辑格式时 manual_only: false --- ## 执行步骤 1. 确认输入文件路径存在且为 PDF 格式 2. 调用 scripts/convert.py 进行转换 3. 检查输出是否包含标题层级，若缺失则提示用户 4. 将结果写入同名 .md 文件 ## 边界说明 - 不支持加密 PDF - 扫描件需先经过 OCR，本技能不处理图像识别 - 表格复杂度过高时可能丢失合并单元格信息

注意"边界说明"这一段。新手最容易漏掉它，结果用户拿一个加密 PDF 过来，技能跑失败，用户以为是技能坏了。把边界写清楚，既是对用户负责，也是减少无效调试。

4. 自己动手写一个技能：从需求到跑通的完整链路

4.1 先别急着写代码，把"触发场景"用一句话说清楚

我写技能有个铁律：如果不能用一句话说清楚"什么情况下用这个技能"，那就说明需求还没想明白，先别动手。这句话要包含三个要素：触发条件、输入、输出。比如"当用户提供一段 SQL 查询并要求优化时，输入是原始 SQL，输出是优化后的 SQL 加改进说明"。这句话写不出来，后面写多少代码都是白费。

写清楚这句话之后，把它直接放进when_to_use字段。这一步看起来简单，但它逼着你把模糊的需求具体化。我见过太多人上来就写脚本，写完发现"这个技能到底什么时候该用"自己都说不清，最后变成一个没人调用的死技能。

4.2 脚本设计：让模型做判断，让脚本做执行

技能里的脚本，职责边界要划清楚。我的原则是：模型负责理解意图、处理模糊输入、生成自然语言；脚本负责确定性计算、文件操作、外部调用。不要把需要判断的逻辑塞进脚本，也不要把机械的重复操作交给模型。

举个反例。有人写一个"整理 CSV"的技能，把"判断哪一列是日期、哪一列是金额"这种逻辑写死在 Python 脚本里，结果换个 CSV 就失效。正确做法是让模型先看数据、判断列类型，然后把判断结果作为参数传给脚本，脚本只负责按参数执行清洗。这样脚本是通用的，模型负责适配变化。

脚本的输入输出也要规范。我习惯让脚本接受 JSON 格式的参数，输出也返回 JSON，包含status、result、error三个字段。这样模型解析起来稳定，出错时也能拿到明确的错误信息，而不是一堆堆栈。

4.3 调试技能的三板斧：日志、示例、边界用例

技能写完不是终点，调试才是重头戏。我调试技能一般用三招。

第一招是加日志。在脚本的关键节点打印输入参数和中间结果，跑一遍看数据流是否符合预期。很多人调试时只看最终输出对不对，但输出错了往往是中间某一步就偏了，不看中间状态根本定位不到。

第二招是准备示例。在examples/目录里放至少两组输入输出，一组正常情况，一组边界情况。每次改完技能，拿这两组跑一遍，确保没改坏。这其实就是最朴素的回归测试。

第三招是构造边界用例。空输入、超长输入、格式错误的输入、包含特殊字符的输入，这些都要试。我踩过最坑的一次，是一个处理文件路径的技能，在路径包含空格时直接崩了，因为脚本里没加引号。这种问题只有构造边界用例才能发现。

4.4 把技能放进仓库前，必须做的三件事

技能跑通了，想放进awesome-claude-skills这类仓库分享，先做三件事。

一是补全文档。SKILL.md里的边界说明、依赖声明、示例，一个都不能少。别人用你的技能，看不到这些信息就是抓瞎。

二是声明依赖。用了哪些 MCP server、需要哪些环境变量、依赖哪些系统命令，全部列清楚。我建议单独开一个requirements.md，把安装步骤写明白。

三是标注版本和兼容性。技能不是一劳永逸的，Claude Code 的接口、MCP 的协议都可能变。在SKILL.md里标注"适用于 Claude Code X.X 及以上版本"，能帮用户快速判断能不能用。

5. 技能与 MCP 的组合：让能力真正落地到工作流

5.1 先分清：什么时候该写 Skill，什么时候该上 MCP

这是新手最容易混淆的地方。我的判断标准很简单：如果这个能力需要连接外部系统、访问实时数据、执行有副作用的操作，用 MCP；如果这个能力只是"一套处理套路"，用 Skill。

举个例子。"查询数据库"这件事，需要连接数据库、执行 SQL、返回结果，这是 MCP 的活。"根据查询结果生成一份分析报告"这件事，是一套处理套路，这是 Skill 的活。实际工作里，两者经常配合：MCP 负责取数，Skill 负责加工。

再比如"调用 Figma 获取设计稿"是 MCP，"把设计稿转成前端组件代码"是 Skill。理解了这层分工，你就不会纠结"这个功能到底该写成技能还是 MCP"了。

5.2 组合模式：MCP 取数 + Skill 加工 + Skill 输出

我实际用得最多的组合模式是"三段式"：MCP 负责取数，一个 Skill 负责加工，另一个 Skill 负责输出。比如做竞品分析，流程是这样的：MCP 连接搜索接口拿到原始资料，第一个 Skill 负责提取关键信息并结构化，第二个 Skill 负责按模板生成分析报告。三个环节各司其职，任何一个环节出问题都好定位。

这种组合的好处是可替换。今天用 A 搜索接口，明天换成 B，只要 MCP 层的输出格式不变，后面的 Skill 完全不用改。同理，报告模板要调整，只改输出 Skill 就行，取数和加工环节不受影响。这就是工程化带来的灵活性。

5.3 一个真实案例：把"代码审查"拆成 MCP + 两个 Skill

说个具体的。我在团队里搭的代码审查流程，拆成了三部分。

MCP 层负责连接代码仓库，拿到 PR 的 diff、相关文件内容、历史提交记录。这部分用现成的 Git 相关 MCP server 就能搞定。

第一个 Skill 叫diff-analyzer，负责分析 diff，识别出改动的类型（新增功能、修复 bug、重构、改配置），并标记出可能的风险点（比如改了公共接口、动了数据库 schema、删了测试）。

第二个 Skill 叫review-commenter，负责根据分析结果生成审查意见，按严重程度分级，并给出具体的修改建议。

整个流程跑下来，审查意见的生成时间从原来的半小时压缩到几分钟，而且因为分析是结构化的，漏看风险点的概率大大降低。这里的关键不是某个技能写得多聪明，而是把一个大任务拆成了职责清晰的几段，每段都能独立测试和优化。

5.4 组合时的坑：上下文传递和错误处理

组合技能最容易出问题的地方是上下文传递。第一个技能的输出，怎么准确传给第二个技能？如果只是自然语言描述，信息在传递过程中会丢失细节。我的做法是让技能之间用结构化数据（JSON）传递，自然语言只用于最终呈现给用户的部分。

另一个坑是错误处理。组合流程里，如果中间某个技能失败了，是整体回滚还是跳过继续？这取决于业务逻辑。我的经验是：取数环节失败要中断，加工环节失败可以降级，输出环节失败要重试。取不到数据，后面都是空谈；加工失败，可以用简化版结果顶上；输出失败，重试几次通常能成。这套策略写进技能的错误处理逻辑里，能让整个流程稳很多。

6. 技能库维护与踩坑实录：那些文档里不会写的事

6.1 技能不是越多越好，臃肿的技能库会拖慢触发

刚开始用技能库的人，容易陷入"收集癖"——看到什么都想加进来。我早期也这样，技能库塞了上百个，结果发现模型触发越来越不准，经常该用 A 技能的时候触发了 B。后来才明白，技能库的规模和触发准确率是负相关的。技能越多，描述之间的重叠越多，模型判断的难度越大。

我的做法是定期做"技能审计"：三个月没被调用过的技能，要么删掉，要么合并进相关技能。同类技能只保留最通用的那个，特殊场景用参数区分，而不是各写一个。现在我的核心技能库控制在二十个以内，触发准确率反而高了很多。

6.2 版本漂移：为什么昨天还好好的技能今天就崩了

这是最让人抓狂的问题。技能昨天跑得好好的，今天突然报错，你什么都没改。原因通常是上游变了：Claude Code 更新了接口、MCP server 改了返回格式、依赖的第三方 API 调整了参数。这种"版本漂移"在快速迭代的生态里非常常见。

应对办法有两个。一是锁定版本，在技能文档里明确标注依赖的版本范围，升级前先测试。二是加健康检查，在技能启动时先跑一个轻量的探测，确认依赖可用再执行主逻辑。我现在的习惯是，凡是依赖外部服务的技能，开头都加一段检查，失败就给出明确的提示，而不是让用户面对一堆莫名其妙的报错。

6.3 权限与安全：哪些技能绝对不能自动触发

前面提过手动触发的原则，这里展开说。以下几类技能，我强烈建议设为手动触发，绝不自动执行：

• 写文件、删文件、改配置：误触发可能造成数据丢失
• 调用付费 API：误触发会产生真实费用
• 发送消息、发邮件、发通知：误触发可能造成尴尬或事故
• 执行数据库写操作：误触发可能污染生产数据
• 涉及凭证、密钥的操作：误触发有泄露风险

这些技能在SKILL.md里标注manual_only: true，并且在执行前要求用户二次确认。多一步确认，换来的是安心。

6.4 我踩过的三个具体坑

第一个坑：技能描述里的"等"字。我早期写触发条件喜欢用"处理文档、报告、表格等"，这个"等"字让模型过度泛化，结果用户随便说个什么它都想触发。后来我把"等"字全删了，改成列举具体场景，触发准确率立刻上来了。

第二个坑：脚本里的相对路径。技能脚本里用了相对路径，在我本地跑没问题，换到别人机器上就找不到文件。后来统一改成基于技能目录的绝对路径，问题解决。这个坑很基础，但真的很多人踩。

第三个坑：忽略输出编码。处理中文内容时，脚本输出没指定 UTF-8，结果在某些环境下乱码。现在我的脚本开头一律显式设置编码，省心。

6.5 让技能库持续有价值的三个习惯

最后分享三个我坚持了很久的习惯。

一是给每个技能写"变更日志"。哪怕只有一行，记录什么时候改了什么、为什么改。过几个月回头看，这些记录能帮你快速回忆上下文。

二是定期跑一遍所有技能的示例。我每个月抽半小时，把技能库里的示例全跑一遍，看有没有因为上游变化而失效的。早发现早修，别等用的时候才发现坏了。

三是把高频操作沉淀成技能。每次发现自己重复做同一件事超过三次，就停下来想想能不能写成技能。这个习惯让我的技能库始终围绕真实需求生长，而不是为了收集而收集。

awesome-claude-skills这类仓库的真正价值，不在于它收录了多少技能，而在于它提供了一套可参考的结构和约定。你照着它的组织方式整理自己的技能，慢慢就会形成一套贴合自己工作流的私人能力库。到那时候，你关注的就不再是"仓库里有什么"，而是"我今天又该沉淀点什么进去"。这个转变，才是从"用工具"到"建工具"的分水岭。