企业官网建设流程全解析

Serverless Framework Agent Skills 深度指南:安装、自动更新与定制 AI 智能体技能包

【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless

Serverless Framework 内置了面向 AI 编码智能体(Claude Code、Codex、Cursor 等)的Agent Skills机制:把描述"如何正确操作你的 serverless 服务"的指令文件,一键安装到项目中约定的技能目录,并通过版本化同步在团队间持续保持一致。读完本篇,你将掌握serverless agent skills install的完整用法与参数、技能目录的检测与选择逻辑、自动更新的触发与边界条件、以及如何"接管"某个技能使其脱离框架管理,并能对照源码理解这套同步引擎的"只前进、不删除、不覆盖已接管技能"三大不变量。

Agent Skills 是什么

Agent Skills 是一组指令文件(遵循 agentskills.io 开放的 Agent Skills 标准:一个目录对应一个技能,内含SKILL.md及可选的辅助文件,如references/目录)。它们的作用不是运行代码,而是"教会"支持该标准的 AI 编码智能体如何工作——例如如何编写符合框架规范的serverless.yml、如何部署 MCP 服务器、如何调试沙箱环境。

仓库中实际内置了哪些技能,可以直接查看 skills/manifest.json:当前清单包含serverless-mcp与serverless-sandboxes两个技能,各自记录了内容版本(version)与内容哈希。每个技能的实际指令内容位于如 skills/serverless-mcp/SKILL.md 这样的一级目录下,frontmatter 中带有managed-by: serverless-framework与version等元数据,这些字段正是后续安装与自动更新逻辑的判断依据。

需要注意:内置技能集合随 CLI 版本变化。如果你的 CLI 版本尚未捆绑任何技能,执行serverless agent skills install会报告No skills are bundled with this CLI version.且不做任何安装;本文其余内容在升级到捆绑了技能的版本后适用。

安装技能:命令与目录检测

在你的服务目录(即serverless.yml所在目录)执行:

serverless agent skills install

技能会被写入以下两类目标目录:

命令会写到哪里:五级检测阶梯

默认不指定参数时,命令会检测你或团队已经在使用哪些智能体目录——同时检查服务目录内(如项目里已有.claude/、.agents/)和当前用户的 home 目录,只写入有"信号"的目录;完全无信号时才创建两个目录。

从源码 resolve-targets.js 可以看到,这套检测是一条按优先级从高到低的阶梯:

1. 显式--dir参数(仅 install 模式):按参数原样写入,目录不存在则创建,并对非法值报错(合法值仅claude、agents);
2. 已存在 Framework 托管的技能:收敛到"我们的技能已经在哪里"的目录——这正是自动更新模式依赖的"opt-in 门槛";
3. 服务级智能体目录:服务目录中检测到.claude/或.agents/即视为团队偏好;
4. home 目录检测:检查~/.claude、~/.agents、~/.codex、~/.cursor等标记目录。值得注意的是源码中的映射:检测到~/.codex或~/.cursor也归入agents目标,因为这两个应用读取的是.agents/skills/标准目录;
5. 兜底:以上都无信号时,两个目录都创建。

用--dir显式指定目标

serverless agent skills install --dir claude serverless agent skills install --dir agents serverless agent skills install --dir claude --dir agents

--dir可以重复使用,也接受逗号分隔列表,即等价于:

serverless agent skills install --dir claude,agents

完整的命令行参考(含更多示例)见 agent-skills-install 命令文档。

建议提交到版本库

官方建议将安装后的技能提交到版本控制,让整个团队的智能体(以及新加入的同事)都能直接受益。因为技能内容本身是纯文本指令文件,且受框架版本化管理,提交后与代码一起 review、随 PR 演进是最稳妥的协作方式。

内置技能如何打包:frontmatter 契约与清单

理解安装机制前,先看框架如何"认识"一个技能。仓库对内置技能执行 CI 强制的 frontmatter 契约(见 skills/README.md):

--- name: <必须与目录名一致> description: <非空,≤1024 字符> metadata: managed-by: serverless-framework # 必填——更新/所有权标记 version: "1" # 整数字符串;每次内容变更都必须递增 author: Serverless Inc. # 可选 ---

规则要点:

• 每次技能内容变更,必须递增metadata.version,然后运行node packages/sf-core/scripts/lint-skills.js --update并同步提交 skills/manifest.json,否则 CI 失败;
• 辅助文件(aux files)永远不会从用户安装中被删除——新增或重命名文件,而不是复用旧文件名。

