最近圈子里到处都在聊 Vibe Coding，这个词从年初的玩笑梗，现在已经慢慢变成一种正经的开发方法论。但聊到深处，你会发现一个更值得关注的变化：以前大家说的 Vibe Coding 是“跟着感觉写代码”，重点是 AI 一次性能写出多少能跑的代码；现在的重心已经转移到“怎么把感觉沉淀成可复用的东西”——这就是 Agent Skills 正在做的事情，也是标题里说的“skills.sh 时代”背后的真实含义。

我自己这段时间一直在把日常开发里的重复任务拆成技能包，配合现有 AI 编程工具一起用。体感非常明显：以前是每次都要把上下文重新交代一遍，让模型重新理解我的项目、我的规范、我的偏好；现在只需要把它挂进 Agent 的技能目录，整个工作流的顺手程度完全不一样。这篇文章我想从一个开发者的实际视角，拆一拆 Vercel 为什么会在现在这个节点全力押注 Agent Skills，以及这套“技能包化”的工作流到底怎么落地，适合所有已经在用 AI 辅助写代码、又觉得当前方式还不够系统的开发者参考。

1. Vibe Coding 正在经历的三个阶段：从“聊天生成”到“技能沉淀”

1.1 第一阶段：对话式生成，爽但不可积累

Vibe Coding 最早的形态很简单：打开一个 AI 编程助手，把需求用自然语言描述一遍，模型直接吐代码，你复制粘贴，跑通了就完事。这种模式的好处是门槛极低，哪怕没怎么写过某类脚手架代码，也能在几分钟内拿到一个能跑的雏形。

但问题是，这种使用方式几乎没有积累效应。我见过不少开发者一个月后在同一个项目里，还是会对着 AI 重复输入“帮我把这个列表改成虚拟滚动”“不要用 any”“错误处理要统一格式”之类的指令。因为每次对话都是一次性的，模型的记忆只存在于这次会话的上下文窗口里。关了窗口，一切归零。

更麻烦的是，你的项目规范、代码风格、常用技术栈偏好，这些“隐性知识”完全没办法固化下来。同一个开发者，上一周和下一周让 AI 写的代码，风格可以完全不一致。这在单打独斗时还只是有点别扭，一旦放到团队协作里，代码库很快就会被 AI 生成的各种“异形代码”污染。

1.2 第二阶段：上下文工程，能复用但很脆弱

为了解决“记忆归零”的问题，大家开始做上下文工程。具体做法包括：写 CLAUDE.md 之类的项目说明文件、维护一个 docs/ 目录放技术决策记录、把常用指令做成系统提示词模板。我自己也干过这事，把团队代码规范塞进一个超长的规则文件里，让 AI 工具每次自动加载。

这套方案的优点是立竿见影，AI 生成的代码确实更贴项目风格了。但它的脆弱性也很明显：规则文件越长，模型就越容易在长上下文里“迷失重点”，前端一点的约束会被后面的内容稀释。而且，这类上下文文件是“被动加载”的，模型只有在读文件时才会遵守，一旦某个 Agent 没有按预期加载，整套规则就形同虚设。

更关键的问题是，它不是“可执行”的。你可以在文档里写“项目使用 pnpm 作为包管理器”，但 AI 并不会真的去帮你初始化 pnpm workspace；你可以写“提交信息遵循 Conventional Commits”，但 Agent 不会真的去校验 commit message。文档能约束生成，却不能驱动工具链。

1.3 第三阶段：Agent Skills，把“技能”变成可安装、可执行、可共享的单元

到了第三个阶段，思路发生了变化：不再是给 AI 写一堆“建议”，而是给 Agent 准备一套“能力包”或者叫“技能包”。每一个技能包都是一个自包含的目录，里面有描述文件、有指令说明、有示例、甚至还有配套的脚本和资源。Agent 在接到任务时，会根据任务描述去匹配并加载对应的技能包，然后按照技能包里的方法论来执行。

打个比方，传统 Prompt 是在教一个实习生“怎么做事”，上下文工程是在给他一本“员工手册”，而 Agent Skills 相当于直接给这个实习生一套“标准化作业工具箱”——里面既有说明书，也有专用扳手，他该用哪个工具、按什么流程操作、输出什么结果，都有明确指引，而你只需要告诉他“今天修这个机器”。

