企业官网建设流程全解析

1. 从一次“工具失灵”说起：为什么我们需要 SKILL

几个月前，我在一个自动化项目里尝试让 Claude 按固定流程生成周报。起初我以为只要把流程写成一段很长的系统提示词塞进去，模型就能老老实实照做。结果并不理想：提示词超过两千字之后，模型开始选择性遗忘约束，中途跑偏去回答无关问题，甚至把几个步骤的顺序完全打乱。我折腾了几轮 prompt 优化，收效甚微。

后来我接触到了 Anthropic 官方提出的 SKILL 概念，才意识到问题不在“提示词写得不够好”，而在于我让模型同时承担了“理解流程”和“执行流程”两个任务——这恰恰是 SKILL 想要解决的核心问题。简单说，SKILL 是 Anthropic 在 Agent Skills 能力体系下提出的一种结构化技能封装方式：把某类任务的完整执行逻辑（指令、步骤、资源、示例）打包成一个独立的技能模块，Claude 在推理过程中按需加载并执行。

这篇文章我想结合自己的实操经验，从“什么是 SKILL”到“怎么写一个优秀的 SKILL”完整拆一遍，重点覆盖官方最佳实践、文件组织方式、提示词设计思路，以及我踩过的一些坑。适合正在搭建 AI Agent、做自动化流程编排、或者想把自己重复性工作沉淀成可复用技能的开发者。

2. 先弄清楚：SKILL、MCP 和 Tool 到底什么关系

2.1 SKILL 不是又一种 Tool

很多人第一次听说 SKILL，第一反应是“这不就是工具（Tool）吗”。我当时也有同样的困惑，直到对比了它们在 Agent 中的运行机制才搞清楚差别。

Tool 的本质是一个可被模型调用的外部函数，模型负责决定“何时调用、传入什么参数”，但工具本身不包含“何时该被用”的上下文理解。比如一个get_weather(city)的 Tool，模型知道传入城市名就能拿到天气，但模型并不清楚在什么业务流程下该优先调用它、拿到结果后应该如何继续。

SKILL 则更像是“一组有上下文的执行流程”。它由三部分构成：

• SKILL.md：核心指令文件，描述了该技能何时使用、如何执行、有哪些步骤和注意事项；
• scripts/ 资源目录：存放技能运行时需要的脚本、数据模板、参考文档；
• 可选示例与校验规则：帮助模型在调用时快速对齐预期输出。

从这个角度来说，SKILL 更像是把“工具 + 使用说明 + 执行策略 + 参考案例”捆绑在了一起。模型加载一个 SKILL，不只是获得一个可调用的函数，而是获得了一套完整的“怎么做这件事”的上下文。

2.2 与 MCP 的边界在哪里

MCP（Model Context Protocol）解决的是“模型如何标准化地访问外部数据和工具”的问题，它定义了一套协议，让不同的数据源和工具能够以统一的方式暴露给模型。SKILL 不依赖特定的传输协议，它本质上是存在于文件系统里的技能定义。

用一句话来区分：MCP 负责“连接”，SKILL 负责“流程”。MCP 决定模型能碰到的数据和工具范围，SKILL 决定模型面对一个任务时按照什么逻辑一步步完成。两者可以配合使用，同一个 Agent 里既可以通过 MCP 接入业务系统的数据接口，也可以通过 SKILL 把标准作业流程固化下来。

2.3 为什么 Anthropic 强调 SKILL 而不是“更长的提示词”

这是我在实践中体会最深的一点。把流程细节全部塞进系统提示词，表面上省事，实际会遇到三个问题：

• 上下文污染：与当前任务无关的指令会干扰模型判断，尤其当多个任务共享同一个系统提示词时，模型常常把 A 任务的规则误用到 B 任务上；
• 指令冲突：长提示词里前后表述稍有出入，模型就可能选择其中一条执行，产生不可预测行为；
• 维护困难：改一个步骤就要重新评估整段提示词对其他任务的影响，风险极高。

SKILL 的按需加载机制天然规避了这些问题。Claude 在收到用户请求后，会先判断“这个任务是否匹配某个已注册的 SKILL”，只在匹配时加载对应的 SKILL.md 内容。未匹配的任务完全不受影响。相当于把“全局规则”降维成了“局部上下文”，既减少干扰，也让每个技能可以独立迭代。

3. 官方最佳实践拆解：高质量 SKILL 的四个设计原则

3.1 原则一：明确“何时用”远比“怎么用”更重要

翻阅 Anthropic 的官方实践文档时，我注意到一个反复出现的强调点：SKILL.md 的第一部分必须是“When to use”或“适用场景”，而不是开门见山写步骤。

