create-voltagent：用官方 Skill 按 VoltAgent 规范初始化 AI Agent 项目

大模型Skills create-voltagent VoltAgent Agent Skill AI Agent TypeScript 2026-08-16 78 阅读

前言

用 Cursor、Codex CLI 或 Claude Code 说一句「帮我搭一个 AI Agent 项目」，模型往往能写出能跑的 TypeScript。问题是：依赖选哪套、目录怎么切、环境变量叫什么、开发服务器用哪个框架，每次都不一样。框架自己其实有脚手架，但 Agent 未必会去跑官方 CLI，更容易按通用模板拼出一个「看起来像 Agent、却对不上框架约定」的仓库。

create-voltagent 就是把这件事写成 Agent Skill 的产物。它来自 VoltAgent 官方维护的 VoltAgent/skills 仓库，正文在 skills/create-voltagent/SKILL.md，许可证 MIT。同一份 SKILL.md 按 Agent Skills 通用格式编写，Cursor、Codex CLI、Claude Code 等能读 Skill 的工具都可以加载。它也被收录进 VoltAgent 维护的技能目录 awesome-agent-skills。

和「通用的创建项目 / 写 Skill」类能力不同，这份文件只服务一件事：按 VoltAgent 自己的 CLI 与手动步骤，把一个可运行的 Agent 工程搭起来。

这是什么

一句话定位：指导使用 VoltAgent 框架创建 AI Agent 项目，覆盖 create-voltagent-app CLI 初始化，以及不跑脚手架时的完整手动搭建。

官方 frontmatter：

  • name：create-voltagent
  • description：Skill for creating AI agent projects using the VoltAgent framework. Guide for CLI setup and manual bootstrapping.
  • author：VoltAgent
  • version：1.0.0
  • repository：https://github.com/VoltAgent/skills

VoltAgent 是一套开源 TypeScript Agent 工程平台：核心是 @voltagent/core 这类运行时（Agent、Tool、Memory、Workflow 等），旁边还有 VoltOps Console 做观测、部署与评测。官方文档入口是 voltagent.dev/docs。create-voltagent 不替代这些文档，它解决的是更前面一步——让编程助手按官方路径开工，而不是临时发明一套项目结构。

同仓库里还有三份配套 Skill，职责不同，不宜混用：

create-voltagent 的边界更窄：只负责「从零创建项目」。

核心功能与亮点

根据官方 SKILL.md，Agent 在用户要创建 VoltAgent 项目时，必须先问一句：

How would you like to create your VoltAgent project?

然后给出三条路：

  1. Automatic Setup：直接跑 npm create voltagent-app@latest，处理交互提示
  2. Interactive Guide：先确认服务器框架、模型提供商和 API Key，再执行 CLI
  3. Manual Installation：按文档逐步装依赖、写配置、补齐可运行示例

这就是框架专属 Skill 和通用 Skill 的差别。通用「搭个 Node 项目」只会给你 package.json 和入口文件；这份 Skill 把 VoltAgent 已经拍板的选择写死了：Hono 或 Elysia、六家模型提供商、.env 字段名、tsdown 打包、以及官方示例里的天气 Tool 与报销审批 Workflow。

CLI 会问什么、会生成什么

create-voltagent-app 的交互流程在 Skill 里写得很具体：

  1. 项目名（默认 my-voltagent-app）
  2. 服务器框架：Hono（推荐）或 Elysia
  3. AI 提供商：OpenAI、Anthropic、Google、Groq、Mistral、Ollama
  4. 需要时填写 API Key（Ollama 可跳过）
  5. 安装依赖并生成脚手架
  6. 写入 .env、README.md、tsconfig.json、tsdown.config.ts 以及 Docker 相关文件
  7. 本机有 Git 时初始化仓库

生成后的目录约定如下：

my-voltagent-app/
|-- src/
|   |-- index.ts
|   |-- tools/
|   |   |-- index.ts
|   |   `-- weather.ts
|   `-- workflows/
|       `-- index.ts
|-- .env
|-- .voltagent/
|-- Dockerfile
|-- .dockerignore
|-- .gitignore
|-- README.md
|-- package.json
|-- tsconfig.json
`-- tsdown.config.ts

.voltagent/ 用来放 LibSQL 的本地库（Skill 示例里是 memory.db 和 observability.db），不是可有可无的缓存目录。

环境变量也标准化了

CLI 会按所选提供商写入 .env（没有 Key 就留占位）。Skill 列出的常见字段：

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_GENERATIVE_AI_API_KEY=...
GROQ_API_KEY=...
MISTRAL_API_KEY=...
OLLAMA_HOST=http://localhost:11434

VOLTAGENT_PUBLIC_KEY=...
VOLTAGENT_SECRET_KEY=...