这就是标题里“skills.sh 时代”的实质：技能不再藏在对话里，而是像软件包一样被结构化、版本化、分发化。未来的开发者共享的不再是“一段提示词”，而是一整套可复用的工作技能。

2. Agent Skills 的结构拆解：一个技能包内部到底有什么

2.1 最小可用技能包的目录结构

我拆解过几个公开的技能包范例，也自己搭过不少，一个标准技能包通常长这样：

my-skill/ ├── SKILL.md # 技能说明，Agent 首先读取的文件 ├── scripts/ # 可执行脚本，比如解析日志、批量重命名 │ └── audit.js ├── assets/ # 参考资源，比如示例代码、模板文件 │ └── template.tsx ├── references/ # 深度文档，按需加载的补充说明 │ └── api-notes.md └── .skills-version # 可选的版本标记

这个结构的设计逻辑非常清楚：SKILL.md 是入口，相当于技能包的门面，Agent 搜索技能时首先读到它的内容，然后决定“这个技能是否适合当前任务”；scripts 是技能的执行层，把可自动化的事情真正跑起来；assets 和 references 则是按需加载的知识库，避免一次性把所有内容塞进上下文。

为什么这么设计？核心是控制上下文成本。如果一个技能包把几十个文档全部一次性加载，Agent 的上下文窗口很快就会被塞满，反而影响判断。通过 SKILL.md 做摘要、按需加载 references，Agent 可以像人类查手册一样，先看目录，再翻到需要的章节。

2.2 SKILL.md 的写法决定了技能包好不好用

SKILL.md 的写法直接影响 Agent 会不会在正确的时候选用这个技能。根据我的实测经验，一份能用的 SKILL.md 至少要包含以下几点：

• 一个精准的 name 字段，让 Agent 能快速识别技能归属
• 一段描述（description），说清楚“这个技能解决什么问题，在什么场景下使用”
• 一段清晰的指令（instructions），告诉 Agent 使用该技能时应该遵循的步骤和输出格式
• 若干示例（examples），展示输入输出对照，模板化越强越好
• 明确的边界（limitations/avoid），告诉 Agent 什么时候不该用这个技能，节省无效调用

描述字段特别容易被人忽视，但它其实是技能包“被发现”的关键。Agent 选择技能的过程，本质上是一个基于任务描述和技能描述之间的语义匹配过程。如果你的 description 写得含糊，比如只写“代码相关”，那 Agent 很可能在不需要的时候误加载，或者在该用的时候压根没想起来。

2.3 与普通 Prompt / MCP / 插件到底有什么区别

很多朋友会问：Agent Skills 跟自定义 Prompt 有什么区别？跟 MCP Server 又有什么区别？我用一个表格说明：

我的理解是：Prompt 是你对 AI 说的一句话，MCP 是你给 AI 接的一个外部工具接口，Agent Skills 则是你给 AI 装的一个“专业技能模块”——它既能像 Prompt 一样传递指令和知识，又能像插件一样触发脚本执行，同时还能像软件包一样被分发和版本管理。

3. Vercel 的布局逻辑：为什么是 Vercel，为什么是现在

3.1 Vercel 的核心资产：从部署平台到 AI 应用入口

要理解 Vercel 为什么会成为“skills.sh 时代”的代表玩家，得先看它手上握着什么牌。

第一张牌是 v0。如果你用过 Vercel 的 v0，应该能感受到它已经不只是“聊天生成 UI”的工具，而是逐渐变成“生成完整前端工程”的入口。用户输入一句话，它返回的不仅是一段 JSX，而是一个包含组件、路由、依赖关系的完整项目骨架。这套逻辑天然需要“技能化”来支撑：用户描述“我要一个博客后台”，Agent 其实是在内部调用了若干个针对 Next.js 项目初始化的技能包。

第二张牌是 AI SDK。这是 Vercel 在底层做的一个非常关键的抽象层，它让开发者可以一套 API 对接多家的模型服务。Agent Skills 一旦要大规模落地，必须依赖这套抽象，否则技能包里的脚本、工具调用逻辑就会被特定模型厂商绑定。

第三张牌是部署平台本身。Vercel 天然具备将“技能包”转化成“可部署应用”的能力。你可以把一个技能包推到平台上，实例化成一个个可访问的服务端点，团队之间分享技能就像现在分享一个部署链接一样简单。

