企业官网建设流程全解析

如果你试过让Claude反复处理同一类任务，比如“分析一下这个项目的整体结构”“按我们的规范检查这段代码”，你会发现每次都要把背景、要求、边界条件重新解释一遍。解释得稍微含糊一点，输出的质量就跟着波动。后来我接触到Agent Skills，这个思路直接改变了我的工作方式：把常用的处理流程固化成一个“技能包”，让模型按预定义的步骤去执行。这篇内容就把我实际操作的心得和踩过的坑捋一捋。

Agent Skills能解决的问题很具体：它让Claude Agent不再只是被动地回答每一次提问，而是拥有类似“工具箱”的能力——你给它一个任务，它能调用对应的处理流程，按你预设的步骤、约束、输出格式来完成。它适合的人也比较广：正在用Claude做项目分析、代码审查、文档整理的开发者，或者经常需要让AI重复执行固定流程的“重度用户”。

我下面会从最基础的概念讲起，用一个可以照抄的示例带你把一个完整的Skill跑起来，再分享我在实测中遇到的实际问题和排查思路。全程不绕弯子，希望你看完就能直接上手。

1. Agent Skills到底解决了什么问题

1.1 从最原始的“复制粘贴提问”说起

在Agent Skills出现之前，我的工作流大概是这样：每个新任务，都要在对话里重新贴一遍项目背景、编码规范、期望输出格式，有时候还要附上几个历史案例作为参考。这就像是每次请同一个师傅来干活，都得重新给人家讲一遍你的规矩。对话一长，上下文被大量重复信息占据，留给真正任务本身的空间就越来越少。

而且这种方式有一个很隐蔽的麻烦：模型的每次回复都是“临场发挥”。你上一次说“请用简洁的语言总结”，它记住了；但一旦开启新对话，它又把这句话忘得干干净净。我的同事A同学就遇到过这种情况，他让Claude按一套固定的标准审查代码，第一轮效果不错，第二轮换了新会话，模型完全忘了之前定的规则，审查标准直接漂移了。这不是模型变笨了，而是你没把“规则”固化成它能稳定读取的东西。

Agent Skills正好解决这个痛点。它的思路很简单：把特定任务的处理流程、参考信息、脚本工具，打包成一个独立的技能目录。模型在处理相关任务时，会自动读取这个技能包里的说明，严格按要求执行。相当于你给师傅写了一本操作手册，每次他干活前先翻手册，而不是听你临时口述。

1.2 和系统提示词、自定义指令、MCP工具的区别

有一段时间我分不清Agent Skills和另外几个容易混淆的概念，后来用了一张表把它们的关系理清楚了：

你可以这样理解：系统提示词是“世界观”，自定义指令是“性格”，MCP工具是“手脚”，Agent Skills是“肌肉记忆”。前面几样解决的是“模型是什么样的人”，Agent Skills解决的是“模型做某件事时按什么流程走”。

举一个实际取舍的例子。我一开始想用系统提示词解决审查规范的问题，把整段审查标准塞进系统提示词里。但很快发现两个问题：一是那段文字对所有任务都生效，模型回答普通问题时也被迫背着这套规则，反而干扰了正常对话；二是系统提示词有长度限制，塞不下太详细的流程。而把审查流程做成一个Skill之后，只有模型判断当前是审查任务时才加载，既不干扰日常对话，又能承载比提示词复杂得多的步骤描述。

2. 动手构建一个Skill：从零到能跑的完整过程

2.1 目录结构：最小可用骨架

构建Skill并不神秘，它就是一组遵循特定目录约定的文件。以Claude相关客户端为例，最基础的结构是在项目根目录下建一个.claude/skills文件夹，里面每个子文件夹就是一个独立的Skill。我这个示例Skill的名字叫项目代码概览，真实结构长这样：

.claude/skills/ └── 项目代码概览/ ├── SKILL.md ├── scripts/ │ └── scan_project.py └── references/ └── output_template.md

看着简单，但我见过不少人在这一步就出错。最常见的问题是目录层级不对：有人把SKILL.md直接放到了.claude/skills下面，没有单独建一个技能文件夹。按约定，系统扫描的是skills目录下的下一级子目录，只有当子目录里的SKILL.md存在时，才被识别为一个技能。我排查过的几个案例里，模型明明已经加载了其他技能，但新写的技能始终不生效，最后发现就是这个原因。

