企业官网建设流程全解析

1. 先搞清楚：你写的到底是“提示词”还是“技能”

这段时间几乎所有的 Agent 开发教程都在推 SKILL.md，但我在实际看项目代码、帮朋友排查 Agent 问题的时候，发现一个特别普遍的现象：多数人把技能封装理解成了“把一段写得还算不错的提示词存成一个 Markdown 文件，然后说这就是技能”。

这话听起来有点扎心，但确实是当前 Agent 开发领域的真实状态。今天我想借这篇文章，把这个事掰开揉碎讲清楚：为什么不能把 Agent 技能写成提示词模板？SKILL.md 究竟和提示词模板差在哪里？以及从一段普通 prompt 升级成标准 SKILL.md 的过程中，具体要做哪些事。

先说结论：提示词模板是给“对话”用的，SKILL.md 是给“流程执行”用的。这俩看着都是文字，本质上完全是两类东西。如果你开发的 Agent 只是偶尔回答几个问题、生成几段文案，那提示词模板完全够用；但如果你希望 Agent 能自主完成一条完整任务链路——比如“拉取数据、清洗、分析、生成报告”——还指望它中途不出岔子、每一步都知道自己在干嘛，那就必须把技能结构化为 SKILL.md，而不是靠一段 prompt 硬撑。

这篇文章适合谁看？三类人最需要：一是正在做 Agent 开发、但总觉得“提示词越写越长、效果越来越差”的工程师；二是想把自己的工作经验沉淀成可复用技能的 AI 产品经理；三是刚接触 Claude 系、Codex、Google Agent 等开发框架，想搞明白 skill 和 agent 关系的初学者。我会把我在真实项目里踩过的坑、复盘过的写法、以及最终沉淀下来的实操模板，全部列出来。

1.1 提示词模板和 SKILL.md 的核心差异

先花点时间把概念对齐。

提示词模板，本质上是一段写给大模型的“一次性指令”。它的形态是：“请你扮演一个数据分析师，根据以下数据，输出一份包含结论、建议的报告……”这种写法在最简单的问答场景里没问题，但一旦任务变长、变复杂，问题就暴露了。

SKILL.md 则是把一项“能力”完整描述成一份操作手册。它内部有清晰的元信息区（frontmatter）、有处理逻辑、有步骤流程、有输入输出的约定、有示例、有质量检查清单，甚至还能挂在辅助脚本文件。模型读到这份手册时，不是在“读一段话然后自由发挥”，而是在“按一套标准作业程序（SOP）执行任务”。

我用一个生活化类比帮你记住这个区别：

提示词模板就像你在冰箱上贴了一张便利签：“记得把菜做完。”SKILL.md 则是一本菜谱：食材清单、切配标准、火候大小、哪一步容易出错、成品长什么样才算合格，全写得清清楚楚。

后者才是 Agent 能稳定复现的基石。便利签你可能每次看完都不一样，菜谱却能让一个完全没做过这道菜的人，把菜做得八九不离十。

1.2 SKILL.md 到底解决了什么问题

我在实际开发中总结下来，纯提示词写 Agent 技能，通常会撞上四堵墙。

第一堵墙：上下文长度墙。提示词模板只能写在 system prompt 或者首条消息里，模型上下文窗口是有限的。你写的步骤越多、示例越丰富，留给实际任务数据的空间就越小。而 SKILL.md 可以被 Agent 按需读取——当它识别到当前任务需要这项技能时，再加载对应文件，而不是把所有技能的全部内容预先塞在你的 system prompt 里。这一下就释放了大量上下文。

第二堵墙：技能复用墙。提示词模板是“写死”的，你在这一个项目里写的需求分析流程，很难直接迁移到另一个 Agent 项目。SKILL.md 以独立文件形式存在，天然具备模块化属性。我可以在不同 Agent 项目里共享同一套“结构化输出”技能、同一套“代码审查”技能，只需要通过目录约定装载即可。

第三堵墙：执行可控墙。写提示词模板时，你根本没法控制模型“先做一步验证再做下一步”。它可能跳步骤、可能顺序错乱、可能在某个关键校验点上直接忽略。SKILL.md 里的步骤流程可以拆得很细，并配上“检查点”——模型中途中途想跳步时，会被拉回来。