3.2 闭环设计：技能包的创建、执行、分发三位一体

Vercel 真正有意思的地方在于，它把 Agent Skills 的整个生命周期都串起来了。

创建阶段，通过 v0 的可视化交互，开发者可以用对话的方式一步步生成一个技能包，不需要手搓目录；执行阶段，通过 AI SDK 和 Serverless Functions，技能包里的脚本可以直接跑在云端，不必依赖本地环境；分发阶段，技能包可以作为独立项目部署、分享、甚至后续演变成一个公开的技能市场。

这个闭环很关键。以前做 AI 应用，大家各自为政，Prompt 藏在某个配置文件里，工具调用散落在不同函数中。现在 Vercel 想做的事，是把这些碎片化能力全部纳入一套可复用的标准体系里。本质上它不是在做一个“AI 编程功能”，而是在制定一套“AI 工作流的分发协议”。

我个人的判断是：Vercel 并不打算把 Agent Skills 变成自己的独有功能，而是想成为这套标准的定义者。当越来越多的开发者用 Vercel 的 AI SDK 构建技能、部署技能、分发技能，Vercel 就会成为这个生态的默认基础设施。

3.3 对普通开发者的直接影响：工作流从“文件导向”转向“技能导向”

传统开发工作流是文件导向的：你关注有哪些目录、哪些文件、哪些函数，思考的是“代码放在哪里”。Agent Skills 时代的工作流开始变成技能导向的：你关注“我们团队有哪些技能包、每个技能包解决什么问题、新任务应该委派给哪个技能”，思考的是“能力如何编排”。

举个例子。以前做前端重构，我的工作流是：打开项目，找到相关组件，分析状态管理，然后逐个改。现在这套流程可以被固化为一个“前端重构技能包”：Agent 先加载技能说明，了解重构流程分为“依赖审计、类型收敛、状态提取、验证运行”四步；然后它自动执行 scripts 里的审计脚本；再根据 references 里的项目规范调整代码。整个流程不再依赖开发者临时抱佛脚地看文档、回忆上次怎么做的。

这种“技能导向”的工作流，对团队特别有价值。新成员入组，不需要被反复科普“我们项目有哪些约定、通常怎么改代码”，直接让他加载团队的技能包库即可。代码审查、环境初始化、依赖升级、错误排查，这些都是高度重复、又高度依赖上下文的任务，天然适合做成技能包。

4. 动手实战：手把手做一个自己的 Agent Skills 技能包

4.1 先定场景：把“重复提问最多的任务”做成第一个技能包

很多人第一次动手做技能包时容易犯一个错误：想一口气把所有工作流都固化下来。我的建议是，先选一个你最烦、AI 最容易答偏的任务下手。

以我自己为例，我团队里经常有人问我“怎么给这个项目加一个新的 API 路由”。这个问题看似简单，但牵扯到项目里的鉴权方式、请求封装、错误处理规范、测试写法，AI 如果只靠上下文猜测，生成出来的代码十有八九不符合团队约定。

于是我把“新增 API 路由”做成第一个技能包，目录如下：

add-api-route-skill/ ├── SKILL.md ├── scripts/ │ ├── scan-existing-routes.sh │ └── validate-route.js ├── assets/ │ └── route-template.ts └── references/ ├── auth-conventions.md └── error-handling.md

这个技能包的核心思路是：让 Agent 先运行脚本扫描项目现有的路由结构，再加载路由模板和规范文档，最后按照模板生成新的路由代码。这样无论项目文件结构多复杂，Agent 都能先拿到事实数据，而不是靠猜。

4.2 实战编写 SKILL.md 的关键细节

我写 SKILL.md 踩过不少坑，最有价值的几条经验是：

第一，description 要写成“触发条件”，而不是泛泛的功能介绍。比如我写的是“当用户要求新增、修改或删除 API 路由时使用；尤其适用于项目已有统一鉴权和错误处理约定的场景”。Agent 看到这个描述，就能明确判断什么时候该加载这个技能包。

第二，instructions 要写“步骤顺序”，而不是“结果要求”。不要让 Agent 自己去发挥，要明确告诉它：先运行 scan-existing-routes.sh 获取现有路由清单；再阅读 auth-conventions.md；最后按 route-template.ts 生成代码。步骤越具体，输出越稳定。