也就是说：一个Skill = 一个文件夹 + 一个SKILL.md文件，脚本和参考资料是Optional的。先记住这个最小骨架，其他的往后再说。

2.2 写description的讲究：模型能不能准确触发就靠它

如果说SKILL.md是一份操作手册，那么文件开头的description字段就是这本手册的“目录索引”。模型并不是读完整个SKILL.md再决定用不用它，而是先扫描所有技能的描述，判断哪个技能和当前任务匹配，匹配了才读取完整的SKILL.md内容。

我最初写description很马虎，写的是“用于分析项目结构”。看着没问题，但实测触发率很低。因为“分析项目结构”这个表述太宽泛了，模型在很多场景下都无法确定你是否需要这个技能。后来我总结出一个写法公式：使用场景 + 明确任务 + 输入要求 + 反例。

以我的“项目代码概览”Skill为例，改进后的description是这样：

--- name: 项目代码概览 description: 当用户需要快速了解一个代码库的整体架构、目录结构、 技术栈、模块划分时使用。例如用户说"分析一下这个项目的结构"、 "画一下项目的模块关系"、"这个仓库是做什么的"。 不要用于回答具体的代码逻辑问题，例如"这个函数为什么报错"。 ---

注意最后加了一句“反例”，这是我从一次误触发里学到的。那次用户问了一个普通的问题，模型却调用了这个技能，白白浪费了时间。加上反例描述后，误触发率明显下降。原因是模型的意图判断本质上是一个“匹配”过程，你给出的正例越多，匹配越准；你给出的反例越清晰，排除越明确。

2.3 正文Markdown的组织方式：从“引导提问”到“分步指令”

SKILL.md的正文就是你给模型的“操作手顺”。不需要写代码，而是用自然语言清晰地告诉模型：拿到这个任务后，按什么顺序执行，每步做什么，最终以什么格式输出。

我把自己的SKILL.md正文拆成了四段，每一段都有明确的用途：

# 项目代码概览 ## 执行步骤 1. 先扫描项目根目录，读取 README.md（如存在），梳理项目用途。 2. 列出顶层目录结构，标注每个目录的职责（如 src 存放业务代码，tests 存放测试）。 3. 识别关键配置文件（如 package.json、requirements.txt、go.mod），提取技术栈信息。 4. 统计各模块代码量和主要文件，归纳核心模块。 5. 如果项目包含脚本 scripts/scan_project.py，运行它获取统计信息，并将结果整合进输出。 ## 重要约束 - 不深入分析具体函数的实现细节。 - 不要推测不存在的目录或文件，所有描述必须基于实际看到的内容。 ## 输出格式 以 Markdown 输出，包含：项目简介、技术栈表、目录结构树、各模块职责说明、核心模块标记。

我特别想强调一下“执行步骤”里第5条的设计思路。当初我在想，要不要把脚本调用写进去，后来发现非常有必要。因为模型虽然会写脚本，但要它自己去临场发挥一段代码来分析项目，效果远不如你预先准备一个成熟的脚本。于是我把项目扫描逻辑写成了一个Python脚本，把“运行脚本拿结果”作为步骤之一，这样模型的工作就从“思考怎么做”变成了“按流程做什么”，稳定性大大提升。

这种写法有一个额外好处：SKILL.md正文是纯文本，模型读取成本极低，不会因为格式复杂而忽略某条指令。相比之下，如果你把指令藏在脚本里或者隐藏在某个不起眼的文件里，模型很可能根本没意识到要去看。

2.4 何时需要配套脚本和参考文件

不是所有Skill都必须带脚本。我搭过最轻量的Skill，只有一份SKILL.md文件，作用就是约束文章的写作风格和结构。模型读完正文就能工作，不需要额外工具。

带脚本的价值点在于：有些任务需要外部信息或计算，模型本身拿不到这些数据。比如上面那个“项目代码概览”例子，模型无法直接读取你电脑里的文件，除非通过MCP或Agent的文件访问能力。如果你的运行时环境已经给了Agent文件访问的能力，那么有脚本主要目的是让扫描逻辑更强大，比如统计代码行数、识别大型模块、生成依赖关系图。

