企业官网建设流程全解析

过去两个月，我在好几个AI编程社群里反复看到同一个词：skills。Claude Code 刚宣布支持 Agent Skills 的时候，我还觉得这不过是把提示词换个目录存放；直到我真正把一套前端代码审查的 Skills 接进日常流水线，才发现这东西和普通 prompt 完全不是一个量级的玩法。这篇文章我就从底层逻辑讲起，把这几个月在 Claude Code、Codex、Cursor 上折腾 Skills 的踩坑记录、开发模板、调用 MCP 工具的完整链路一次说清楚，适合已经用过 AI 编程助手但总感觉回答不够稳定的开发者，也适合刚听说 Skills 想从零上手的新手。

先说结论：Skills 的本质是给模型一套“按需加载的岗位手册”。它不像 system prompt 那样每次都把几千字规则硬塞进上下文，而是等模型发现“这件事我需要一个专门的工作流”时，再去读对应目录里的 SKILL.md，把步骤、脚本、模板加载进来执行。这种机制既省 context，又能让 AI 在复杂任务里保持稳定输出。下面我会从设计原理、平台差异、开发实战、资源推荐和问题排查五个部分展开，你完全可以照着操作。

1. Skills到底解决什么问题：不只是“把提示词放进文件夹”

1.1 从一次失败的长对话说起

我最早接触 Skills 是因为一次 PPT 制作翻车现场。当时我用 Claude Code 帮我做一个技术分享的演示文稿，我在对话里把需求、大纲、风格要求、页数限制一股脑全打字进去。前两轮模型表现还不错，但聊到第 10 轮修改时，它突然忘了最开始说的“每页不超过 20 个字”，开始大段大段往幻灯片上堆文字。我重复解释了好几遍，效果还是不理想。

这个问题的根源在于：普通对话里你给的指令是“一次性消费”的。模型处理完当前回合后，你的规则就慢慢被新内容挤出注意力窗口。如果每轮都重新强调规则，不仅浪费 token，还特别容易前后矛盾。Skills 解决的正是这件事——它把一套完整的工作规范存成文件，模型在需要的时候主动加载，不需要的时候完全不占用上下文。

另一个常见场景是团队协作。以前我会把常用的代码规范、提交信息格式、测试要求全部写进项目根目录的 CLAUDE.md，但随着项目变大，这个文件越来越长，每次对话都在消耗大量 token，而且里面大部分内容跟当前任务无关。Skills 相当于把这些规范拆成一个个独立模块，按场景触发，既提升准确率，也大幅降低使用成本。

1.2 Skills、Prompt、插件与MCP的区别

我经常看到有人把 Skills 和 MCP 混为一谈，这俩其实是完全不同的东西。MCP（Model Context Protocol）解决的是“模型能调用什么工具”的问题，比如它可以帮你读文件、执行命令、访问数据库；而 Skills 解决的是“模型应该用什么方法完成一件复杂任务”的问题，比如做 PPT 时应该先列大纲、再写标题、最后补备注。

你可以这样理解：MCP 是给模型提供外挂工具，Skills 是给模型提供工作方法和步骤。一个 Skill 内部完全可以调用 MCP 工具来完成具体动作。比如我做“前端项目审查”这个 Skill 时，步骤里就明确写了“先调用 MCP 的 filesystem 工具读取项目目录结构，再调用 grep 工具搜索关键依赖”，这样模型很清楚每一步该用什么工具，而不是自己临场乱猜。

相比传统插件，Skills 更像是“提示词 + 脚本 + 模板”的组合包。插件通常是一个深度集成到编辑器里的扩展程序，需要写 UI、注册命令、处理事件；而 Skills 的形态非常简单，本质上就是一个包含 SKILL.md 说明文件和若干辅助脚本的文件夹，模型通过语义匹配决定是否加载它。这种轻量设计最大的好处是生态门槛很低，会写 Markdown 就能开发自己的 Skill。

1.3 为什么约定用 SKILL.md 这个文件