运行时,解析逻辑位于 read-skills.js:它用 YAML 的JSON_SCHEMA解析 frontmatter,源码注释说明这是有意为之——已安装的SKILL.md属于不受信任输入(克隆下来的仓库可能含有任意技能),因此只允许解析纯数据,禁止自定义/带类型的 YAML 标签。严格模式下还会校验name与目录名一致、description非空、managed-by必须为serverless-framework、version必须为整数字符串。

内置技能的来源则见 manifest.js:生产构建时由 esbuild 在构建期把技能清单注入为__SF_SKILLS_MANIFEST__常量(与__SF_CORE_VERSION__同一模式);从源码运行时则直接读取仓库根skills/目录——两条路径共用同一个读取函数,避免行为漂移。

自动更新:任意 serverless 命令都会静默刷新技能

一旦安装,技能会自动保持最新:只要用捆绑了更新技能的更新版 CLI运行任意serverless命令,已安装的技能会被静默升级,并打印一行类似Serverless agent skills updated: ...的通知。

自动更新的行为边界可以从 auto-update.js 的守卫条件得到完整印证:

• 只前进,不降级。同步引擎 engine.js 的核心不变量写在文件头注释里:"永不删除;只覆盖那些 SKILL.md 带有metadata.managed-by: serverless-framework且版本更低的文件"。因此旧版 CLI 永远不会把队友用新版 CLI 装上的技能降回去(见syncSkills中skill.version > meta.version的判断,版本相同或更高一律跳过);
• CI 环境跳过。isCICDEnvironment()为真时直接返回,不在流水线里动工作区文件;
• 永不抛错。整个钩子包在 try/catch 中,注释明确写着"技能问题绝不能打断用户真正的命令";
• opt-in 门槛。自动模式(mode:auto)只收敛"已存在 Framework 托管技能"的目录,绝不主动引导创建新目录——所以自动更新永远不会替你"多装一个目录";
• 新技能会跟随进已有目录。更新版 CLI 新增的技能,会被安装进"已经包含 Framework 托管技能"的目录,而不会额外创建新目录;
• 自动更新自身不会在serverless agent ...命令触发时运行,且要求存在服务配置文件。

引擎的落盘方式也值得留意:写入采用"先写*.tmp-sf临时文件再 rename"的原子写,避免半截文件被智能体读到。

定制某个技能:从框架托管中"接管"

Framework 托管的技能在更新时会被覆盖。如果希望保留自己的修改,只需编辑该技能的SKILL.md,删除 frontmatter 中的managed-by一行:

metadata: managed-by: serverless-framework # ← 删除这一行即可接管

删除之后,框架就再也不碰这个技能——它完全归你了。源码层面,这一行为对应syncSkills中的分支:检测到!meta.managed时记录reason: 'ejected'并跳过,既不覆盖也不报错,因此你的定制版本会在后续所有 CLI 版本中稳定存在。

卸载

直接删除技能文件夹即可(或整个删除.claude/skills/.agents/skills目录)。这里有一个容易误解的细节:只要另一个目录中仍存在 Framework 托管的技能,被删除的目录就不会被重建——即使重新运行install也不会。要彻底移除,需要把两个目录中所有 Framework 托管的技能文件夹全部删除。

配套工具:serverless agent inspect

当智能体已经能通过技能文件"读懂"你的服务后,调试时还需要知道实际部署出去的 AWS 配置长什么样。serverless agent inspect正是为此设计:一次只读调用即可获取已部署资源的实时 AWS 配置。其资源发现逻辑位于 packages/serverless/lib/plugins/agent/ ——lib/discover-resources.js负责发现资源,lib/registry/下按资源类型(Lambda、API Gateway、CloudFront、DynamoDB、EventBridge、S3、SQS/SNS、Iot、CloudWatch 等)分文件实现了各资源的只读取回。当智能体需要"推理实际在跑什么"而不是仅仅盯着serverless.yml源码时,这条只读通道与技能文件形成互补。

小结

从仓库文件视角快速核对:技能内容与清单在 skills/ 与 skills/manifest.json,同步与检测逻辑在 packages/sf-core/src/lib/agent-skills/,命令级参考文档在 agent-skills-install 与 agent-inspect。

【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless