企业官网建设流程全解析

如果有人突然问我“skills 是什么”，放在两年前，我大概率会想到简历上的技能栏。但放在现在，这个词在开发圈里的含义已经完全不同——它代表一种让 AI 助手（也就是 Agent）真正“会干活”的机制：把某一类任务的经验、步骤、规则和工具调用方式打包成一个独立模块，让模型在遇到对应场景时能自动读取并执行。

我花了不少时间研究这种技能包机制，也亲手写过几个能用的包。这篇文章就围绕“Skills”展开，聊聊它到底是什么、内部结构怎么设计、两类常见写法怎么选、开发中容易踩的坑，以及怎么判断一个技能包到底好不好用。适合正在做 Agent 应用、想给 AI 编程助手或自动化流程加“私房经验”的开发者参考，也适合刚接触这个概念、想知道它和插件/提示词有什么区别的新手。

1. “技能包”到底是什么：不是插件，也不是提示词模板

1.1 一个指令让 Agent“会做事”的底层逻辑

先看一个最常见的使用场景。你正在写代码，突然需要把项目里所有 TODO 注释整理成一份带优先级的清单。如果直接用对话式 AI，你得把项目结构、待办分布、整理格式一点点描述清楚，它可能还要反复追问。但如果你的环境里挂了一个名为todo-audit的技能包，你只需要说一句“跑一下技能：整理 TODO 清单”，它就会自己去扫描目录、解析文件、按既定格式输出结果。

这中间的差别在哪？没有技能包时，每一步决策都靠模型临时猜；有技能包时，从“扫描范围”到“输出格式”再到“是否要写回文件”这些决策，全都被预先固化成了可复用的流程。模型不是被“教会”了做这件事，而是被“告知”了做这件事的标准动作。

这正是技能包机制的底层逻辑：它给了 Agent 一套显式的“操作手册”。模型本身仍然靠推理生成内容，但生成什么、按什么顺序做、做到什么程度算完成，这些原本飘忽不定的东西，现在有了白纸黑字的约束。

1.2 与 MCP、插件、提示词模板的边界划分

这个概念刚流行的时候，我一度分不清它和 MCP、插件、提示词模板之间的区别。后来我用一句话给自己理清了：MCP 是给 Agent 装“手”的，技能包是给 Agent 装“脑子里的流程”的，插件是捆绑分发安装包的，提示词模板是给 Agent 讲“话术”的。

MCP（模型上下文协议）解决的是连接问题：让 Agent 能调用外部工具、读取数据库、操作浏览器。技能包解决的是方法论问题：告诉 Agent 这类任务应该按什么步骤做、用什么标准判断。一个技能包内部完全可以要求 Agent 去调用某个 MCP 工具来完成关键动作，两者不冲突，而是协作关系。

插件是更上层的分发单元。一个插件里可以包含好几个技能包、好几个 MCP 服务定义、以及配套的配置文件。技能包更接近“任务流程的最小独立单元”，一个技能只负责一类内聚的任务。

提示词模板则更像“一次性说清楚这件事怎么做”的文字，它没有固定的文件结构，也没法内嵌脚本或引用外部文档。技能包把提示词的松散叙述变成了结构化工程：有元数据、有正文步骤、有依赖资源，甚至可附带可执行脚本。

1.3 技能包解决的核心问题：把经验从人脑搬进 Agent

如果说上面的区分是理论层面的，那技能包真正解决什么实际问题？我觉得核心就一句话：把人类专家头脑中“隐性经验”变成 Agent 可以反复执行的“显性步骤”。

很多任务在人类看来很简单，比如“发个周报”，但把动作拆开就会发现其中的隐性判断不少：哪些事项值得写、风险要不要提、下周计划按什么颗粒度列、语气正式还是轻松。这些判断以前只存在于人的脑子里，聊天式 AI 每次都要重新猜，猜得还不稳定。技能包把这些判断固化成文字、规则、示例和兜底方案，等于给 Agent 装了一个“干过这活的老同事”的备忘录。

这一点在工程实践中价值很大。我见过不少团队用对话式 AI 处理重复性工作，效果总是忽上忽下：同一类任务，换个措辞描述，结果就走样。引入技能包之后，正是因为执行路径被收敛了，波动才明显下降。这部分我会在后面的质量评估章节展开讲具体数据维度。

2. 拆开一个技能包：SKILL.md、依赖文件与目录规范

2.1 最小可用的技能包长什么样

一个技能包本质上就是一个目录，里面最少只有一个SKILL.md文件。这个文件是技能包的心脏，它用 Markdown 格式书写，既给人读，也给 Agent 读。

目录结构大致是这样：

my-skill/ ├── SKILL.md ├── scripts/ # 可选：可执行脚本，Agent 可调用 ├── references/ # 可选：背景资料、模板、示例 └── assets/ # 可选：图片、静态资源

先说SKILL.md。这不是一个随笔写的说明文件，它的开头必须有一段可被结构化解析的元数据（frontmatter），后面才是正文。元数据里最重要的是name和description，前者是技能的唯一标识，后者是触发依据。

如果只有SKILL.md，这个技能包也能工作，但只能覆盖“纯文字指导型”任务。一旦任务需要外部数据、需要执行命令、需要参考特定模板，你就需要在同级目录下放scripts/或references/，并在正文中按需引用。

2.2 SKILL.md 的元数据与正文写法

写SKILL.md最忌讳的是把它当成普通文档，洋洋洒洒写几万字，Agent 反而抓不住重点。我推荐的写法是：元数据负责“被找到”，正文负责“被照做”。

元数据部分，name 一定要短且有区分度，比如code-review、meeting-minutes，不要叫skill1这种。description 是触发关键，要写清楚三个信息：这个技能负责什么任务、在什么时候使用、大概怎么做。有些 Agent 环境靠语义匹配来选技能，description 写得越贴近真实任务的描述方式，触发准确率越高。

正文部分建议遵守“渐进式披露”（progressive disclosure）原则：既然是给语言模型看的，就按“总-分-例”的顺序写。开头用几句话交代任务目标和最终交付物；中间列出步骤，每步写明输入、动作、输出；最后给一个完整范例，让模型对“最终长什么样”有直观参照。

下面是一个 SKILL.md 的骨架示例：

--- name: weekly-report description: 根据本周工作记录生成结构化周报，汇总完成项、风险项与下周计划。当用户要求写周报、汇总本周进展时使用。 ---

然后正文写：

# 周报生成技能 ## 目标 根据本周的工作记录，生成一份适合发给上级的周报，包含完成项、风险项和下周计划三大部分。 ## 执行步骤 1. 收集素材：读取本周工作记录，如果没有现成记录，则主动向用户提问获取关键事项。 2. 分类整理：把素材分配到“已完成”“进行中”“风险与阻塞”“下周计划”四个类别。 3. 判断语气：默认使用简洁、客观的书面语气，不用口语和夸张形容词。 4. 输出格式：按用户指定的模板输出，若用户未指定，使用 references/weekly-template.md。 ## 注意事项 - 风险项必须如实列出，不允许为了美化报告而省略阻塞问题。 - 已完成事项按优先级排序，每项控制在 50 字以内。

2.3 依赖文件的设计：references 和 scripts 的合理使用

references/目录适合放模板、样例、知识背景等静态资源。我自己的使用习惯是：凡是不希望每次对话都让模型重新“发明”一遍的内容，比如公司周报模板、代码规范片段、论文结构模板，都放这里。正文里用相对路径引用，模型需要时自然会去读取。

scripts/目录则适合放可执行脚本。这里要特别提醒：脚本默认不会主动运行，Agent 需要通过工具调用才能执行。因此脚本本身必须写得健壮，输入输出要清晰，最好是命令行兼容的。比如一个统计代码行数的脚本，就应该是line-counter <目录路径>这种能独立运行的形式，而不是一段需要解释器交互的代码片段。