如果你看过 Anthropic 官方的 Agent Skills 设计，会发现所有 Skills 都围绕一个核心文件：SKILL.md。它采用类似 Markdown 的格式，顶部是 YAML 格式的 frontmatter，里面有 name（技能名字）和 description（技能说明），正文则是具体的指令内容。

这里最关键的是 description。它不只是给人看的注释，而是模型判断“这个任务要不要加载该 Skill”的依据。如果你的 description 写得太泛，比如“帮助用户处理各种问题”，模型根本不知道什么时候该调用它；但如果你写“当用户要求生成 PPT、演示文稿、slides 或教学课件时使用”，模型就能在合适的场景精准触发。

SKILL.md 正文通常会包含适用场景、所需输入、执行步骤、输出格式、注意事项这几块。一份好的 SKILL.md 不是长篇大论，而是像给一个聪明同事的交接文档——告诉他目标是什么、流程是什么、边界在哪，剩下的交给模型自己发挥。

2. 主流工具里如何安装和使用Skills

2.1 Claude Code的Skills目录与启用流程

Claude Code 是最早让我感受到 Skills 威力的工具。它支持两种存放位置：项目级目录.claude/skills/和用户级目录~/.claude/skills/。项目级适合跟团队共享的规范，用户级适合个人常用的工作流。

实际操作很简单，比如你想装一个“PPT 生成助手”的 Skill，只需要创建这样的目录结构：

~/.claude/skills/presentation-builder/ ├── SKILL.md └── scripts/ └── build_ppt.py

然后在 SKILL.md 里写好名称和触发描述，重新打开一个 Claude Code 会话，模型就会自动识别这个 Skill。这里有个前提：Claude Code 只在会话开始时或任务切换到相关语义时去扫描 Skills 目录，所以你在添加新 Skill 之后，最好重启会话或者用/skills命令手动查看当前可用的技能列表。

我实测下来，Claude Code 对 Skills 的触发准确率还不错，但前提是描述得足够具体。还有一个调试小技巧：启动时加--debug参数，Claude Code 会打印出模型加载了哪些 Skill、调用了哪些工具，排查“为什么模型没用我的 Skill”时特别有用。

2.2 Codex、Cursor、OpenCode里的差异

OpenAI 的 Codex CLI 也支持 Skills，路径配置在~/.codex/skills/下。和 Claude Code 类似，每个 Skill 也是一个包含 SKILL.md 的文件夹。Codex 的好处是它本身对 MCP 工具支持很完善，你可以在 Skill 里写清楚“需要调用 mcp__github 工具来读取 issue”，Codex 会自动去连对应的服务。

Cursor 在 0.46 版本之后加入了类似能力，路径是项目下的.cursor/skills/。由于 Cursor 本身是编辑器形态，它对 Skill 的加载更偏“上下文注入”——当你选中一段代码或者打开某个文件时，Cursor 会根据当前文件类型去匹配相关 Skill，并把内容注入到对话上下文中。这意味着 Cursor 的 Skill 更适合跟编辑器行为绑定，比如“当你打开一个 Python 测试文件时，自动加载测试风格规范”。

OpenCode 这类开源 CLI 终端工具也有自己的约定，一般放在~/.config/opencode/skill/或项目级.opencode/skill/。如果你同时在用多个工具，最省心的做法是把 Skills 仓库用 git 管理起来，然后在不同机器上软链到对应目录，避免重复维护。

2.3 三个拿来即用的场景示例

为了让你更直观地理解，我举三个高频场景的例子。

第一个是“网页查资料并整理笔记”。这个 Skill 的 SKILL.md 会这样设计：模型先调用 MCP 的浏览器工具或搜索工具获取网页内容，然后提取重点，再按“摘要、关键结论、原文引用、待办事项”四段式输出。以前我直接让 AI 查资料，它经常只给一段干巴巴的总结，没有来源、没有结构化信息，用这个 Skill 之后输出质量稳定多了。

第二个是“前端图片还原设计稿”。社区里很多好用的 Skill 就是干这个的：拿到一张设计稿截图后，模型先分析布局结构、字体、间距、配色，再依次生成 HTML 骨架、CSS 样式、响应式适配方案。关键是 SKILL.md 里会规定一系列步骤，比如“先描述整体布局、再识别组件、最后输出可运行代码”，避免模型一上来就盲目写代码。

