企业官网建设流程全解析

最近大半年，“skills”这个词在智能体开发圈里的出镜率实在太高了。如果你用过某个主流AI编程工具，大概已经注意到它不再只是一个“聊天框”，而是多了一个会自己写代码、自己跑命令的“子代理”协作层。而支撑这个协作层的核心能力，就是 Skills——一套把零散的提示词、脚本和领域知识打包成“可复用技能包”的机制。

我第一次真正理解 Skills，不是靠官方文档，而是在一次日志排障任务里被“打醒”的。那次子代理渲染了十几个 Skill 文件，却没有一个命中问题场景，模型反复在通用推理里打转。我意识到：Skill 不是简单地写一个 Markdown 文件塞给模型，它背后涉及的是一整套“按需读取、渐进披露、上下文预算”的设计思路。这篇内容，我想把 Skills 从“是什么”到“怎么写、怎么装、怎么避坑”完整拆给你看，尤其是那些文档里不会明说的经验细节。

无论你是刚开始接触 Agent 开发、写过一段时间提示词但还没系统化，还是已经在尝试做自己的技能库，这篇文章都会给你一套可以直接上手的套路，以及我自己踩过坑之后的取舍逻辑。

1. 什么是 Skills：从能力封装到“按需翻手册”的思考框架

1.1 从一句描述到一整套能力

先给一个最直白的定义：Skills 是指一类以文件夹为单位进行组织、以 Markdown 为主文件（通常叫 SKILL.md）进行描述、可附带脚本和参考资源的能力封装单元。它和一段普通提示词最大的区别，在于它不光告诉模型“你要做什么”，还告诉模型“你要在什么时候调用自己、如何按步骤执行、遇到问题去翻哪份参考文档、需要时运行哪个脚本”。

放到生活里类比，普通提示词像是给新人发一张 A4 纸，上面写着“遇到用户报错就帮忙排查”；而 Skill 则像是交给新人一本岗位手册：手册封面写着“适用于什么场景”，翻开来是操作流程，附赠一份快速判断表——什么错误先看什么日志、哪些异常要优先处理，最后页兜里还放了一把专用的检测工具。模型拿到这种技能包之后，处理问题的方式从“临场发挥”变成了“按规程执行”。

我刚开始接触这个概念时犯的第一个错误，是把它当成“加强版提示词”来写。就是把以前写的一大段指令整理成 Markdown，然后放到一个叫 skills 的目录里，且全部内容都塞在主文件里，一个 Skill 动不动写几千字。结果模型每次进入子代理都要把这些内容全部读一遍，上下文开销大得离谱，而且因为信息太杂，模型经常抓不住触发场景。后来我才意识到，Skills 的真正设计精髓，是“渐进式披露”——不是把全部内容一次性暴露给模型，而是只暴露必要的“封面信息”，等模型决定调用之后，再让它按需读取更深的细节。

1.2 渐进式披露：像人一样“先看目录，再翻章节”

渐进式披露这个词听起来玄，其实是咱们写文档早就用过的逻辑：先有总览、目录，再有章节、附录。Skill 体系把这一逻辑变成了可执行规则。

一个 Skill 文件夹里的 SKILL.md 主要承担两件事：第一，用简洁的 frontmatter 告诉模型“我是谁、我解决什么问题、我适合什么时候被启用”；第二，用正文提供一个精炼的操作骨架。真正的大段代码规范、详细的参数表、领域知识背景，应该拆到同文件夹下的 references 或子目录里，由 SKILL.md 里的链接或路径按需引用。

这样设计的直接好处是算力成本和效果的双赢。每次子代理启动或任务分派时，系统只需要把 SKILL.md 的“头部信息”注入上下文，模型就知道有哪些技能可选，却不用为此付出阅读全部细节的 token 成本。等它判断当前任务匹配到了某个技能，再根据正文里的指引去加载 references 下的详细内容。用一句行话讲，这就是“用元数据换命中率，用深链路换准确率”。

所以，写 Skill 的第一课不是怎么写正文，而是怎么克制正文的长度。你要像写简历一样对待 SKILL.md：一页纸说清楚优势在哪，别把完整项目报告绑在简历后面。细节留在附件里，等对方有兴趣了自然会看。

1.3 一次封装，处处可用：Skill 的三层组成

经验上，一个能稳定复现的 Skill 通常包含三个层次。

第一层是元信息层，也就是 SKILL.md 开头的 YAML 格式 frontmatter。它至少应该声明技能名称（name）、适用场景（description 或 when_to_use）以及版本号（version）。其中“触发描述”常常被新手忽略，但实际上，它决定了子代理愿不愿意在你期望的场景里启用这个技能。别写“用于处理日志”这种泛泛的话，而要写“当用户提供应用日志、堆栈跟踪或线上报错信息，希望定位异常原因时使用”。