原因很直观：Claude 需要先判断是否激活这个 SKILL。如果适用场景描述模糊，模型可能在任务不匹配时强行调用，或者在任务高度匹配时反而错过。Anthropic 建议在 SKILL.md 开头用两三句话精确描述触发条件，最好包含正例和反例。

比如我写一个“客户邮件分类”的 SKILL，适用场景不能只写“用于处理邮件”，而要写成：

当用户需要对邮件进行分诊、标记优先级、提取待办事项时使用。如果用户只是要求撰写一封新邮件，不要使用本技能。

“不要使用”这种反向约束非常有效。实测下来，加入反例之后误调用的频率明显下降，因为模型在边界判断上获得了更清晰的信号。

3.2 原则二：步骤指令要“够细”但“不啰嗦”

Anthropic 官方推荐在 SKILL.md 中把执行步骤写成分步指令，但每一条指令都要聚焦“模型该做什么”，而不是解释“为什么这样做”。原理背景可以放在参考文档里，由模型在需要时查阅，而不是堆在主指令文件中。

举个例子，同样是写“数据清洗”的 SKILL：

• 不够好的写法：“先了解一下数据集的整体情况，根据常见的数据质量问题进行处理，最后输出干净数据。”
• 更好的写法：
  1. 读取输入文件的列名和前 10 行数据；
  2. 识别缺失值比例超过 30% 的列，在报告中列出；
  3. 对保留列中的缺失值，数值型用中位数填充，分类型用众数填充；
  4. 输出清洗后的文件与一份清洗报告（Markdown 格式）。

第二种写法把模型需要做出的“决策点”前移——哪列该处理、用什么策略、输出什么——每一步都明确，模型不需要在“自由发挥”和“猜用户意图”之间摇摆。

3.3 原则三：用好“示例”约束输出格式

模型对齐输出格式最有效的方式不是文字描述，而是给一两个示例。Anthropic 的实践文档里也强调，在 SKILL 中提供输入-输出对（尤其是期望输出的样例结构），能让模型稳定复现预期的格式。

我常用的做法是在 SKILL.md 里加一个## 输出示例章节，放置一个简短的示范片段。比如邮件分类 SKILL 的输出示例：

{ "category": "urgent", "priority_score": 92, "action_items": ["回复确认收到", "同步项目负责人"], "summary": "客户反馈生产环境出现数据延迟，要求今日内给出修复时间点" }

有了这个示例，模型生成的输出结构稳定得多。后来我在多个 SKILL 里都采用了这种方法，整体效果比纯文字描述输出字段定义要好上不少。

3.4 原则四：自带校验机制，别把希望全押在“模型自觉”上

优秀 SKILL 与平庸 SKILL 之间还有一个显著差异：有没有内置“自检”环节。Anthropic 推荐在 SKILL 执行流程中加入最终校验步骤，比如要求模型在输出前对照检查清单逐项确认。

实际应用中，我习惯在每个 SKILL.md 末尾加一个“交付前检查”小节，列出三四条可量化的检查项。例如：

• [ ] 输出文件格式是否为 UTF-8 编码的 Markdown？
• [ ] 是否包含全部必填字段（summary、action_items）？
• [ ] 是否有直接复制原始邮件的未修改文本？

这种写法的好处不仅是提升输出质量，更重要的是：当模型执行出现问题时，你能快速定位是哪个环节出了偏差，而不是面对一堆无法归因的错误输出反复试错。

4. 手把手写一个 SKILL：从目录结构到完整落地

4.1 目录结构与文件规范

Anthropic 对 SKILL 的目录结构有一套约定俗成的规范。我通常按下面的结构组织：

my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py └── references/ └── data_format.md

SKILL.md是唯一必须的文件，命名固定全大写。scripts/放可执行脚本，references/放参考文档、数据字典、模板文件。Claude 在加载 SKILL 时会读取 SKILL.md，并按需访问这些子目录中的资源。

这里有一个容易忽略的点：SKILL 目录的位置。如果是在 Claude Code 的项目环境中使用，SKILL 需要放在.claude/skills/下，Claude 启动时会自动扫描该目录，注册所有可用 SKILL。放在其他位置则需要在配置里显式声明路径，否则无法被发现。

4.2 SKILL.md 的推荐模板

根据官方实践和我自己的迭代经验，推荐使用以下模板：