第三个是“PPT 生成”。一个成熟的 PPT Skill 会要求模型调用 MCP 工具里的幻灯片操作能力，并且在 SKILL.md 里明确“标题不超过 20 字、每页要点不超过 5 条、备注栏写演讲提示词”。这样你只需要说一句话“把这篇博客改成 10 页分享稿”，模型就会按既定流程生成，而不是临时自由发挥。

3. 手把手开发自己的第一个Skill

3.1 设计Skill前先回答三个问题

我见过很多人一上来就照着模板写 SKILL.md，结果写出来的东西模型根本不知道怎么用。开发之前，建议先回答三个问题：触发场景是什么、输入是什么、输出是什么。

触发场景决定你的 description 怎么写。比如你公司前端项目要求所有组件必须用 TypeScript、必须写测试、必须带 Storybook 演示，那触发场景就是“用户提到组件开发、前端编码、React/Vue 修改”等情景。输入是指这个 Skill 需要哪些外部信息，比如“项目目录路径”“需求文档内容”还是“技术栈说明”。输出则要定义清楚交付物格式，比如“改动清单、测试文件、注意事项”。

我在实际开发中会先在纸上写一遍这个 Skill 的执行流程：假设模型现在要做这件事，第一步干什么，第二步干什么，什么情况下用哪个工具，最后交付什么。这个过程很像写工作流 SOP，想清楚了再写 SKILL.md 会高效很多。我的经验是，一份好的 Skill 通常包含 5 到 10 个执行步骤，超过 15 步就说明任务分得太粗，应该拆成两个 Skill。

3.2 完整实战：做一个“前端代码审查Skill”

我以自己最常用的“前端代码审查 Skill”为例，展示完整结构。这个 Skill 的作用是让 AI 按统一的审查标准检查前端代码变更，而不是泛泛而谈“代码挺不错的”“有些地方可以优化”。

目录结构：

~/.claude/skills/frontend-code-review/ ├── SKILL.md └── scripts/ └── review_summary.py

SKILL.md 的简化版本如下，实际使用时可以根据团队规范扩充：

--- name: frontend-code-review description: 当用户要求审查前端代码、Rerun代码审查、检查React/Vue组件质量、分析Pull Request时使用。适用于TypeScript/JavaScript项目。 --- # 前端代码审查 ## 适用场景 - 用户要求审查代码变更或Pull Request - 用户想检查组件实现是否符合团队规范 - 用户希望发现潜在的样式、逻辑或性能问题 ## 输入 - 待审查代码的路径或diff内容 - 项目技术栈（默认React + TypeScript） - 需要关注的规范（如有） ## 执行步骤 1. 读取代码文件或diff内容，先梳理变更的整体结构和影响范围。 2. 依次检查以下维度： - 类型安全：是否存在any、未使用变量、隐式类型转换问题 - 组件规范：是否拆分合理、是否有关键副作用、props是否有效约束 - 样式问题：是否使用设计token、是否有魔法数字、是否包含内联样式 - 性能隐患：是否存在不必要的重渲染、大列表是否缺少key、是否有内存泄漏风险 3. 对发现的问题按严重程度分级：阻塞、建议、可选。 4. 输出审查报告，包含问题定位、修改建议、参考代码片段。 ## 输出格式 - 变更总览 - 问题列表（按严重程度排列） - 修复建议代码 - 自检清单

写完后我发现，模型在这个 Skill 的约束下，给出的审查意见明显更专业、更有条理，而不是以前那种“感觉没什么大问题”的敷衍回答。当然，这个 Skill 还很依赖代码文件能被正确读取，所以我在步骤里特意加上了“先读取代码文件或 diff 内容”，确保模型不会凭空猜测。

3.3 在Skill里调用MCP工具