脚本的输出要遵循一个原则：给模型“能消化”的数据，而不是原始数据。我的scan_project.py脚本输出结构大致是：

project_root: /path/to/project language_stats: Python: 82 JavaScript: 15 Shell: 3 module_summary: "src/core": "612 行，核心业务逻辑，模块引用数最高" "src/utils": "233 行，工具函数集合" "tests": "128 行，单元测试"

为什么是这种格式？因为我试过让脚本输出完整的目录树和每个文件的详细分析，结果一次返回的数据量大得吓人，模型被埋在细节里，反而提炼不出重点。做了这个调整之后，模型拿着统计好的结果，直接套用SKILL.md里要求的输出格式，完成质量稳定了很多。你设计脚本时一定要时刻想清楚一件事：这个脚本是给模型用的，不是给人看的，输出内容要服务于模型的后续处理。

3. Skill的加载与触发：搞清它什么时候“站出来”

3.1 系统提示中Skills如何呈现

用支持Agent Skills的Claude环境时，系统会在每次会话启动时扫描.claude/skills目录，把每个技能的name和description注入到上下文里。注意，注入的只是“描述”，不是完整内容，这个设计很巧妙：一方面让模型知道有哪些技能可用，另一方面避免上下文被无关的详细内容塞满。

我在调试时发现一个检查是否加载成功的技巧：直接问Claude“你现在有哪些可用的技能”，它能报出技能的name和description，说明加载成功了。有时候我更新了SKILL.md的内容，发现模型行为没变化，先做这一步检查，确认新描述已注入，再往下排查，能省不少时间。

3.2 触发策略：用户明确引用还是模型自动判断

触发条件有两条路径：用户主动让模型用某个技能，或者模型根据用户意图自动选择。很多教程会告诉你“模型会自动选择合适的技能”，听起来很智能，但我实际用下来的感受是：自动判断适合宽泛场景，明确引用适合关键流程。

举个具体例子。我写了一个“代码审查”Skill，规定了一系列审查标准。某次开会汇报前，我需要它审查一段重要代码，为了确保它一定走审查流程，我在提问里直接写了一句话：“请使用代码审查技能对以下代码进行审查”。结果它老老实实按步骤执行，输出的格式就是我在SKILL.md里定义的那个。而另一次我没点名，只说“帮我看看这段代码”，模型也自动调用了技能，因为description里的正例匹配到了“看看代码”这个意图。

我的建议是：重要任务显式点名，日常任务靠自动判断。“点名”的操作很简单，在问题里加上技能名就行。尤其在你刚完成一个Skill、还在验证效果时，建议每次都点名，这样你能更方便地判断它执行的是不是你设计的流程。

3.3 Skill的一次完整执行流程

当模型决定使用某个Skill后，具体过程是什么样的？我拆解一下，帮助你建立整体认知：

1. 索引扫描：会话启动时，系统扫描skills目录，把技能名和描述注入上下文。
2. 意图匹配：用户提问后，模型根据描述判断哪个技能与当前任务匹配。
3. 完整读取：匹配成功后，模型读取该技能文件夹里的SKILL.md完整内容，同时按需读取references目录里的参考文件。
4. 按序执行：模型依照SKILL.md中的执行步骤工作，包括运行scripts目录下的脚本并读取结果。
5. 格式化输出：模型按SKILL.md中规定的输出格式整理结果，完成整个任务。

理解了这个流程，你就明白为什么技能的目录结构和描述写法如此重要——任何一个环节出错，整个过程都不稳定。我第一次自己写Skill时就犯过脚本路径写错的问题，模型照着SKILL.md的指示去运行scripts/scan_project.py，结果文件根本不存在，它就跳过了这一步直接输出了。你没给模型一个“遇到错误怎么处理”的兜底方案时，它通常不会主动报错，而是默默放弃执行那一步，这个行为特别坑。

4. 实战踩坑记录：排查一个“模型就是不按步骤走”的问题

4.1 现象