VOLTAGENT_PUBLIC_KEY / VOLTAGENT_SECRET_KEY 给 VoltOps 客户端用。只跑本地 Agent、暂时不接 Console 时，Skill 示例允许写成空字符串，但字段本身仍在模板里。

手动路径不是「再写一遍 CLI」

不想用脚手架时，Skill 给出完整 10 步：建目录、装 @voltagent/core 等包、补 package.json scripts、写 tsconfig.json 与 tsdown.config.ts、配 .env、实现 Tool / Workflow、写 src/index.ts，最后 npm run dev。

手动安装时服务器包二选一：@voltagent/server-hono 或 @voltagent/server-elysia。开发依赖固定为 typescript、tsx、tsdown、@types/node、@biomejs/biome。package.json 里的 volt 脚本指向 VoltAgent CLI，Skill 写明可用于 init、deploy、eval、prompts、tunnel、update 这类项目工具。

安装与启用

该 Skill 收录在 VoltAgent/skills 仓库。官方 README 的安装方式以 npx skills add 为准；这个命令会装上仓库里的整套 Skill，不只是 create-voltagent。

官方推荐（支持 add-skill 的 Agent）

npx skills add VoltAgent/skills

skills.sh 上若只装这一份，命令是：

npx skills add https://github.com/voltagent/skills --skill create-voltagent

官方文档 Docs for AI Assistants 把 Local Skills 和 MCP 文档服务分成两条线：Skill 适合能读本地文件的助手；若要在 Cursor / VS Code 里按需查文档、示例和 changelog，可以用 @voltagent/docs-mcp。后者不是 create-voltagent 本身，但和「让 AI 按官方资料写 VoltAgent 代码」是同一套工具链。

手动克隆

git clone https://github.com/VoltAgent/skills.git

然后把 skills/create-voltagent/ 放到各工具会扫描的 Skill 目录。SKILL.md 是通用格式。按 Cursor 文档，项目级会从 .agents/skills/、.cursor/skills/ 自动发现；用户级对应 ~/.agents/skills/、~/.cursor/skills/。兼容目录还包括 .claude/skills/、.codex/skills/ 以及对应的用户级路径。手动放置时目录应类似：

.cursor/skills/create-voltagent/SKILL.md

或：

.agents/skills/create-voltagent/SKILL.md

Claude Code 项目级为 .claude/skills/create-voltagent/SKILL.md，用户级为 ~/.claude/skills/create-voltagent/SKILL.md。Codex CLI 扫描 $CODEX_HOME/skills（默认 ~/.codex/skills）以及项目内的 .codex/skills/。

启用后，在对话里输入 / 搜索 create-voltagent 可手动调用。用户说「创建 VoltAgent 项目」「初始化 voltagent-app」时，Agent 也应按 description 自动选用。

典型用法示例

前置条件

Skill 正文写明：

  • Node.js 20+（推荐 >= 20.19.0）
  • Git（可选，用于自动 git init）
  • 所选模型提供商的 API Key（Ollama 不需要）

官方 Quick Start 把 Node 版本说得更硬：环境需要 Node.js 20.19 或更新，否则生成项目用的 tsdown 打包可能遇到 ESM 解析问题。第三方站点若仍写 Node 18 或 npm create voltagent@latest，与官方 CLI 包名不一致，以 npm create voltagent-app@latest 为准。

最快路径：让 Agent 跑 CLI

在已安装 Skill 的对话里可以直接说：

请按 create-voltagent 帮我创建一个 VoltAgent 项目。
用 Automatic Setup，项目名 my-voltagent-app，服务器选 Hono，模型提供商选 OpenAI。

Agent 应执行：

npm create voltagent-app@latest my-voltagent-app

pnpm / yarn / bun 的等价命令在 Skill 里都有：

pnpm create voltagent-app@latest
yarn create voltagent-app@latest
bun create voltagent-app@latest

指定目录、或从官方仓库拉示例：

npm create voltagent-app@latest my-voltagent-app
npm create voltagent-app@latest -- --example with-workflow

--example 的源是 voltagent/voltagent/examples。部分包管理器必须在 --example 前加 --。拉完示例后还要 npm install 和 npm run dev。

进入项目后启动开发服务器：

cd my-voltagent-app
npm run dev

若选了 Ollama，Skill 额外要求先拉模型：

ollama pull llama3.2

官方 Quick Start 记录的启动信息是：HTTP 服务在 http://localhost:3141，Swagger UI 在 http://localhost:3141/ui，并提示用 VoltOps Console 测 Agent。示例对话是问「What’s the weather in San Francisco?」，对应脚手架里的天气 Tool。

手动路径里的最小可运行形状