第三，示例要覆盖边界情况。我在 SKILL.md 里放了一个“已验证的示例输出”，同时特意写了一段“禁止事项”：不要在未运行扫描脚本时凭空猜测现有路由数量；不要移除已有鉴权装饰器；不要使用非项目约定的错误包装类。这些“边界说明”对控制 AI 的行为非常有效。

4.3 把技能包接入日常开发工作流

技能包写好后，接入方式通常有两种：一种是放进本地 Agent 的 skills 目录，让它在合适的时候自动加载；另一种是作为独立项目部署，通过 API 方式供团队其他工具调用。

本地接入适合个人开发者：你只需要把技能包路径配置进工具的设置里，日常写代码时 Agent 会自动匹配。云端部署适合团队：把技能包挂在服务端，配合 Serverless Function，团队的每个人都能通过统一的入口调用，而且可以在后端统一控制版本、做升级回滚。

我自己的习惯是双轨并行：本地放一份原始技能包作为开发调试环境，等稳定了再推一个版本到云端给团队使用。这样既能快速迭代技能包内容，又能保证线上环境的稳定性。

4.4 技能包质量自查清单

经过几轮的实践，我总结了一张自查清单，写技能包时逐条过一遍，能显著提高命中率：

• SKILL.md 的 description 是否能在 50 字内说清“何时使用”
• instructions 是否按顺序排列，Agent 是否可以不假思索地执行
• 示例是否包含“输入→处理→输出”完整链路
• 是否明确写出了“禁止做什么”
• 脚本是否存在边界校验，而不是盲目跑通
• references 文档是否精简，避免把无关背景全部塞进去
• 技能包是否做了版本标记，能否回滚到上一版本

这张清单不一定适用于所有场景，但作为一个通用起点非常有用。尤其是“明确禁止事项”这一点，我在实际使用中发现它比“鼓励事项”更能约束 AI 的行为底限。

5. 实战踩坑记录：这些坑比文档更值得看

5.1 技能包粒度不对：太肥导致失焦，太瘦导致没用

技能包的粒度很难一次拿准。我一开始做过一个“前端开发全流程”的技能包，想着把它做成包罗万象的大全。结果 Agent 每次加载这个技能包时，要消耗极多的上下文，而且因为内容太杂，常常在“要不要处理样式”和“要不要写测试”之间摇摆，输出质量反而不如不加载。

后来我把它拆成了五个子技能：初始化新组件、接入 API 层、编写单元测试、提交前检查、修复样式问题。每个子技能都非常聚焦，Agent 的选择准确率明显上升。我的经验是：一个技能包应该对应一个“可以在 10 分钟内由人完成并且有明确产出”的任务，而不是对应一个大领域。

5.2 description 写得不好，Agent 要么不加载，要么乱加载

这是最隐蔽的一个问题。技能的 description 写得含糊，Agent 就容易出现两种情况：一是任务跟技能高度相关但 Agent 没识别到，导致技能完全没被加载；二是任务跟技能只有一点点沾边，Agent 就强行加载，浪费上下文还影响执行路径。

解决办法是给 description 加“正例”和“反例”。我通常在 description 末尾补一句“注意：本技能适用于 X 场景，不适用于 Y 场景”。这样 Agent 在语义匹配时既能命中，又能排除错误场景。如果你发现 Agent 频繁误加载某个技能包，大概率是 description 没有写清楚边界。

5.3 上下文污染：技能参考资料不能“越多越好”

技能包里的 references 是双刃剑。参考文档越全，指导意见越丰富，但同时也会持续占用上下文窗口。我踩过一个教训：把项目的完整技术规范文档全部塞进 references，结果 Agent 处理任务时，到达实际代码逻辑时上下文已经快满了，生成的代码反而开始出现一些低级错误。

后来我明确了原则：references 里的文档必须“精简到 Agent 判断所需的最小集合”；详细内容可以放到按需加载里，但一定要保持短小聚焦。比如 500 行的背景说明压缩成 20 行的要点清单，保留核心规定，删掉历史原因和备选方案讨论。这种“有损压缩”是值得的，因为 Agent 毕竟不是人，它不需要理解“为什么有这个规范”，只需要知道“按什么规范执行”。

5.4 版本漂移：技能包更新后，旧会话还在用旧逻辑

