企业官网建设流程全解析

1. 从“skills”这个标题说起：它到底指什么

第一次看到“skills”这个标题，很多人会以为是某个泛泛而谈的能力清单，或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Genkit、npx、Google Cloud 这些关键词，方向就非常明确了——这里说的 skills，是围绕 AI Agent 生态构建的一套可插拔能力模块。简单讲，它让一个通用的大模型 Agent 能够通过加载不同的技能包，快速获得特定领域的执行能力，比如写论文、做分镜、自动挖洞、前端开发辅助等等。

我最早接触这个概念是在折腾 Claude 的 Agent 能力扩展时。当时想让一个对话式 Agent 帮我完成一些重复性的工程任务，比如自动跑 Playwright 脚本、自动整理 GitHub 仓库的 issue，结果发现光靠提示词根本不够稳定。后来才意识到，Agent 的能力边界不应该靠“提示词工程”去硬撑，而应该用结构化的 skills 来定义。这就像给一个刚入职的通用型员工配了一套标准作业程序，他不需要重新学习整个行业，只需要按技能包里的流程执行就行。

这套东西解决的核心问题是：让 Agent 的能力从“什么都能聊两句”变成“某件事能稳定做对”。适合谁来参考？如果你正在做 AI Agent 相关的开发、想给自己的工具链加自动化能力、或者单纯想搞清楚 npx 安装 skills 的完整流程，那这篇内容会对你有直接帮助。如果你只是好奇 AI 能干什么，也可以从里面的实操部分感受到这套机制的设计思路。

2. Agent Skills 的整体设计与思路拆解

2.1 为什么是“技能包”而不是“大提示词”

很多人第一反应是：我直接把要求写进系统提示词不就行了？我试过，短期可以，长期一定崩。原因有三个。第一，提示词越长，模型对每一段的注意力越稀释，关键约束容易被忽略。第二，不同任务之间的提示词会互相干扰，比如你同时要求它“严谨引用”和“自由发挥”，模型就会摇摆。第三，提示词无法版本化管理，改一处可能影响全部行为。

Skills 的思路是把能力拆成独立模块，每个模块有自己的元数据、触发条件、执行逻辑和依赖声明。Agent 在运行时根据当前任务动态加载对应的 skill，用完就卸载。这就像操作系统加载驱动，而不是把所有驱动代码塞进内核。好处是隔离性好、可复用、可单独测试。热搜词里出现的“agent skills测试”也印证了这一点——每个 skill 都可以独立验证，不会因为改了一个技能把整个 Agent 搞崩。

2.2 核心组成：一个 skill 里到底有什么

基于我实际拆解过的几个 skill 包，一个标准的 Agent Skill 通常包含以下部分：

• 元数据文件：声明 skill 的名称、版本、作者、适用场景、依赖项。通常是 JSON 或 YAML 格式。
• 触发描述：用自然语言描述“什么情况下应该激活这个 skill”，Agent 靠这个做路由。
• 执行逻辑：可以是提示词模板、函数调用定义、外部脚本入口，或者几者的组合。
• 资源文件：比如模板、示例、参考数据、分镜脚本样例等。
• 测试用例：用来验证 skill 在给定输入下是否产生预期输出。

这里的关键设计是触发描述与执行逻辑分离。触发描述面向 Agent 的调度器，执行逻辑面向实际运行环境。这样调度器不需要理解具体怎么执行，只需要判断该不该调用。这个思路和微服务里的服务发现很像，注册中心只管路由，不管业务实现。

2.3 与 Genkit、Google Cloud 的关系

热搜词里同时出现了 Genkit 和 Google Cloud，这不是偶然。Genkit 是一个用于构建 AI 功能的开发框架，它提供了定义工具、流程和 Agent 的基础设施。Skills 可以理解为跑在 Genkit 之上的能力单元。而 Google Cloud 提供的是运行环境和模型接入能力，比如 Vertex AI 的模型端点。

我自己的理解是：Genkit 负责“怎么把 skill 接进 Agent 的调用链”，Google Cloud 负责“skill 执行时用哪个模型、在哪跑”。npx 则是本地开发和调试时的入口工具，让你不用全局安装就能拉起一个 skill 的运行环境。这三者构成了从开发到部署的完整链路。

2.4 方案选型的几个关键取舍

在实际搭建时，有几个选择需要提前想清楚。