2.4 一个“周报生成”技能的完整配置示例

我把上面例子补全，展示一个带参考模板的完整技能包应该是什么样：

weekly-report/ ├── SKILL.md └── references/ └── weekly-template.md

weekly-template.md内容大致是：

# {日期} 周报 ## 本周完成 - 事项1（一句话描述） - 事项2（一句话描述） ## 风险与阻塞 - 风险描述 / 影响范围 / 建议处理方式 ## 下周计划 - 计划项1（预计投入时间） - 计划项2（预计投入时间）

这种设计的好处是：模板和流程分离。以后模板要改，只动 references 目录，不需要重写 SKILL.md；反过来，流程要调整，也只动正文，模板不用碰。对 Agent 来说，读取SKILL.md是轻量操作，只有真正需要时才去加载 references 里的内容，不会“一口气全读进来”导致上下文被无关信息灌满。

3. 两类技能包的实战写法：文档驱动与代码驱动

3.1 纯 Markdown 文档型：适用于规则清晰、判断简单的任务

纯文档型技能包里只有 SKILL.md 和少量参考文档，没有可执行程序。它适合的任务有共同特征：核心动作是“分析、归纳、改写、判断”，不需要访问外部系统，也不需要做批量计算。

举个例子，一个“代码提交信息规范”技能。它要做的事情是：读取 git diff，按 Conventional Commits 规范生成提交信息。这个任务本身不需要脚本——读取 diff 是 Agent 的工具能力，规范判断靠的是文字约束。我把提交信息的类型列表、作用范围、写法示例全写进 SKILL.md，模型看到后就能直接配。

这种技能包的好处是零环境依赖、跨平台可迁移、调试成本低。写起来也快，最多半小时就能出一个能用的版本。缺点是上限有限：凡是需要精确计算、文件批量操作、复杂状态管理的任务，纯文档就不够力了。

3.2 脚本调用型：把本地命令变成 Agent 的双手

当任务从“怎么想”变成“怎么做”的时候，就该上脚本了。脚本调用型技能包的核心设计思路是：Agent 负责理解任务和编排，脚本负责执行确定性的操作。

举一个实际写过的例子。我给一个模拟项目做过“依赖安全检查”技能包。SKILL.md 里写了触发条件和使用时机，然后列出的执行步骤是：

1. 读取项目根目录下的依赖清单文件。
2. 运行scripts/dep-audit.py --path .扫描依赖版本。
3. 解析脚本输出的 JSON 结果。
4. 按 SKILL.md 中的分级规则生成安全报告。

这里脚本只负责“计算”和“取证”，生成报告、决定建议这些需要语言能力的部分留给模型。分界的原则就一句话：凡是可以被确定性验证的事交给脚本，凡是需要理解与表达的事交给模型。

#!/usr/bin/env python3 # scripts/dep-audit.py import json, sys, re def main(path: str): # 模拟扫描逻辑：读取依赖清单，比对已知的不安全版本范围 findings = [] with open(f"{path}/requirements.txt") as f: for line in f: pkg, ver = line.strip().split("==") if re.match(r"^1\.0\.\d+$", ver.strip()): findings.append({"package": pkg, "version": ver.strip(), "risk": "high"}) print(json.dumps(findings)) if __name__ == "__main__": main(sys.argv[1])

3.3 从零搭建“代码评审”技能的完整步骤

下面演示一个相对完整的开发流程，目标技能是“代码评审”，这个例子覆盖了 SKILL.md、references、scripts 三类要素的使用。

第一步，明确任务边界。我想让 Agent 在收到“帮我 review 这段代码 / 评审这个 merge request”时，主动读取 diff，按设计、可读性、性能、安全性四个维度输出评审意见，并给出严重程度分级。

第二步，写 SKILL.md。正面说清楚四维度的评审标准；反面说清楚不做什么，比如不直接修改代码、不做无根据的风格挑剔。脚注里放一个“严重程度分级表”的引用路径，让模型在遇到判断困难时去查。