我做一个“文档审阅”Skill时遇到一个很典型的问题：按我在SKILL.md里的定义，模型应该先运行一个脚本抽取文档里的关键段落，再根据这些段落做审阅。但实际执行时，模型全程没有调用脚本，直接用自己的理解去审阅了。最无语的是，它生成的审阅意见看起来还像模像样，如果不仔细看，你根本不知道它漏掉了脚本这一步骤。

这个问题持续了挺久，因为输出质量好坏并不像运行代码那样非黑即白。模型擅自改变执行流程的情况在纯自然语言场景下很容易被忽略，而且我见过不少人也遇到了类似问题，却很难找到原因，因为排查方向往往搞错了。

4.2 完整排查链路

我分享一下当时的完整排查思路，注意看我是怎么一层层缩小范围的。

第一步，检查SKILL.md的YAML头。这是最基础的检查项。如果frontmatter有语法错误，整个Skill可能都不被识别。我排查时仔细看了字段之间有没有多余的空格、引号是否闭合，结果一切正常。

第二步，检查技能是否被正确注入。我向模型询问当前技能列表，确认“文档审阅”技能在列表中，并且description描述与我的预期一致。确认之后，我排除了技能本身未被识别的问题。

第三步，检查SKILL.md正文里关于脚本调用的表述。发现问题的苗头在这里。我最初的表述是：

如果需要，可以运行 scripts/extract_key_segments.py 获取文档关键段落。

“如果需要”这个条件给了模型太大的自由裁量权。它可能会自行判断“不需要”，然后跳过这一步。这个推测很有价值：问题可能不在于模型不听话，而在于我的指令里给了它“可以不听话”的选项。

第四步，修改表述后实测。我把指令改成：

必须首先运行 scripts/extract_key_segments.py，将输出的关键段落作为本次审阅的主要依据，不允许跳过此步骤。

修改后重新测试，模型确实调用了脚本。但让我意外的是，问题并没有完全解决——脚本被调用了，但输出结果是空的。排查脚本本身才发现，脚本依赖一个第三方库，而当前环境没有安装，代码静默失败，没有抛出任何错误提示。

4.3 结论和方法论：把每次失败当成“输入设计问题”

第四步的发现让我重新反思整个排查过程：模型其实一直都在遵循我的指令，这一步的失败不是模型的“主观不执行”，而是脚本自身故障。但如果我的SKILL.md从一开始就写了“不允许跳过此步骤”，问题会暴露得更早，因为模型会在尝试调用脚本失败后就卡在这个步骤上，而不是默默“发挥”绕过障碍。

这次经历让我把一件事想透了：在Agent Skills的世界里，没有真正的“模型不听话”，只有“输入设计不到位”。指令里条件化、模糊化的表述，本质上是我们在模型面前打开了一扇“不这么做也可以”的侧门。你不想让它走侧门，就不要在指令里留门。

之后我再写SKILL.md，就遵守一个原则：能写“必须”就不写“可以”，能写“按顺序”就不写“自行决定”。规则的表达越接近“操作协议”，模型的行为偏差就越小。同时，每个脚本都要考虑失败场景：环境依赖是否完整、路径是否正确、无结果输出时是否要有明确报错。我后来给所有配套脚本加了一个统一的约定：任何脚本执行失败时，必须向模型返回明确的错误信息，而不是返回空结果。这样一来，模型至少能在自己的输出里告诉你“这一步出错了”，而不是“这一步不存在”。

5. 让Skill真正好用起来的细节优化

5.1 脚本输出控制：给模型“能消化”的数据

想在脚本输出和模型理解之间找到平衡，需要根据任务类型做不同处理。我的经验是遵循一条原则：脚本只算最终结论，不做完整分析。

还是拿“项目代码概览”为例。最初版本里，我让脚本输出项目中每一个Python文件的路径和行数，结果那些文件特别多，光路径列表就有几千行。模型读取这些内容之后明显变得不知所措，生成的模块总结非常泛泛。后来我调整思路：脚本只输出每个模块的汇总统计和依赖关系，个别异常文件的信息要单独标记出来。模型拿到的数据变少了，但可用性大幅提高。

这里的关键是：模型处理信息的注意力是有限的，你给它的“原料”应该像一道菜的主料，而不是把整片菜地都搬上桌。你要通过脚本把原始数据提炼成半成品信息，再由模型完成最终的判断和表达。这种分层协作的模式，是Agent Skills区别于普通提示词工程的核心所在。