第一，skill 的粒度。太粗，一个 skill 干太多事，复用性差；太细，调用链太长，延迟和错误率都会上升。我的经验是：一个 skill 对应一个可独立验证的完整任务单元。比如“生成分镜脚本”是一个 skill，“把分镜转成图片提示词”是另一个，不要混在一起。

第二，同步还是异步。如果 skill 执行时间超过几秒，建议设计成异步任务，否则会阻塞 Agent 的主循环。热搜词里的“自动挖洞 skills”这类安全测试场景，往往需要长时间运行，异步是必须的。

第三，依赖管理方式。是每个 skill 自带依赖，还是共享一个基础环境？自带依赖隔离性好但体积大，共享环境轻量但容易冲突。我倾向于核心依赖共享，特殊依赖自带，用锁文件固定版本。

3. 核心细节解析与实操要点

3.1 目录结构：一个可运行的 skill 长什么样

我拿一个实际用过的前端开发辅助 skill 举例，目录结构大致如下：

my-skill/ ├── skill.json ├── trigger.md ├── executor.js ├── prompts/ │ └── main.md ├── resources/ │ └── template.html └── tests/ └── basic.test.js

skill.json是入口，内容大概是这样：

{ "name": "frontend-helper", "version": "1.0.0", "description": "辅助前端开发，生成组件骨架和样式建议", "triggers": ["生成组件", "写一个前端页面", "帮我搭个布局"], "entry": "executor.js", "dependencies": { "playwright": "^1.40.0" } }

trigger.md里写的是更详细的触发条件，用自然语言描述，供 Agent 的调度模型判断。executor.js是实际执行入口，可以调用外部命令、请求模型、读写文件。prompts/main.md存放提示词模板，和代码分离，方便非工程人员调整。

注意：skill.json里的triggers不要写得太宽泛，比如只写“帮我”，否则任何请求都会命中这个 skill，导致调度混乱。我踩过这个坑，后来改成具体动作词才稳定。

3.2 触发机制的设计细节

触发机制是整个 skills 体系里最容易被低估的部分。很多人以为只要写好执行逻辑就行，结果发现 Agent 根本不调用，或者乱调用。核心在于触发描述的质量。

一个好的触发描述应该包含三个要素：动作类型、对象范围、排除条件。比如：

• 动作类型：生成、转换、检查、部署
• 对象范围：React 组件、CSS 布局、API 接口
• 排除条件：不适用于后端逻辑、不适用于数据库迁移

我实测下来，把这三要素写清楚之后，误触发率能降一半以上。另外，触发描述里不要用同义词堆砌，比如“生成、创建、新建、搭建”全写上去，反而会让调度模型困惑。选最常用的两三个词就够了。

3.3 执行逻辑的三种常见形态

根据任务类型不同，执行逻辑可以分成三类：

第一类：纯提示词驱动。适合文本生成、改写、总结类任务。executor 只是把输入套进模板，调用模型，返回结果。这类 skill 最简单，但也最依赖模型本身的能力。

第二类：脚本驱动。适合需要确定性操作的任务，比如文件处理、命令执行、数据转换。executor 直接调用本地脚本或外部命令。热搜词里的“npx playwright install失败”就属于这类场景——skill 需要调用 Playwright，但环境没配好就会失败。

第三类：混合驱动。先用脚本做确定性处理，再用模型做判断或生成。比如“自动挖洞 skills”，先用扫描脚本收集信息，再用模型分析潜在风险点。这类 skill 最实用，但也最复杂，需要处理好脚本和模型之间的数据传递。

3.4 依赖安装与 npx 的角色

npx 在 skills 开发里主要承担两个角色：一是快速拉起开发环境，二是执行 skill 的安装脚本。比如：

npx create-agent-skill my-skill

这条命令会生成一个 skill 的脚手架，包含基础目录和配置文件。安装依赖时：

npx skills install ./my-skill

它会读取skill.json里的 dependencies，自动安装。但这里有个常见问题：如果依赖里有 Playwright 这类需要下载浏览器二进制的包，在国内网络环境下很容易失败。我的处理方式是先单独安装 Playwright 并指定国内可用的下载源，再执行 skill 安装。具体做法后面排查部分会讲。

提示：npx 执行时默认使用临时目录，如果你需要反复调试同一个 skill，建议先npm install -g或者用npx --no-install配合本地已安装的包，避免每次重新下载。

3.5 资源文件与提示词的版本管理

资源文件和提示词模板一定要纳入版本管理，而且要和代码分开提交。原因是提示词的改动频率远高于代码，如果混在一起，每次调提示词都会产生大量无意义的代码 diff。我的做法是prompts/和resources/单独用一个仓库或者子模块管理，skill 主仓库只保留引用。