很多场景下，Skill 需要配合 MCP 工具才能真正跑通。比如做 PPT 的 Skill，如果模型没有操作 pptx 文件的能力，就算步骤写得再详细，也只能输出 Markdown 大纲，无法生成真正的演示文稿。这时你应该在 Skill 的步骤里明确写“调用 MCP 的 pptx 工具创建幻灯片，并通过 add_slide 方法逐页添加内容”。

MCP 工具在模型眼里就是一组带命名前缀的函数，常见的命名格式是mcp__服务器名__工具名。比如你连了一个文件系统服务，工具名可能是mcp__filesystem__read_file。在 SKILL.md 里，你不一定需要写出完整前缀，只要写清楚“使用文件系统工具读取 xxx”，模型在执行时会自动匹配可用的 MCP 工具。但为了避免歧义，对于多 MCP 服务的情况，我建议还是写出明确的工具名或者至少标明是哪个 MCP 服务提供的。

这里有一个容易踩的坑：如果某个 MCP 服务没连接成功，模型会卡在“尝试调用工具却失败”的状态。所以我在不少 Skill 的第一条步骤里都会写“先检查所需 MCP 工具是否可用，若不可用则告知用户并提供降级方案”。这个小小的防御性设计，能省去很多排查时间。

3.4 调试技巧

Skill 开发完成后，调试是必经环节。我遇到最多的问题是“模型根本不加载我的 Skill”。这时我会先确认目录路径是否正确，再检查 SKILL.md 顶部的 frontmatter 是否完整，尤其是 name 和 description。有时候 description 里缺少触发关键词，模型就会把它当成普通知识文档，而不是可执行的技能。

另外一个技巧是利用工具的调试日志。Claude Code 的--debug模式会输出模型加载了哪些 SKILL.md，看不懂的话就重点搜索 “loaded skill” 或 “skill” 关键字。Codex 也可以用-v或 verbose 模式查看日志。如果你写的 Skill 包含 shell 脚本或 Python 脚本，不要忘了给脚本执行权限，用chmod +x处理一下，否则模型会告诉你“没有权限执行该文件”，但这个报错真正含义可能只是你忘了设置权限。

4. 值得收藏的场景型Skills推荐

4.1 从社区仓库找Skills的姿势

现在 GitHub 上已经有不少 Skills 合集，质量参差不齐。我一般会优先看 Anthropic 官方仓库anthropics/skills，里面维护了一组经过验证的示例，比如生成 PDF、构建幻灯片、处理电子表格、从截图生成代码等，这些是最适合入门的参考资料。社区里 star 很高的合集也值得关注，比如 Matt Pocock 基于个人工作流程整理的 TypeScript 相关 Skills，还有各种 awesome 系列仓库，里面按场景做了分类。

但我不建议看到什么 Skill 就往本机里塞。每个 Skill 都是作者基于自己的工作流设计的，直接拿来用可能会跟你现有的工具链冲突。我的做法是：把感兴趣的 Skill clone 下来当作模板，通读它的 SKILL.md，保留核心步骤，然后按自己的项目和习惯改造。

4.2 按场景的推荐清单

我按自己在实际工作中验证过的场景整理了一个清单，你可以作为参考。需要说明的是，这些 Skills 不一定要去网上找现成的，很多完全可以根据这里列出的设计思路自己写。

这里重点说一下数学建模类的 Skill。很多参赛同学问我要“数学建模 Skills 推荐”，其实比起用别人写好的，我更建议自己做一个“建模流程 Skill”：让模型遇到问题后，先判断是优化问题、统计问题还是微分方程问题，然后列出数学假设和符号定义，再生成求解脚本并用测试用例验证边界。这个逻辑写进 SKILL.md 后，AI 给出的建模方案会专业很多，而不是看到题目就堆一堆公式。

4.3 用Skills搭一个个人工作台

用好 Skills 的关键是持续积累。我给自己定了一个规矩：凡是让 AI 成功完成过两三次以上的重复任务，就把过程沉淀成 Skill。比如我经常需要把设计稿还原成前端页面，一开始是每次在对话里重新描述要求，后来直接写了一个“image-to-frontend” Skill，现在只要把图片路径扔进去，模型就能走完整套流程。