第三步，准备 references/review-guidelines.md。这里面是分级标准和“什么是严重问题，什么是小问题”的对照表，比如：引入未捕获异常属于严重问题；变量命名不清晰属于轻微问题。

第四步，添加辅助脚本。虽然代码评审主要靠模型语言能力，但我加了一个scripts/count_changes.py，用来统计 diff 的行数、文件数、修改类型分布，给评审提供量化背景，避免模型只盯着一个文件看而忽略了整体变更规模。

第五步，本地测试。我用一份虚构的模拟代码跑这个技能，看输出的评审意见是否覆盖了四个维度、分级是否合理。第一次测试发现模型倾向于只关注性能而漏掉安全问题，我就把 SKILL.md 里“安全优先于性能”这句话提到了执行步骤的前面。

3.4 混合型技能的设计思路与取舍

混合型是最常见的情况：任务既有判断分析，又有确定性操作。我的设计经验是先把整个任务沿着“输入 → 处理 → 输出”拆成一条流水线，然后在每个环节打标签：这一步是“模型理解”还是“脚本执行”。凡是标了“脚本执行”，就去写脚本；标了“模型理解”，就在 SKILL.md 里给足指导。

这里有一个常被忽略的取舍点：脚本写得太“重”会让技能失去通用性，写得太“轻”又可能让模型乱发挥。我通常用“中间表达”来缓冲，也就是让脚本输出标准化 JSON，模型再基于 JSON 做判断。这样一来，脚本只保证“事实正确”，模型负责“判断合理”，两者解耦，技能包也好维护。

4. 技能包开发踩坑实录：从“能跑”到“好用”的九条经验

4.1 症状一：Agent 读懂了技能，却执行得不到位

最典型的翻车现场是这样的：你把 SKILL.md 写得清清楚楚，步骤也列了，模型复述起来头头是道，但真执行的时候，要么漏了中间步骤，要么输出格式和示例对不上。

我排查下来，最常见的原因有两个。一是步骤写得太“原则化”。比如“分析用户需求”这种话，模型无法判断做到什么程度算分析完成。解决办法是把步骤改成可验证的动作：谁的输入、做什么操作、产出什么结果。二是示例和指令不一致。模型会优先模仿示例，如果你在“注意事项”里说“语气简洁”，但示例里写了很长的描述性句子，模型会照着示例来。解决方法是让示例严格匹配规范，甚至刻意造一个“完全符合规范”的反面样例来对比。

4.2 症状二：技能太多，Agent 反而选错工具

技能包数量超过一定规模后，会出现一个哭笑不得的问题：Agent 在多个相似技能之间挑错。比如你同时有weekly-report和daily-report两个技能，description 如果写得太像，模型可能在用户要每日站会摘要时调用周报技能。

解决办法是给 description 写清楚“适用范围边界”。我习惯加上“不用于……”的反向描述。比如：daily-report 用于每日站会摘编，不用于周报、月报，也不用于项目总结。这能大幅提高命中率。另一个办法是合并相似技能，把日会/周会/月会合成一个meeting-report技能，内部用参数区分场景，减少 Agent 的选择压力。

4.3 症状三：脚本在终端能跑，在 Agent 环境里却报错

这是脚本调用型技能最常遇到的坑。明明脚本在终端跑得好好的，进了 Agent 环境就是各种路径找不到、权限不够、环境变量缺失。

这里要理解 Agent 执行脚本的环境和普通终端不完全一样，工作目录可能不固定，环境变量也可能是精简过的。我的经验是：脚本里不要依赖相对路径，入口参数必须显式传绝对路径；依赖的外部命令要先探测存在性，缺失时给出友好提示；输出统一走 stdout，不要往临时文件里写中间结果，因为 Agent 不一定能拿到那个文件。还有一点，处理完要记得清理临时文件，不然会污染后续执行环境。

4.4 定位技能问题的最小复现法