第二层是执行层，也就是 SKILL.md 正文里定义的操作步骤。这里要用祈使句、分步骤，给出模型可以照着执行的明确动作。我曾经对比过两组技能描述，一组写着“分析错误并给出建议”，另一组写着“第一步先提取日志中的时间戳与日志级别，第二步按级别排序并聚合相同错误，第三步对照常见错误对照表给出根因判断”。后者的效果明显更好，因为它把“隐性知识”变成“显性流程”。

第三层是资源层，也就是存放在 Skill 文件夹内的脚本、参考文档、模板文件等。脚本可以用 Python、Shell 或任何可执行工具，但要注意避免硬编码路径和过度依赖本机环境。参考文档则建议按用途拆分，比如“常见错误对照表”“敏感信息脱敏规范”“正则表达式速查”等。这样等模型真正进入任务时，能快速定位到自己需要的部分，不必从头扫到尾。

2. 为什么需要 Skills：传统提示词方案的三个痛点

2.1 上下文窗口是稀缺资源，Skills 是“对 token 的精细投资”

做过 Agent 开发的人都知道，上下文窗口再大也不是无限大。只要输入变长，不仅费用往上涨，模型在中途把注意力转移到次要信息的概率也会变大。尤其在多轮任务里，每轮都要追加一段超长提示词，上下文很快就被无效信息填满，反而把一个简单任务拖成长篇大论的“失焦表演”。

Skills 解决的，正是“知识怎么进上下文，什么时候进上下文”的问题。它不要求你提前把所有技能细节塞进系统提示，而是让知识留在外部、按需加载，需要时才进入上下文。这种做法节约的 token 是按倍数算的：以前每次带 3000 字的行业规范进对话，现在只在模型发起调用时加载其中的 500 字，使用率却能反而提高。我把这个过程理解为“对 token 的精细投资”——花出去的每一分钱，都要换取更精准的决策质量。

2.2 提示词工程难以复用，Skills 是“可安装的知识包”

传统的提示词工程，最大的问题是复用性太差。你在一段任务里调好的指令，换个项目、换台机器可能就要重新调。就算你把提示词存成模板，模板里那些上下文变量、案例引用也经常变得僵硬，和实际任务对不上。

Skills 把这个问题变成了文件系统问题：一个 Skill 是一个独立目录，自带版本、作者、描述、脚本和参考资源。它天然适合放进 Git 仓库做版本管理，也适合分发和安装。你不再需要复制粘贴大段提示词到新项目里，而是把技能目录克隆下来，放到专门的技能目录，再在配置里声明一下就能用。也就是说，提示词时代靠“复制”，Skills 时代靠“安装”。

我做过的模拟项目 X 里，大概维护了十几个针对不同任务类型的技能包。每次新任务进来，我基本不用重写提示词，只需要在技能目录里挑出可能相关的几个，让模型根据 frontmatter 做匹配。项目切换时，整个技能库直接带走。这种体验是传统提示词工程完全不具备的。

2.3 Skills 与实时工具调用（MCP）的分工：不是替代，而是互补

经常有人问我：有了 Skills，是不是就不需要 MCP 这类工具调用了？我的看法恰恰相反，两者解决的是根本不同的两个问题。

MCP 提供的是“连接外部系统的实时能力”，比如让模型读取某个数据库、查询某个 API、操作某个 Git 仓库。它的核心价值是“动”，是让模型能够影响外部世界。而 Skills 提供的是“完成特定任务的领域专长”，核心价值是“知”，是让模型知道某类任务该怎么拆解、用什么标准判断、参考哪些经验。

官方的建议也是至少一半以上通用场景优先考虑用 Skills，而不是 MCP。原因是 MCP 每次调用都要走网络、起服务、冒安全风险，而 Skill 只是读文件、跑脚本，天然更轻、更快、更可控。如果要把一个能力复用给团队或社区，Skill 也比 MCP server 简单得多，因为后者要维护一个长期运行的服务进程，而前者只是“文件 + 脚本”，版本管理友好，故障也容易排查。

所以，合理的设计是：用 Skills 把“做事的方法”沉淀下来，用 MCP 把“接触的数据和系统”接进来。二者互相配合，而不是二选一。

3. 手把手构建一个日志分析 Skill：从需求到可复现

3.1 需求定义与目录结构设计

做任何 Skill，第一步不是写文件，而是先把任务边界和产出标准想清楚。拿日志分析来举例，假如我们希望这个 Skill 能自动完成“输入一段或多段日志 → 分析异常 → 输出根因和修复建议”，那就要明确几个问题：日志是什么格式的？分析结果按什么标准组织？要不要生成报告文件？