第四堵墙：调试维护墙。提示词模板出了问题，你只能靠“再改几个字”来试错，没有任何结构化信息能帮你定位问题。而 SKILL.md 是一个独立文件，反馈链路清晰：技能没生效就查 description 写得好不好；步骤执行不对就查正文逻辑；想升级技能，直接改文件版本号。

这也是为什么现在主流 Agent 开发框架都在推 SKILL.md——它把“写提示词”这种近乎玄学的事情，变成了“写配置、写逻辑、写文档”这种工程师容易上手的工作。说穿了，SKILL.md 是提示词工程的工程化解决方案。

2. SKILL.md 的内部结构拆解：一个文件就是一个完整技能

很多教程都讲 SKILL.md 的结构，但讲得都太浅，往往只给你看一个 YAML 头就结束了。这里我把我实际项目中稳定在用的完整结构展开讲，包括每个字段的作用、正文应该怎么写、以及目录里除了 SKILL.md 还应该放什么。

2.1 YAML Frontmatter：技能的元信息层

SKILL.md 顶部的 YAML frontmatter，是整个技能文件的“身份证”。它决定了 Agent 什么时候调用这个技能、怎么调用、以及调用时应该带上什么信息。我用一个实际例子说明：

--- name: weekly_report_generator description: 根据团队本周的工作日志，输出结构化周报。当用户提供工作内容列表、要求生成周报、或提到“周报”“weekly report”时使用。输入为工作事项列表或原始日志文本，输出为符合团队模板的周报 Markdown。 when_to_use: 用户需要整理周报、日报，或需要对零散的工作记录进行结构化汇总时 version: 1.2.0 dependencies: - python3 - pandas ---

这里最关键的是description字段。很多人写 description 时只写一句“生成周报”，结果就是技能根本不会触发——因为 Agent 在判断“当前任务是否需要这个技能”时，靠的是语义匹配，不是你的文件名。

好的 description 必须包含四类信息：

• 技能解决的问题：这个技能是用来干什么的，一句话说明。
• 触发信号：用户说什么话、出现什么场景时，应该调用这个技能。
• 输入格式：调用技能时，需要提供什么样的数据。
• 输出格式：技能返回什么，是 Markdown 文档、JSON 数据，还是指令代码。

我在实际项目中踩过一个坑：当初给数据分析技能写的 description 太泛，结果用户随便问一句“这个数据怎么样”就触发了技能，而技能内部又没有处理“宽泛提问”的逻辑，Agent 自己生成了一个毫无依据的分析报告。后来我重写 description，明确写明“仅当用户提供了具体的数据文件路径或数据结构描述时触发”，误触发率立刻降下来了。

另外两个字段也需要提一下。when_to_use字段目前不是所有框架都支持，但我发现写上它有一个额外好处：它强制你自己想清楚“这个技能的适用边界在哪”。如果没有边界意识，一个技能很容易被写成“万能工具”，最后什么都干不好。version字段则是我强烈建议保留的，技能文件会持续迭代，没有版本号，改坏了想回退都难。

2.2 正文 Markdown：Agent 的操作手册

frontmatter 下面是正文，这是 SKILL.md 真正的核心。和提示词模板不同，正文不是写给用户看的，而是写给 Agent 当操作手册用的。写法上有一条核心原则：

每一项指令都必须能被验证，不能是“尽力而为”的模糊指令。

举个反例，很多人这么写正文：

“请对数据进行分析，得出有价值的结论，并提供建议。”

模型读完这句话根本不知道什么叫“有价值”。它只能自由发挥，结果就是每次输出的风格、结构、深度全都不一样，技能就失去了意义。

我推荐的正文结构大概是这样的：