--- name: 技能名称 description: 一句话描述该技能适用场景 --- # 技能名称 ## 何时使用 明确说明触发条件，包含正例与反例。 ## 输入要求 说明该技能需要哪些输入信息，以及这些信息的格式。 ## 执行步骤 1. 第一步... 2. 第二步... 3. 第三步... ## 输出规范 描述输出内容的结构与格式。 ## 输出示例 一个完整的示例输出。 ## 交付前检查 - [ ] 检查项1 - [ ] 检查项2

这个模板的每一节都有明确作用。description字段尤其关键，因为 Claude 判断是否激活该 SKILL 时，主要依赖这个字段和“何时使用”章节的内容。不要在这两处写模糊的口号式描述。

4.3 实战案例：写一个“会议纪要结构化”SKILL

我拿一个实际项目来演示完整过程。假设我需要一个 SKILL，能把一段零散的会议录音转写文本整理成结构化会议纪要。

SKILL.md 核心内容：

--- name: 会议纪要结构化 description: 将会议录音转写文本整理为结构化会议纪要，提取决策、待办、风险。当用户提供会议转写文本并要求生成纪要及时使用。 --- # 会议纪要结构化 ## 何时使用 当用户提供一段会议讨论的转写文本，并需要整理成会议纪要时使用。 如果用户只是询问关于会议的建议，并没有提供转写文本，不要使用本技能。 ## 输入要求 - 会议转写文本（纯文本或 Markdown） - 可选：会议主题、参会人名单 ## 执行步骤 1. 通读全文，识别会议的主要议题分布。 2. 提取每个议题下的关键讨论内容，区分“事实陈述”与“主观观点”。 3. 识别明确决策项，记录决策内容与提出人（如能在文本中对应）。 4. 识别待办事项，提取负责人、截止时间（如有）、任务描述。 5. 按模板输出结构化纪要，确保无信息遗漏。 ## 输出规范 - Markdown 格式 - 包含字段：会议主题、时间（如可识别）、参会人、议题列表、决策记录、待办事项、风险与关注点 ## 输出示例 ### 会议主题：数据平台迁移方案评审 #### 决策记录 - 确认采用双写迁移方案，过渡期为两周 - 数据校验由平台组负责，业务组配合 #### 待办事项 - [ ] 张伟：完成迁移脚本开发，截止 6月20日 - [ ] 李娜：梳理依赖列表，截止 6月18日 #### 风险与关注点 - 双写期间写入性能可能下降，需设置监控告警 ## 交付前检查 - [ ] 是否覆盖了所有议题？ - [ ] 每条待办是否有负责人？ - [ ] 是否有未经文本依据支撑的编造信息？

这个 SKILL 我用了一段时间，效果非常稳定。关键在“交付前检查”里那条“是否有未经文本依据支撑的编造信息”——它显著降低了模型在信息不全时自行脑补的问题。要知道，模型在整理纪要时最容易犯的错不是漏项，而是“合理想象”出一些原文中不存在的信息。

5. 实操经验：从零到一调试一个 SKILL 的完整过程

5.1 在 Claude Code 中注册与测试

我用的主力环境是 Claude Code。把 SKILL 目录放到项目的.claude/skills/下之后，重启会话，Claude 就会自动识别。可以通过对话直接询问“你有哪些可用的技能”，确认 SKILL 是否成功加载。

测试阶段我建议准备一组覆盖不同场景的输入，至少包含三类：

• 典型场景：完全符合 SKILL 设计目标的任务；
• 边界场景：任务部分满足 SKILL 触发条件；
• 负向场景：任务与 SKILL 无关，但看起来容易混淆。

用这三组输入反复跑，重点观察两个行为：启动判断（是否在合适的时机激活）和执行过程（是否严格按步骤走）。一旦发现 SKILL 在不该激活时被激活，优先回去改“何时使用”部分的表述。

5.2 参数调优：如何通过输出让模型更稳

SKILL 和自定义提示词一样，也存在“过犹不及”的问题。我在调试中发现几个值得注意的参数和细节：

• temperature 设置：生成类任务可以稍高（0.4~0.7），结构化提取任务建议调低至 0.2 以下，否则字段稳定性会下降；
• 步骤数量：执行步骤尽量控制在 5~8 步之间，超过 8 步模型容易在中途丢失对前序步骤的关注；
• 长文本处理：如果输入内容很长，建议在 SKILL.md 里显式要求模型“分批处理、中间汇总”，而不是一次性读完所有内容再输出，否则细节容易丢失。

5.3 迭代节奏：别追求一次写对

我现在的习惯是先写一个最小可用版本，跑通主流程，再逐步增加边界约束和异常处理逻辑。第一版 SKILL 往往只包含“何时使用”“执行步骤”“输出格式”三部分。验证基础流程没问题之后，再根据失败案例补充“交付前检查”和“反例描述”。