Skill 的入口示例把 Agent、Memory、Observability、Workflow 和 Hono 服务器注册在一起。模型字符串格式是 provider/model，例如 openai/gpt-4o-mini、anthropic/claude-3-5-sonnet、ollama/llama3.2。官方文档说明：使用这种字符串时不必再单独引入提供商 SDK，把对应 API Key 写进环境变量即可。仓库 README 里还有 openai("gpt-4o-mini") 这种 Vercel AI SDK 写法，两种都出现在官方材料中；Skill 手动步骤用的是字符串形式。

Tool 示例 src/tools/weather.ts 用 createTool + Zod 声明参数。需要注意：示例的 execute 返回的是写死的 21 C and sunny，用来演示 Tool 注册，不是真实天气 API。

Workflow 示例 expenseApprovalWorkflow 用 createWorkflowChain：金额不超过 500 由系统自动批准；超过 500 则 suspend，等管理者用 resumeData 恢复。这是官方 Quick Start 里同一份「人在回路」示例，可以在 Console 的 Workflows 页用下面两组输入分别试自动批准和挂起：

{
  "employeeId": "EMP-123",
  "amount": 250,
  "category": "office-supplies",
  "description": "New laptop mouse and keyboard"
}

{
  "employeeId": "EMP-456",
  "amount": 750,
  "category": "travel",
  "description": "Flight tickets for client meeting"
}

选 Elysia 时，Skill 要求把 honoServer 换成 elysiaServer，并改对应 import，其余结构不变。

生产构建官方写的是：

npm run build
npm start

build 走 tsdown，把 src/index.ts 以及同级的 tools/、workflows/ 打进 dist/index.js，避免 Node ESM 加载器报 ERR_UNSUPPORTED_DIR_IMPORT。

需要把本地服务暴露给同事或收 webhook 时，官方 Quick Start 使用：

npx @voltagent/cli init
pnpm volt tunnel 3141

默认端口就是 3141。这是 VoltAgent CLI 的能力，create-voltagent 只在 scripts 里把 volt 接上，并不展开 tunnel 的全部参数。

适用场景与注意事项

适合

  • 要从零建一个 VoltAgent 项目，希望 Agent 跑官方 CLI，而不是手写一套「像 LangChain / 像 Next.js」的目录
  • 需要对照官方约定核对现有脚手架：Hono/Elysia、.voltagent/、tsdown、环境变量名
  • 团队已经在用 Cursor / Claude Code / Codex，希望「创建 Agent 项目」这件事可重复、可共享

使用时要注意

  1. 这是脚手架 Skill，不是架构手册。 创建完成后的目录约定、Memory 选型、多 Agent 协作，应交给同仓库的 voltagent-best-practices / voltagent-core-reference，或直接查 官方文档。
  2. Node 版本以 20.19+ 为准。 Skill 写 20+ 并推荐 >= 20.19.0；Quick Start 明确要求 20.19，否则 tsdown 的 ESM 解析可能出问题。
  3. CLI 包名是 create-voltagent-app。 不要写成 create-voltagent。后者是 Skill 的名字，不是 npm 脚手架包名。
  4. 天气 Tool 是占位实现。 示例返回固定气温和天气，接入真实 API 需要自己改 execute。
  5. API Key 会进 .env。 CLI 在需要时会提示填写。仓库若要提交，应确认 .gitignore 已覆盖 .env（脚手架会写这份文件）。
  6. Ollama 仍要本机模型。 可以不填云厂商 Key，但 Skill 要求 ollama pull llama3.2，并且 .env 里是 OLLAMA_HOST=http://localhost:11434。
  7. Skill 目录里目前主要是 SKILL.md。 没有附带评测集。效果取决于模型是否先问三条创建路径、是否按官方命令执行，而不是跳过 CLI 直接编一个项目。

小结

create-voltagent 把 VoltAgent 官方的「如何开一个新项目」收成一份可移植 Skill：先问 Automatic / Interactive / Manual，再按 npm create voltagent-app@latest 或 10 步手动流程落到 Hono/Elysia、提供商、环境变量和示例 Tool/Workflow。它不教你设计多 Agent 系统，但能避免编程助手用通用模板绕开框架自己的脚手架。

官方地址：
https://github.com/voltagent/skills/tree/main/skills/create-voltagent

框架文档：
https://voltagent.dev/docs/

相关文章

腾讯 CubeSandbox 开源：60ms 冷启动的硬件级 AI Agent 执行环境 2026-07-29 MCP 最大版本更新：无状态核心如何让 AI Agent 真正上生产 2026-07-30 腾讯开源 CubeSandbox：60ms 冷启动、硬件隔离的 AI Agent 执行沙箱 2026-07-30 OpenCode 未认证 HTTP 服务致 RCE：开源 AI 编码 Agent 的安全红线 2026-07-30 Google 发布 Gemini 3.6 Flash：Token 效率提升 17%、Agent 默认模型的性价比之战 2026-07-30
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