# 周报生成技能 ## 步骤一：收集输入 - 从用户消息中提取工作事项列表，若用户未提供结构化列表，逐一询问补充 - 将事项按“已完成 / 进行中 / 阻塞”三态进行分类 ## 步骤二：撰写周报正文 - 每个事项使用以下格式： - 事项名称： - 当前状态： - 本周进展（最多两行）： - 阻塞问题（可选）： - 若事项超过 10 条，按项目维度合并同类项 ## 步骤三：质量检查 - 检查所有事项是否都包含状态标记 - 检查是否所有“阻塞”状态的事项都补充了阻塞原因说明 - 检查总字数是否在 800 字以内，超出则删减冗余描述 - 检查通过后方可输出，否则回到步骤二修正

这样的写法，模型每一步都有明确的输入、操作、输出标准。尤其是“质量检查”这一步，很多人写提示词时完全忽略，但它是让 Agent 输出稳定的关键：让模型自己扮演评审者，而不是一次生成就完事。

正文里还可以加入“反例”区块。模型在推理时如果有“这个不能做”的负向约束，会比只有正向指令时表现更稳。比如在周报技能里，我会写：

## 禁止事项 - 不得编造未发生的工作内容 - 不得将用户闲聊内容自动转为正式工作事项 - 不得把阻塞原因写成主观评价（例如“同事很慢”），需改为客观描述（例如“等待前端接口交付”）

2.3 辅助文件：代码、脚本、模板怎么组织

一个完整的 skill 目录，通常长这样：

weekly_report/ ├── SKILL.md ├── assets/ │ ├── report_template.md │ └── example_report.md └── scripts/ └── format_checker.py

assets 目录用来放静态模板和示例，scripts 目录用来放可执行脚本。为什么不能让 SKILL.md 把所有东西都塞进去？两个原因：

第一，上下文成本。SKILL.md 太长，Agent 加载技能时占用的上下文就越多。我的经验是：正文控制在 200 行以内，需要展示的模板、示例全部外置到 assets，Agent 需要时再读取对应文件。

第二，可维护性。模板文件经常要改，技能逻辑不常改。如果模板内容直接嵌在 SKILL.md 正文里，每次改模板都可能误触正文里的结构，增加出错概率。

有一个点要特别提醒：不是所有框架都会自动读取 assets 和 scripts 目录，具体要看你的开发框架支持情况。在 Claude 系 Agent 开发中，辅助文件的支持力度比较大；但一些轻量级框架只认 SKILL.md 单文件。入手前先去翻一下框架文档，别辛辛苦苦建好目录结构，最后发现 Agent 根本不读。

3. 实战迁移：把一个“周报提示词”升级成完整 SKILL.md

理论说再多，不如走一遍迁移过程。这一节我拿一个真实场景——团队周报生成——来完整演示怎么把一段普通提示词“翻译”成标准 SKILL.md。你跟着做一遍之后，就能掌握这套方法论，迁移到任何类似技能场景。

3.1 大多数人的原始提示词长什么样

我见过最典型的“写周报提示词”，长这样：

“你是一个周报助手，请根据我提供的工作内容，撰写一份周报，要求条理清晰、重点突出。内容大致包括本周进展、问题风险和下周计划。”

这段提示词，如果用现在的标准去审视，至少存在以下问题：

• 没有定义输入结构：用户可能给的是“周一修了两个 bug，周二开会对需求”，也可能是“1. xxx 2. xxx”的列表。输入格式不固定，模型每次结构化信息的标准就不同。
• 没有定义输出模板：什么叫“条理清晰、重点突出”？不同模型、不同轮次生成出来的格式可能完全不一样。
• 没有质量检查机制：写完之后没有自检，可能出现漏项、编造、格式错乱。
• 没有边界：用户没说清楚工作内容时，模型不知道该追问还是该硬猜。

这就是典型的“便利签”式提示词。单看好像没什么问题，但一旦你希望它稳定输出、每次格式统一、甚至下游对接自动化流程，就会立刻发现在裸奔。

3.2 迁移后的完整 SKILL.md 示例

下面是我实际在用的完整版本，你可以直接抄走用：

--- name: weekly_report description: 根据团队成员提供的本周工作日志，生成符合团队模板的周报。当用户提供工作记录、提到“写周报”“生成周报”“weekly report”时使用。输入为工作事项文本，输出为结构化 Markdown 周报。若用户仅说“写周报”但未提供内容，请先追问本周完成事项。 when_to_use: 周报生成、日报整理，或需要把零散工作记录汇总为结构化汇报文档时 version: 2.1.0 ---