沉淀下来的 Skills 我会放到一个独立的 git 仓库里，命名规范统一为“场景-能力”的格式，比如frontend-code-review、docs-article-builder。这样换电脑或者带新同事时，直接把仓库 clone 下来，再让每个人按自己的工具链软链到对应目录，团队的知识积累就能持续复用。个人工作台的核心价值就是：你的高效工作流不需要每次从零开始和 AI 沟通，它会越来越懂你的习惯。

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

5.1 模型就是不用我的Skill

这个问题出现频率最高。我排查时一般按三个顺序来：第一，检查目录路径和 frontmatter 格式；第二，检查 description 是否包含明显的触发词；第三，检查是否重启了会话。经常有人改了 SKILL.md 之后忘记新开会话，然后抱怨“怎么不生效”，其实模型在做任务规划时根本没重新扫描目录。

如果你确认这些都正常，还有一招是手动“点一下”该 Skill。Claude Code 里可以用/skills命令查看可用技能，有时候直接指定“使用 skills 里的前端审查规范来检查这段代码”，模型就会明确去读取对应文件。这不算作弊，更像是对模型的一种提醒方式。

5.2 Skills与MCP工具协调失败

另一类常见问题是 Skill 里写了“调用 MCP 工具”，但模型根本找不到。我遇到的大部分原因是 MCP 服务没启动，或者服务名对不上。比如我在一个 Skill 里写“使用 server 的 fetch 工具”，但实际配置的服务器名是http-server，模型就会迷茫。解决办法是在 SKILL.md 里写得再具体一点，比如“使用 mcp__http-server__fetch 工具获取网页内容”。

还有一个不容易注意的坑：同时安装多个功能重叠的 MCP 服务时，模型可能不知道该选哪个。我在做学术研究 Skill 时，机器上同时配了浏览器搜索和学术搜索引擎，SKILL.md 里如果不指定优先级，模型就会随机选一个，输出质量很不稳定。后来我在步骤里明确写上“优先使用学术搜索 MCP，其次才用通用搜索”，问题立刻消失了。

5.3 Skill体积过大导致上下文浪费

有人以为 Skill 内容越详细越好，其实不是。SKILL.md 也会被模型读进上下文，如果正文写了一万字，即使按需加载也会消耗大量 token，而且在长任务中反而容易让模型抓不住重点。我的经验是：SKILL.md 正文控制在 2000 字以内，写清步骤和输出格式即可，详细的模板、代码、数据都放到 scripts 或其他文件中，让模型按需读取。

比如我的前端代码审查 Skill，SKILL.md 只写了审查的六个维度和输出格式，而详细的规范清单放在docs/style-rules.md里，SKILL.md 中的某个步骤写着“如有疑问，读取 docs/style-rules.md 中的详细规范”。这样既保证了 Skill 轻量，又保留了大而全的细节。

5.4 安全提醒：谨慎使用第三方Skills

最后必须提醒一点，Skills 本质上是可以引导模型执行任意操作的文件。一个来路不明的 Skill 可能包含恶意脚本，让模型在本地执行危险命令，或者在无人注意时读取敏感文件后外传。我自己从社区下载 Skills 后，第一件事就是完整阅读 SKILL.md 和所有关联脚本，确认没有可疑的网络请求或高危命令，然后才会放进技能目录。

安全巡检类的 Skills 尤其要小心。如果你做的是内部授权范围内的安全检查，可以放心使用；但绝对不能把这类 Skill 用在未经授权的目标上。安全技能的设计也应遵循同样的原则：先收集信息、再评估、最后输出修复建议，而不是直接下载攻击脚本。

在我个人的实际使用习惯里，还会定期清理不再使用的 Skills，因为技能目录越多，模型在语义匹配时的干扰就越大。每保留一个 Skill，我都会确认它在过去两周内确实被用到过，或者即将用于某个明确任务。说到底，Skills 是给人用的效率工具，不是收藏品，精简和持续迭代才是让它发挥作用的关键。如果你也想尝试，建议从一个小场景开始，比如把一个你经常重复的操作流程写成最简单的 SKILL.md，哪怕只有 20 行，跑通一次你就会明白它的价值。