这样做的好处是能快速定位问题来源。一次性写一个功能完整、覆盖各种边界的 SKILL，一旦效果不好，你会很难判断是步骤设计有问题、场景描述不准确还是输出规范约束不足。分步迭代则让每次改动都有明确变量，调试效率高得多。

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

6.1 Claude 没有自动发现 SKILL

这是新手最常遇到的问题。排查步骤按顺序来：

• 检查 SKILL 目录是否放在.claude/skills/下，路径不能有拼写错误；
• 检查 SKILL.md 文件名，大小写不能错，必须叫SKILL.md；
• 检查文件头部 YAML 的name字段，是否包含非法字符或重复；
• 重启 Claude Code 会话再试，SKILL 在会话启动时扫描注册，运行中加入的新 SKILL 不会被动态发现。

6.2 模型偶尔不再遵循 SKILL 指令

我遇到过几次 SKILL 在复杂对话中途“失效”的情况，后来定位到原因是对话轮次太长，早期加载的 SKILL 上下文权重被后续大量对话内容稀释。解决办法是在 SKILL.md 的执行步骤中加入“每一步开始前回顾本技能的核心目标”类似的自提示语句，让模型在长流程中持续锚定任务范围。

另一个直接有效的做法是把一个大型 SKILL 拆分成多个小型 SKILL，每个只负责一个环节，通过流程串联。拆细之后，每个 SKILL 的指令密度更高，被稀释的概率也小得多。

6.3 输入输出格式兼容问题

如果你在 SKILL 里调用了scripts/下的 Python 脚本处理数据，注意脚本的输入输出编码，统一使用 UTF-8。我踩过的一个坑是：脚本输出的临时文件存在系统临时目录，Claude 在后续步骤中读取时因为路径特殊字符解析失败。后续我把所有中间文件都放在项目内的skill_workspace/目录下，问题就消失了。

对于 Windows 用户还有一个细节：路径分隔符不要混合使用。在 SKILL.md 里给出相对路径并约定基于项目根目录解析，比写死绝对路径要稳健得多。

6.4 SKILL 输出质量不稳定

同一个 SKILL 在不同轮次运行产生不同质量的结果，这除了模型本身采样随机性之外，最常见原因是输入信息不完整。我建议在 SKILL.md 的“输入要求”部分明确列出必需字段，若是字段缺失，要求模型先向用户澄清而不是自行假设。

比如会议纪要 SKILL，如果我规定“参会人列表缺失时，需要主动向用户确认后再生成最终纪要”，输出质量会稳定很多。模型在没有完整信息时倾向于编造合理的默认值，这在大规模使用中是个隐患。

7. 我对 SKILL 未来形态的一些观察

7.1 从“提示词复用”到“技能沉淀”

现阶段大部分人的提示词工程还是停留在“复制粘贴一段 prompt 到对话窗口”的层面。SKILL 把这一过程结构化、文件化、可版本管理化，本质上是在推动提示词工程向软件开发流程靠拢。我预期未来团队里会出现“技能工程师”这类角色，专门负责把业务专家的作业方法转化为可运行的 SKILL 资产。

7.2 SKILL 与 API 调用的结合方式

如果你是通过 API 接入 Claude，SKILL 的使用方式会更灵活一些。可以在系统提示词层面通过预定义规则让模型先去匹配可用技能列表，再在匹配命中时把 SKILL.md 内容作为上下文注入。这种方式相当于自己在应用层实现了“按需加载”，适合需要深度控制 Agent 行为的生产环境。

7.3 一个实用的扩展思路：SKILL 组合

单个 SKILL 解决单一任务，但实际业务流程往往是多步骤的。我的做法是把 SKILL 做成“可组合的积木”，比如一个“项目周报生成”SKILL，内部依赖“数据提取”“异常标注”“格式排版”三个子技能。在 SKILL.md 的执行步骤里显式声明子技能的调用顺序，Claude 就能串联执行。

这种组合方式让技能维护变得非常清爽：修改格式排版不影响数据提取逻辑，新增数据源只需要改数据提取那一个子 SKILL。如果你的业务逻辑足够复杂，很值得按这个思路拆一拆。

最后分享一个我实践下来的体会：写 SKILL 的过程其实就是一次次“角色换位”的练习。你得从模型的视角去思考——看到什么描述会激活这个技能，执行到哪一步容易产生歧义，输出到什么程度才叫完成。这种思维方式一旦建立，不仅 SKILL 写得好，你设计其他 Agent 能力的整体水平都会跟着上一个台阶。