正文部分：

# 周报生成技能 ## 角色定位 你是一名团队周报整理助手，你的目标不是生成美化文本，而是把用户提供的原始工作记录，准确地转化为标准结构的周报。严格基于输入内容，不做任何编造。 ## 步骤一：输入解析 1. 从对话中提取本周工作事项列表。 2. 若原始记录中包含日期信息，按日期排序；若无日期，按事项类型归组。 3. 确认清单：所有事项必须至少包含“主体动作 + 对象 + 结果”三要素。缺少要素时，列出缺失项并向用户确认，不得自行猜测补全。 ## 步骤二：事项归类 将事项归入以下四类： - 功能开发：涉及新功能、新模块的编码与实现 - 问题排查：涉及 bug 修复、线上问题定位、性能调优 - 协同沟通：涉及会议、跨团队协调、需求评审 - 其他：无法归入以上三类的杂项 ## 步骤三：结构化输出 输出格式严格遵循以下模板： ### 本周进展 - 【功能开发】事项一（一句话描述） - 【问题排查】事项二（附解决状态） ### 风险与阻塞 - 事项三，风险描述：等待第三方接口文档，已阻塞 2 天 ### 下周计划 - 计划一（用动词开头，如“完成”“推进”“评审”） ## 步骤四：质量检查 输出前逐项自检： 1. 每个事项是否标注了分类？ 2. 风险和阻塞是否有具体原因说明？ 3. 下周计划是否以动词开头？ 4. 是否存在编造内容？ 四项全部通过后才可输出；任一不通过，回到对应步骤修正。 ## 禁止事项 - 不得在周报中写入与用户输入无关的内容 - 不得把模糊描述直接写成确定结论 - 不得省略质量检查直接输出

3.3 迁移逻辑：为什么这样拆分更好

对比一下迁移前后的差异，你会发现核心改进是这四个维度：

输入从“随缘”变成“有约定”。原来用户发什么你收什么，现在先做输入解析和要素确认。这从根本上杜绝了“模型在信息不全时硬编”的情况，大幅提升输出可信度。

流程从“一步”变成“四步”。原来的提示词是一句话指令，模型要一次性完成“理解输入、归类整理、生成文案、保证质量”全部工作。现在拆成四步，每步只做一件事，每一步的执行质量更容易保证。对大模型来说，复杂任务拆细了，每一步的准确率都显著提高。

输出从“自由发挥”变成“模板套用”。模板不是限制模型发挥，而是给模型提供了明确且稳定的目标。四类事项的分类标准、周报的各段模板、动词开头的下周计划要求……每一条都是可验证的，输出不达标时模型能明确知道哪里不合格。

自检从“可选”变成“必须”。质量检查那一步，是很多提示词使用者最容易忽略，但对结果稳定性影响最大的设计。它让模型在输出前多一次“审核”的过程。实测下来，加了这个环节之后，周报格式达标率能从原来的 60% 提升到 95% 以上。

4. 真实场景中的效果对比：三种 Agent 任务的技能化改造

周报只是一个简单样本。我把这个方法迁移到几个实际项目里之后，发现不同任务类型对 SKILL.md 的侧重点完全不同。这里展开讲三个有代表性的任务类型，方便你对照自己的场景。

4.1 数据清洗类技能：重逻辑、重校验

数据清洗是典型的“看似简单、实际极易翻车”的 Agent 任务。最初我用提示词让 Agent 做清洗，结果它经常发挥不稳定：这次会删掉空值，下次把有业务含义的 0 也删了；这次知道日期格式要统一，下次又忘了转时区。

做成 SKILL.md 之后，我把清洗规则明确拆成按优先级排列的检查步骤，并在关键改动点埋了“确认逻辑”：