5.2 多Skill协同与required_skills

做了一段时间之后，我的Skill数量逐渐多起来。面对这种情况，自然会产生一个疑问：如果任务需要多个技能配合怎么办？比如先“扫描项目结构”，再“按团队规范审查代码”，这两个操作本质上分属两个不同的处理流程。

Agent Skills里提供了required_skills字段来处理这类依赖，你可以在一个SKILL.md的frontmatter里声明它需要依赖其他技能。实际执行时，模型会先加载并执行被依赖的技能，再执行当前技能。我把“项目代码概览”和“代码审查”串起来做过一次实测：前者先输出了项目结构和模块划分，后者基于这个结果再进行审查，整个过程中两个技能各司其职，过渡很顺畅。

但这里要补充一个我的个人建议：不要过度依赖嵌套关系。技能之间一旦形成很深的调用链，排查问题会非常困难，因为任何一环的失败都会传导到最终结果。我一度尝试过做一个“万能项目经理”技能，它依赖五六个底层技能，结果模型在执行时频频出现跳步、漏步。后来我干脆把它拆成独立的几个技能，让用户按需调用，效果反而稳定得多。技能拆分的原则是：每个技能只做一件事，但把这件事做深做透。

5.3 版本迭代：给Skill做变更记录

Skill是代码，也是会腐化的文档。项目在演进，流程在调整，如果SKILL.md不跟着更新，它很快会变成一套“准确的旧流程”。我发现维护Skill最有效的方式，是像维护代码一样维护它。

具体来说，我会在SKILL.md的头部加一个版本号和变更记录：

--- name: 文档审阅 description: 当用户需要对一篇技术文档进行结构审阅时使用... version: 2.3 last_updated: 最近更新日期 changelog: - "2.3: 增加术语一致性检查步骤" - "2.2: 修复脚本在无第三方库环境下的静默失败问题" ---

有人可能会问：模型会看这些元数据吗？不一定每次都会，但当你面对一个旧的、有变化的场景时，版本记录能帮你自己快速回忆起改过什么。我实际体会最深的是：没有版本记录的SKILL.md，一旦改动后模型行为异常，你根本想不起来上次改的是哪一块。有了变更记录，回退或者排查都方便很多。

改Skill时还要注意一个“单一变量原则”：每次只改一个点，然后实测验证。如果你一次改了脚本输出格式、正文步骤顺序、description三个地方，出了问题你很难定位是哪一处引起的。这跟调试代码是一个道理，变量少，问题才能暴露得快。

6. 一些最终建议

最后聊几点基于我个人经验的建议，不一定绝对正确，但都是踩过坑之后得到的。

第一，从纯Markdown流程开始，不是所有东西都要配脚本。我第一次做Skill时总想着脚本越强大越好，后来发现一个只靠文字指令的写作规范类Skill，比那些依赖复杂脚本的技能稳定得多。先把手头最重复的那个任务固化成纯指令流程，跑通了再考虑加脚本。

第二，在SKILL.md里写明“输入质量要求”。我发现模型执行技能时，常常因为用户输入信息不足而被迫猜测。比如“审查代码”这个Skill，用户只说“看看这段代码”，但代码本身没贴出来，模型就会用自己脑补的示例代码来“演示”流程——这完全浪费了你设计的审核标准。我在一个Skill的正文里专门加了这条约束：“如果用户没有提供待处理的原文，请先向用户索要，不得自行生成示例”。

第三，定时更新你的description。模型行为变化不一定是它变得不聪明，更可能是你的Skill描述里某些词汇与现在用户的说法对不上了。比如用户现在习惯说“这个仓库架构如何”，而你技能描述里写的是“分析项目结构”，语义相近但措辞不匹配，匹配率就会下降。每隔一段时间，把真实用户的提问语句补充进description的正例里，这个小操作效果非常明显。

Agent Skills这套机制，说到底就是把“怎么教AI做事”这件事工程化。你不需要成为一个提示词大师才能稳定复现高质量的执行结果——把这些标准固化在一个又一个的Skill里，剩下的，就是慢慢积累和迭代。这个过程没有太多玄学，多做几个，做多了，手感自然就有了。