另外，提示词模板里不要硬编码具体模型名称。应该用变量占位，比如{{model}}，在运行时注入。这样同一个 skill 可以在不同模型之间切换，方便做 A/B 测试。热搜词里“claude agent skills: a first principles deep dive”这类内容，核心也是在讨论这种可移植性。

4. 实操过程与核心环节实现

4.1 从零搭建一个 skill 的完整流程

我以“生成分镜脚本”这个 skill 为例，走一遍完整流程。这个 skill 的需求是：输入一段剧情描述，输出结构化的分镜脚本，包含镜号、画面描述、台词、时长建议。

第一步：初始化目录。

mkdir storyboard-skill cd storyboard-skill npm init -y

第二步：创建 skill.json。

{ "name": "storyboard-generator", "version": "1.0.0", "description": "根据剧情描述生成分镜脚本", "triggers": ["生成分镜", "写分镜脚本", "把剧情转成分镜"], "entry": "executor.js", "dependencies": {} }

第三步：编写触发描述 trigger.md。

当用户提供一段剧情、故事梗概或场景描述，并要求生成分镜、镜头脚本、拍摄脚本时，激活此技能。 不适用于：纯对话生成、角色设定、世界观构建。

第四步：编写执行逻辑 executor.js。

const fs = require('fs'); const path = require('path'); async function execute(input, context) { const template = fs.readFileSync( path.join(__dirname, 'prompts', 'main.md'), 'utf-8' ); const prompt = template.replace('{{input}}', input); const result = await context.callModel({ prompt, model: context.model || 'default' }); return { type: 'storyboard', content: result, format: 'markdown' }; } module.exports = { execute };

第五步：编写提示词模板 prompts/main.md。

你是一个专业的分镜师。请根据以下剧情描述，生成分镜脚本。 要求： 1. 每个镜头包含：镜号、景别、画面描述、台词、时长建议 2. 景别从远景、全景、中景、近景、特写中选择 3. 画面描述要具体，包含人物动作、环境、光线 4. 时长建议以秒为单位，总和不超过 60 秒 剧情描述： {{input}} 请以 Markdown 表格输出。

第六步：本地测试。

npx skills run ./storyboard-skill --input "一个人在雨夜走进一家便利店"

如果一切正常，会返回一个包含分镜表格的结果。我第一次跑的时候返回的是纯文本，没有表格，原因是提示词里虽然写了 Markdown 表格，但模型没有严格执行。后来在模板里加了一个示例输出，就稳定了。

4.2 参数选择与计算过程

在分镜 skill 里，时长建议是一个需要计算的参数。我的做法是给模型一个约束公式：

• 总时长上限 = 60 秒
• 镜头数量 = 剧情复杂度系数 × 基础镜头数
• 单镜头时长 = 总时长 / 镜头数量

剧情复杂度系数根据输入文本的长度和事件数量估算。比如输入 100 字以内、单一事件，系数取 0.8；100 到 300 字、两到三个事件，系数取 1.0；300 字以上、多线叙事，系数取 1.2。基础镜头数设为 8。这样算下来，简单剧情大约 6 个镜头，每个 10 秒；复杂剧情大约 10 个镜头，每个 6 秒。

这个计算不需要精确，但要有依据。否则模型给出的时长要么太短，画面塞不下；要么太长，节奏拖沓。我在实际使用中会把计算结果作为提示词的一部分传给模型，让它在这个框架内发挥。

4.3 接入 Genkit 的实操记录

如果要把 skill 接入 Genkit 流程，需要做一层适配。Genkit 的工具定义要求输入输出有明确的 schema。我的做法是在 executor 外面包一层：

const { defineTool } = require('genkit'); const storyboardTool = defineTool({ name: 'storyboard-generator', description: '根据剧情描述生成分镜脚本', inputSchema: { type: 'object', properties: { plot: { type: 'string' } }, required: ['plot'] }, outputSchema: { type: 'object', properties: { storyboard: { type: 'string' } } } }, async (input) => { const result = await execute(input.plot, { callModel }); return { storyboard: result.content }; });

这里的关键是 schema 要和 skill 的实际输入输出对齐。我遇到过 schema 写得太宽松，导致 Genkit 在编排时无法正确传递参数。后来把必填字段和类型都写死，问题就解决了。

4.4 部署到 Google Cloud 的注意事项