在实际使用中，我经常更新技能包模板，但发现某些 Agent 会话里输出的代码还是旧版本风格。排查下来，原因是 Agent 在会话开始时已经加载了技能包内容，后续技能包文件更新并不会同步到这个会话中。

这个问题的解决思路是：重要的技能包更新，必须连带一个新的版本号；如果技能包逻辑跟项目生成结果强相关，需要提示 Agent“先检查技能包版本是否最新”。此外，在技能包更新频率较高的阶段，建议每个任务都开新会话，不要复用旧的 Agent 会话。这条经验对依赖长会话做事的人尤为重要。

为了帮你更直观地排查问题，我整理了一个常见故障速查表：

5.5 与团队协作时，必须把技能包当成“代码”来管理

技能包不是写一次就完事的，它会随着团队规范变化而演进。我们团队后期把它当成正式代码来管理：每个技能包都独立在仓库里，有提交历史、有 PR 评审、有问题单。刚开始有人觉得这样做太重，但几次“技能包更新导致团队生成代码风格不一致”的事件之后，大家就意识到，技能包对产出的影响比例几乎是 100%，远比一般代码模块的影响面更大。它值得用最严格的方式去管理。

6. 这份变革对开发者角色的真实影响：有人在担心，有人在行动

6.1 技能工程师：一个正在成形的新角色

Agent Skills 的普及，带来一个很有意思的变化：开发者的核心竞争力，正在从“能写多少代码”转向“能不能把工作方法封装成技能包”。

传统开发者维护的是代码资产，未来的开发者需要维护的是“方法资产”。同样是完成一次 API 集成，以前比的是谁熟悉框架 API、谁能写得更快；现在比的可能是谁能把整个集成过程沉淀成一个标准化的技能包，让团队所有 Agent 都能按这个标准自动执行。

我把这种能力称为“技能工程化”。它要求你具备双重的抽象能力：既要懂业务任务的深层逻辑，又要懂 Agent 的能力边界和行为习惯。这种人短期内很难被替代，因为“拆解任务→定义流程→设计校验→封装分发”，这些环节需要真刀真枪踩过坑才做得好。

6.2 技能市场：下一个 NPM 级别的想象空间

当技能包的创建、使用、分发形成闭环，一个更庞大的图景就出来了：技能包市场。它像 NPM 之于 JavaScript，像 GitHub Actions 之于自动化——开发者不再需要从零开始构建所有技能，而是可以直接安装别人验证过的成熟技能包。

这个市场一旦成熟，会彻底改变软件分发的形态。以前你买一个软件产品，买到的是成品；未来你订阅一个技能包，相当于买到的是“方法论+工具链+最佳实践”的组合。Vercel 这类平台如果能把技能包市场的基础设施做起来，意义不亚于当年包管理器对前端生态的贡献。

这种变化对个人开发者尤其友好。以前做一个工具产品，要应付部署、运维、分发平台；现在做一个技能包，本质上是在交付一套“即插即用的 AI 执行能力”。门槛更低，触达范围反而更广。

6.3 保持清醒：Agent Skills 还不完美，别神化它

当然，我并不是想把这个方向吹得天花乱坠。实际用下来，Agent Skills 的成熟度还处于早期阶段。最明显的局限有三个：一是技能包的描述和指令仍然依赖自然语言，不同模型对同一份技能包的理解和执行质量差异很大；二是技能包内部逻辑不支持真正意义上的条件跳转和复杂分支，目前多数还是线性推进；三是技能包的可观测性不足，当 Agent 执行技能包时，里面具体怎么做、每一步耗了多少上下文，开发者的能见度还很差。

所以我不建议你把现有的工程体系一夜之间全部迁到技能包上。作为一个阶段性策略，比较务实的做法是：先挑两三个高重复、低复杂度、结果可验证的任务做试点；跑通之后再逐步扩展。技能包是给工作流提效的，不是给自己制造新问题的。

我在实际使用中还有一个很深的体会：技能包最大的价值不是让 AI 写得更好，而是逼着你自己把工作流程想得更清楚。你会发现，很多你以为“已经很熟”的任务，一旦要写进技能包、让另一个智能体也能按步骤执行，里面的模糊地带和隐性假设立刻就会暴露出来。所以哪怕你暂时不打算大规模使用 Agent Skills，也建议试着把手上最常做的一件事写成技能包，这个梳理过程本身，就值回票价。