定义清楚之后，再设计目录结构。一个标准的日志分析 Skill 目录大概长这样：

log-analyst/ ├── SKILL.md ├── scripts/ │ ├── parse_log.py │ └── summarize_errors.py └── references/ ├── common_errors.md └── log_levels.md

SKILL.md 是入口，scripts 放解析和聚合脚本，references 放静态参考。这个结构的好处是把“动态逻辑”和“静态知识”分开。动态逻辑交给脚本处理，模型负责编排和决策；静态知识放进 references，模型在需要判断时再查询。分工清晰后，即使以后要更新某个部分，也不会牵一发动全身。

3.2 SKILL.md 的核心写法：前置声明与正文结构

SKILL.md 是模型第一个读到的东西，如果你只打算花 10 分钟去优化一个 Skill，就把这 10 分钟全花在它身上。下面是我长期打磨后稳定好用的一份模板：

--- name: log-analyst description: 分析应用日志与错误堆栈，定位异常原因并给出修复建议。当用户提供日志文本、错误堆栈或希望排查线上问题时使用。 when_to_use: 用户直接粘贴日志、导出日志文件、或描述线上报错现象并希望定位根因时。 version: 1.0.0 ---

正文部分我会按照“先收集、再结构化、后判断”的顺序组织：

1. 读取用户提供的日志来源，确认日志格式。如果是文件，先检查文件编码与大小，避免乱码和超大文件。
2. 调用 scripts/parse_log.py，提取时间戳、日志级别、模块名、关键消息，并按级别和模块聚合。
3. 根据聚合结果，结合 references/common_errors.md 中的对照表判断异常类型。若日志包含堆栈信息，提取异常类名和出错模块。
4. 输出结果时遵循固定格式：异常摘要、故障模块、可能原因、修复建议、相关日志片段。
5. 若日志中出现敏感信息，按 references/脱敏规则 处理后再输出。

这份正文的特点是每条都以动词开头，而且明确指向具体的执行动作。模型不需要猜测“应该分析到什么程度”，因为你已经把“分析到什么程度”定义得很清楚。还有一个细节：引用 references 时我写的是相对路径，这样拷贝整个目录到别的机器也不会断链。

3.3 用脚本把静态知识变成动态能力

Skill 不是只能写 Markdown。真正让它“有手有脚”的，是配套脚本。比如日志分析场景，光靠模型在上下文里人工数错误级别，又慢又容易漏。我通常写一个 Python 脚本先把原始文本标准化。

下面是一段简化版的脚本思路，用于演示关键逻辑：

import re from collections import Counter def parse_logs(text): pattern = re.compile( r'(?P<timestamp>\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2})' r'.*?(?P<level>DEBUG|INFO|WARNING|ERROR|CRITICAL)' r'.*?(?P<message>.*)' ) rows = [] for line in text.splitlines(): m = pattern.search(line) if m: rows.append({ 'timestamp': m.group('timestamp'), 'level': m.group('level'), 'message': m.group('message').strip(), }) return rows def summarize(rows): level_counter = Counter(r['level'] for r in rows) error_buckets = Counter() for r in rows: if r['level'] in ('ERROR', 'CRITICAL'): # 按去掉参数后的消息模板聚合，比如 user_id=123 归一到 {} template = re.sub(r'\b\w+=\S+', '{}', r['message']) template = re.sub(r'[\d]+', '{}', template) error_buckets[template] += 1 return level_counter, error_buckets.most_common(10) if __name__ == '__main__': sample = open('sample.log').read() rows = parse_logs(sample) levels, top_errors = summarize(rows) print(levels) print(top_errors)

这里的核心技巧是“聚合相似错误”：真实线上日志里，同样的错误会因请求 ID、用户 ID 不同而显得千变万化。如果不做模式归一化，模型会把同一条错误当成几十条来处理，分析结果自然不准。脚本先按模板聚合，把“用户 123 下单失败”和“用户 456 下单失败”归并成“用户 {} 下单失败”，统计量一下子清晰了。这个细节也是我在真实场景里反复调优后才加进去的，效果立竿见影。

3.4 测试与迭代：让模型真正“用起来”

写完 SKILL.md 和脚本，并不代表大功告成。Skill 必须经过“冷启动测试”：开一个全新会话，不提供任何额外提示词，直接把日志文件或日志文本丢给子代理，看它能不能主动启用 log-analyst 这个技能，并按正文步骤执行。如果模型从头到尾都没有提到这个 Skill，问题大概率出在 frontmatter 里的 when_to_use 写得太笼统或者正文步骤不够可执行。