部署环节主要涉及模型端点和运行环境的配置。我的经验是：

• 模型端点用环境变量注入，不要写死在代码里
• skill 的资源文件打包进部署产物，不要依赖运行时下载
• 如果 skill 需要调用外部命令，确保运行环境里有对应的二进制

有一次我把一个依赖 Playwright 的 skill 部署上去，结果运行时报“浏览器未找到”。原因是部署环境里没有安装浏览器二进制。后来在构建脚本里加了一步npx playwright install chromium，并且把浏览器缓存目录也打包进去，才稳定运行。

注意：部署环境的网络策略可能和本地不同，依赖下载类操作最好在构建阶段完成，不要留到运行时。

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

5.1 npx playwright install 失败的排查路径

这是热搜里出现频率很高的问题，我自己也踩过好几次。典型报错是下载超时或者证书错误。排查顺序如下：

我遇到最多的是缓存目录权限问题。因为之前用 sudo 跑过一次，导致缓存目录归属 root，后续普通用户无法写入。解决方法是删掉缓存目录重新安装，或者改归属。

5.2 Skill 不被触发的几种原因

Agent 不调用 skill，通常不是 skill 本身的问题，而是触发描述或调度配置的问题。常见原因：

• 触发词太窄，用户的实际表达没有命中
• 触发词太宽，被其他 skill 抢先匹配
• skill 没有正确注册到调度器
• 调度器的阈值设置过高，置信度不够就不调用

我的排查方法是先把触发描述打印出来，手动模拟调度器的判断逻辑。如果手动判断都觉得模糊，那模型肯定也判断不准。调整时优先增加具体动作词，减少抽象描述。

5.3 执行超时与异步改造

同步执行的 skill 如果超过调度器设定的超时时间，会被强制中断。我一开始没注意这个限制，写了一个需要跑 30 秒的扫描 skill，结果每次都在 10 秒时被掐断。后来改成异步任务：skill 先返回一个任务 ID，实际执行在后台进行，Agent 通过轮询或回调获取结果。

改造后的 executor 大致逻辑：

async function execute(input, context) { const taskId = generateTaskId(); context.registerTask(taskId, { status: 'running' }); runInBackground(async () => { const result = await doHeavyWork(input); context.updateTask(taskId, { status: 'done', result }); }); return { taskId, status: 'accepted' }; }

这样调度器不会阻塞，用户体验也好很多。

5.4 依赖冲突的处理经验

多个 skill 共享环境时，依赖冲突很常见。比如 skill A 需要 Playwright 1.40，skill B 需要 1.35。我的处理原则是：

• 核心依赖统一版本，由基础环境提供
• 特殊依赖用独立目录隔离，通过路径引用
• 实在无法兼容的，拆成两个独立运行环境

热搜词里“codex好用的skills”和“claude 国内安装skills 官方市场”这类内容，背后其实都涉及依赖管理的问题。不同平台的 skill 生态不一样，安装方式也不一样，但依赖冲突的解决思路是相通的。

5.5 常见问题速查表

6. 从 skills 生态看能力扩展的边界

Skills 这套机制最吸引我的地方，是它把 Agent 的能力扩展从“改模型”变成了“加模块”。这意味着一个通用 Agent 可以通过加载不同 skill，快速适应完全不同的场景。今天加载分镜 skill 做视频前期，明天加载挖洞 skill 做安全测试，底层模型不用换，调度逻辑不用改。

但边界也很明显。Skill 能解决的是“流程确定性”问题，解决不了“模型能力上限”问题。如果模型本身不具备某种推理能力，再好的 skill 也补不上。所以我的做法是：能用脚本确定性完成的，不交给模型；必须用模型判断的，用 skill 把输入输出约束好，减少自由发挥空间。

另外，skill 的维护成本不能忽视。每加一个 skill，就多一份触发描述要调、多一份依赖要管、多一份测试要跑。我现在的习惯是，新 skill 先在小范围用一周，确认稳定后再正式注册到主调度器。热搜里“今天学会了skills，打开新世界”这种感受我也有过，但新鲜劲过去之后，真正留下来的是那些经过反复打磨、触发精准、执行稳定的 skill。

最后分享一个我常用的调试技巧：在 skill 的 executor 里加一个DEBUG环境变量开关，打开时把输入、提示词、模型返回、执行耗时全部打到日志里。排查问题时不用猜，直接看日志。这个习惯帮我省了大量时间，尤其是处理触发不准和执行超时这两类问题时，日志比任何文档都管用。