## 清洗步骤 1. 先探查数据全貌：字段类型、空值比例、重复率，并把探查结果记录下来 2. 空值处理：仅对“数值型且业务上可忽略”的字段执行删除或填充；对于主键、金额字段出现空值，直接标记为异常并停止下一步处理 3. 重复值处理：先确认重复判定维度（全字段还是指定字段），再执行去重 4. 格式清洗：日期统一为 YYYY-MM-DD；金额统一为数字类型并保留两位小数 5. 输出前必须生成清洗报告：改动行数、删除比例、异常字段列表

这里面最重要的一条是：每一步清洗动作都必须能被审计。原来的提示词只告诉模型“清洗数据”，模型不知道自己改了哪些数据、为什么改。现在每一步都有记录、有报告，用户可以对 Agent 的操作进行复核。数据任务不比写文案，模型写错一句可以重来，数据改错了代价就大了。

用这个思路改造之后，我做过一个小统计：数据清洗类任务的返工率从 40% 左右降到了 10% 以内，而且排查问题时可以直接看清洗报告定位逻辑漏洞，不再需要整条重跑。

4.2 文档生成类技能：重模板、重一致性

文档生成是 Agent 最常见的应用场景，但也是被做成提示词模板重灾区。技术方案、产品 PRD、面试复盘、小说章节……只要是“写文档”，很多人第一反应就是写一段“请你扮演某角色，以某风格生成某文档”。

这种用法不是不行，但问题在于：当你的文档有固定结构要求（比如公司内部方案模板、特定格式的竞品分析），纯提示词几乎无法保证每次生成的章节编号、标题层级、段落长度完全一致。

我给文档生成类任务做 SKILL.md 时，核心思路是“模板优先”：

• 在 assets 里挂一个标准模板文件，模板文件中写清楚章节结构、每章节预期字数、必须包含的要素。
• SKILL.md 正文只写“如何往模板里填内容”的逻辑：信息从哪来、哪些信息缺失时需要追问、哪些内容需要查证、什么情况需要附数据来源。
• 模板里预留可变量标记（例如 {项目名称}、{日期}），Agent 生成时把对应位置替换掉。

这个方法有个额外的好处：模板和技能逻辑可以分别迭代。公司改版了文档规范，只需要改模板文件，技能逻辑完全不动。如果用纯提示词，每次改格式都要重新调一段长文本，痛苦极了。

4.3 代码修复类技能：重上下文、重闭环验证

代码修复任务，是所有技能类型里对上下文要求最高的一种。Agent 要理解项目结构、定位 bug、修改代码、跑测试、再验证结果——这个链路太长了，任何一步信息缺失都会导致后续工作全错。

一开始我用提示词让 Agent 修 bug，发现它经常犯一个毛病：只改它看到的那个文件，不去检查关联调用方。比如修了一个函数的参数校验，但调用方还在用旧参数结构，结果项目直接运行报错。这就是典型的提示词无法覆盖“闭环验证”需求。

SKILL.md 版本里，我在正文里规定了严格的修复流程：

## 修复步骤 1. 先复现问题：运行报错场景或阅读报错堆栈，确认问题根因 2. 定位影响面：使用 grep 或 IDE 全局搜索，查找相关函数的所有调用位置 3. 执行修改：修改时保持最小改动原则，不得顺手重构代码 4. 验证闭环：运行相关测试用例，若项目无测试，至少执行一次调用链上的完整验证 5. 输出修复说明：问题根因、修改文件列表、验证结果

特别要提的是第 4 步“验证闭环”。这条规则在纯提示词里基本没人写，而在 SKILL.md 里它就是一个硬性步骤。模型执行到这一步时，如果有测试框架，会直接跑测试；没有测试也要在输出前明确标注“未验证”，让使用的人心里有数。加上这一步之后，我这边代码修复任务的“改完还是坏”的情况少了一大半。

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

最后这部分，是我在大量实际项目中踩出来的雷，整理成一份问题速查表。你先收藏，遇到问题时候翻出来对照。

5.1 SKILL.md 写了不生效，Agent 始终没有调用技能

这是最常见的问题。我自己也犯过好几次。通常有三个排查方向：