技能包调试比普通代码调试麻烦，因为同样的输入，模型输出可能每次都不一样。我的调试方法是“最小复现法”：先构造一个最简单的输入，能触发错误即可；然后固定一种模型参数（比如低随机性），一步步手动“扮演 Agent”执行技能包里的步骤，看卡在哪一步。

这个过程中最有价值的工具其实是“让 Agent 自言自语”。我会在 SKILL.md 里临时加一条调试指令：“执行每一步前，先用一句话输出你正在执行的步骤和依据”。这样模型会把自己的推理过程暴露出来，问题出在指令歧义还是资源缺失，一目了然。排查完再把这条调试指令删掉，避免污染正式版本。

4.5 安全边界：哪些操作不该放进技能包

技能包赋予 Agent 更强的执行力，这也意味着风险更高。我自己定的安全红线有三条。第一，默认不允许技能包内的脚本执行删除、格式化、全局覆盖等破坏性操作；如果确实需要，必须在 SKILL.md 里显式声明，并加一个二次确认步骤，让 Agent 操作前先向用户复述将要执行的动作。第二，不把密钥和敏感配置写进技能包目录，脚本需要读取环境变量里的凭据，而不是硬编码。第三，技能包内的脚本要对输入做校验，特别要防路径穿越——Agent 有可能传入意想不到的路径参数，脚本要做好白名单限制。

5. 如何评估一个技能包的质量：三个维度与迭代闭环

5.1 维度一：成功率、稳定性、可干预度

判断技能包好不好用，不能只看“这次结果还不错”。我习惯用三个维度评估。

成功率：同一组测试用例跑多次，输出结果达到“合格线”的比例。这里的合格线要提前定好，比如周报技能的成功条件就是三个板块齐全、无遗漏风险项、格式符合模板。

稳定性：同一输入在多次执行中，结果风格和结构差异多大。语言模型的随机性会导致输出漂移，技能包的价值就是压制这种漂移。我用“结构重合度”来衡量：两次输出框架是否一致、章节是否对齐、语气是否接近。

可干预度：用户能不能低成本地纠正方向。好的技能包应该允许用户中途打断并调整参数，而不是一条道走到黑。衡量方式是看“用户提出修改后，Agent 能否正确调整而不重复劳动”。

5.2 用失败用例反向驱动技能描述重写

技能包最大的成长动力，其实是不好用的用例。每次出现失败，别急着骂模型，先把失败样本收集起来，倒推是哪一段指令造成的。

我举个例子。有一次我写的代码评审技能，对一段有明显安全漏洞的代码没有任何提示，反而大篇幅挑格式问题。我把失败样本拿回来重看，发现 SKILL.md 里“安全性”虽然排在第一位，但后面用了太多篇幅写可读性细节。模型被大量细节带偏了注意力。我把评审顺序改成强制编号步骤：先检查安全问题并明确输出“S级问题”，未发现安全问题时才能进入下一维度。改完之后，同类失败样本的复现率明显下降。

5.3 技能包的版本管理与团队共享

技能包也是代码，需要版本管理。我和团队协作时的习惯是给目录打上语义化版本号，比如weekly-report-v2.1.0，或者用 Git 仓库管理每个技能包的变更历史。每次修改都必须记录改动原因，否则一个月后你会发现自己都不知道某个步骤为什么存在。

共享时最需要注意的是“环境适配”。别人拉走你的技能包，跑不起来十有八九不是脚本逻辑问题，而是依赖没装全、路径结构不一致。我会在技能包根目录放一个README.md，写清楚运行环境、依赖项、首次使用前的初始化命令。这个文件放在技能包目录里，既不会干扰 Agent 执行流程，又能让人类同事快速上手。

最后再分享一点我自己的体会。写技能包写得多了就会发现，最难的不是写格式，而是把自己脑子里那些“不用想就知道”的判断标准，一句句翻译成 Agent 能照着执行的显性指令。这个过程本身，其实比技能包本身还值得。每次遇到任务波动，你要想的不只是“让 AI 再聪明点”，而是“我到底有没有把这件事的做法说清楚”。反过来，这也是磨练自己梳理方法论的好机会。