create-voltagent：用官方 Skill 按 VoltAgent 規範初始化 AI Agent 項目

大模型Skills create-voltagent VoltAgent Agent Skill AI Agent TypeScript 2026-08-16 74 閱讀

前言

用 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
羽毛球分组比赛记分
小程序二维码

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

小夜