第一，description 写得太窄或太偏。Agent 选择技能靠的是语义匹配，如果你的 description 里没有覆盖用户常见的表达方式，技能就永远“躺在抽屉里”。我的建议是：把 description 写完之后，设身处地列 10 种用户触发这句话的变体说法，看看你的 description 能不能覆盖到。覆盖不了就扩写。

第二，技能文件没有放在正确的目录下。不同框架对 skill 目录的约定不同。Claude 系的项目比较规范，通常把技能放在项目的.claude/skills/目录下，一个技能一个子目录；但其他框架不一定按这个规则来。部署技能前，第一步就是确认你的框架加载技能文件的约定路径。

第三，技能路径有命名问题。文件夹名和 SKILL.md 内部的 name 字段不一致时，部分框架会拒绝加载。避免踩坑的做法是：目录名、文件名、name 字段保持完全一致，用下划线命名法，不用空格和中文。

5.2 技能把内容输出了，但质量不稳定

技能生效了，输出时好时坏，这时候问题大概率出在正文写得不够“死”。我的经验是：能让模型做判断题的地方，就不要让它做开放题。

比如你写“请整理一份简洁的报告”，这就是开放题，模型不知道“简洁”是 300 字还是 800 字。你改成“报告正文总字数控制在 500 字以内，分三个小节，每小节至少包含 2 个数据点”，这就变成判断题/填空题了，执行结果会稳定得多。

另外，正文里的“质量检查”步骤也不能省。那一段不是在凑字数，而是让模型在输出前强制进入一次“复盘模式”。这一步能显著减少格式错乱、漏项、编造内容等问题。

5.3 多个技能之间互相干扰

当你的 Agent 项目里挂了好几个技能时，可能会出现一种很闹心的情况：明明用户问的是 A 技能的问题，Agent 却调用了 B 技能。原因通常是两个技能的 description 描述范围重叠了，或者其中一个技能的描述写得太泛。

解法有两个方向：

• 收紧 description 边界。在 description 里明确写明“不适用于什么场景”。比如财务分析技能里写明“不适用于通用聊天”，数据分析技能里写明“仅处理结构化数据，不做文本生成”。负向描述能有效减少误触发。
• 调整技能粒度和优先级。如果你的技能体系越来越大，可以拆成“基础技能”和“场景技能”两层。基础技能管通用能力，场景技能在用户特定任务出现时才被调用。这个分层逻辑越早规划，后面技能多了越省心。

5.4 技能里的指令 Agent 读了但执行不到位

有时候你明明在正文里写了“步骤四：输出前必须自检”，模型还是跳步了。这种情况在长流程任务里特别常见——模型生成到最后一步时，“忘了”前面的约定。

我的建议是：把关键约束同时放在多处，而不只是放在正文中间。

具体做法是：

• 在步骤描述里写一次自检逻辑。
• 在最后的“禁止事项”或“质量检查”区块里再写一遍关键约束，强制输出前重新看一次。
• 特别重要的输出格式，直接以“输出示例”形式给出来，放在正文末尾。

模型在生成答案的收尾阶段，往往会重新参考文档末尾的信息。只要关键约束在尾部再次出现，执行不到位的情况就会减少。

5.5 关于跨框架迁移的一个提醒

最后说一个很多人容易忽略的现实问题：SKILL.md 并不是一个统一标准，不同框架对它的支持程度不一样。有的框架支持 YAML frontmatter 完整字段，有的只解析 name 和 description，有的框架完全只把正文当提示词用。

所以，当你在一套框架里写好的技能文件迁到另一套框架时，不要想着“复制粘贴就能跑”。我习惯的做法是：先读目标框架的 skill 文档，确认字段解析范围，再写一份最小技能文件做加载验证，最后再把完整技能迁过来。效率看似低了，实际上避免了迁移后出现一堆莫名其妙的兼容问题。

最后再分享一个我个人的习惯：我会每隔两到三周回看一次技能文件的调用日志，而不是写完就丢在那里不管。技能描述里的触发词会不会过时？步骤里有没有哪一个环节模型经常反复出错？那些躲过了所有排查的隐藏问题，往往在这里露出马脚。技能文件和代码一样，不是写完就算了，它需要你持续维护，才能真正成为 Agent 的可靠肌肉记忆。