我在一次测试里发现，模型确实调用了 Skill，但执行时跳过了脚本，直接在上下文里数错误，结果漏了两条重复异常。排查后发现是步骤写得太轻，模型认为自己也能完成，就没必要跑脚本。修正方式是加一条硬性约束：“必须运行 parse_log.py 对原始日志进行结构化，严禁跳过脚本直接人工阅读”，并在正文中给出脚本运行方式和预期输出。改完再冷启动测试，命中率显著提升。

迭代 Skill 的最高效办法，是“用失败的对话喂给下一个版本”。每次测试发现模型做了你不期望的操作，就把这段会话记录下来，然后在 SKILL.md 中增加一条明确规则去约束它。两三轮之后，这个技能会变得非常贴合你的工作习惯，远超通用的系统提示词。

4. 发布、发现与安装：让 Skill 流动起来

4.1 发布流程与版本管理

单个 Skills 的价值有限，真正有价值的是技能生态。如果你把 Skill 做得靠谱，可以发布到社区仓库或企业内部的技能索引里，让别人以极低的成本复用。发布前有几件事必须做：第一，检查目录里有没有隐私或敏感信息，日志模板、真实 IP、密码片段一律别放进去；第二，在 SKILL.md 里把版本号写清楚，并建议遵循语义化版本规则——主版本变动代表行为不兼容，次版本代表功能增强，补丁代表文档或小修小补；第三，补一份简单的 README，说明这个 Skill 适合什么场景、依赖什么环境、怎么跑测试。

版本管理上，我一直用的是文件夹名加版本号的方式，比如 log-analyst-v1，避免直接覆盖旧版本。因为技能行为是否兼容，往往要实际测试才知道，保留旧版本可以在回退时省很多事。用 Git 管理整个技能目录库，每次改动都能留下提交记录，出了回归问题也容易定位。

4.2 安装机制与自动更新：三类主流方式

Skills 的安装方式，不同平台略有差异，但基本可以归为三类。

第一类是命令安装，通过包管理工具或专用 CLI 从仓库拉取指定技能。这类方式适合有适配器和网络环境的场景，平时我更新技能库时最常用它，一条命令就能把若干技能同步下来。第二类是文件安装，把 Skill 文件夹放到用户级技能目录，例如某平台桌面端的 ~/.config/xxx/skills/ 下，刷新后即可生效。这种方式最适合本地开发，我改完一个技能后通常直接观察平台上是否加载到新版本，不依赖任何安装流程。第三类是自动更新机制，由平台或工具定期从远程仓库拉取技能列表，检测到版本号变化后自动替换。这类方式最省心，但也要注意：如果技能目录里本地做过修改，自动更新可能覆盖你的改动，常见做法是加一个忽略清单或使用分支管理。

我自己的实践经验是：个人使用偏向文件安装，速度最快、可控性最强；做团队共享或公开发布，则用命令安装 + 版本管理分开处理，这样线上线下的同步逻辑都很清楚。

4.3 子代理中的“最小渲染”机制：只把封面给人看

Skills 在子代理中的工作方式，很多人理解得有偏差。子代理启动时不会把技能目录里的所有文件全部读出，而是先扫描整个技能列表，只渲染每个 SKILL.md 的 frontmatter 部分，也就是“名字 + 触发描述”。模型看到的是简洁的技能索引，而不是几百个技能的完整内容。

只有当下的任务与某个技能的描述匹配，模型才会加载该技能目录下的 SKILL.md 正文，并在后续步骤中按需读取 references 和其他资源。这个“先看标题、后翻正文”的机制，保证了即使技能库里躺着几百个技能，每一轮任务的上下文开销也基本恒定。这也是为什么描述字段写得是否准确，直接决定技能的使用率。描述写得太泛，模型不敢用；写得太窄，模型又不知道什么时候该用。好的描述是“场景 + 用户意图”的组合，比如“用户粘贴了一段报错日志，希望你快速判断故障原因和解决方案”。

理解了最小渲染机制之后，你就不会再抱怨“为什么技能不好用”，而会去反思“我的技能描述是不是写得太像关键词堆砌了”。常见的一个错误是把自己的技能描述写成一堆名词，比如“日志、错误、定位、根因、修复”，模型根本没法判断触发时机。改成一句完整的话，效果立刻不一样。

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

5.1 问题速查表：按症状定位到解法

我整理了一份高频问题速查表，基本覆盖了大家做 Skills 时最常卡住的地方：

这张表不是我一次写成的，而是几个月实际使用中陆陆续续补充的。每次遇到一个新问题，我会在解决后立刻追加到表里，慢慢它就成了团队的“避坑手册”。

5.2 几个细节坑：命名、碎片化与过度自动化

除了上面表格里的常见问题，还有几个不太容易察觉的坑，我得单独拎出来说。

第一个坑是命名不统一。有些人喜欢用中文名、有些人用驼峰、有些人用带空格的长描述。我强烈建议技能目录名统一用小写字母加连字符，例如>