Preface¶

When you say “help me set up an AI Agent project” to Cursor, Codex CLI, or Claude Code, the model often produces runnable TypeScript code. The problem is: which set of dependencies to choose, how to structure the directory, what names to use for environment variables, and which framework to use for the development server—all of these vary every time. The framework itself actually has a scaffolding tool, but the Agent may not run the official CLI, and is more likely to piece together a repository that “looks like an Agent but does not conform to the framework’s conventions” using a generic template.

create-voltagent is the result of turning this task into an Agent Skill. It comes from the VoltAgent/skills repository officially maintained by VoltAgent, with the main content in skills/create-voltagent/SKILL.md, licensed under MIT. The same SKILL.md is written in the Agent Skills universal format, and can be loaded by tools that can read Skills such as Cursor, Codex CLI, and Claude Code. It is also included in the skill directory awesome-agent-skills maintained by VoltAgent.

Unlike general “create project/write Skill” capabilities, this document only serves one purpose: set up a runnable Agent project according to VoltAgent’s own CLI and manual steps.

What is this¶

One-sentence positioning: Guide to creating an AI Agent project using the VoltAgent framework, covering create-voltagent-app CLI initialization, and complete manual setup when not using the scaffolding.

Official 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 is an open-source TypeScript Agent engineering platform: the core is runtimes such as @voltagent/core (Agent, Tool, Memory, Workflow, etc.), alongside VoltOps Console for observation, deployment, and evaluation. The official documentation entry is voltagent.dev/docs. create-voltagent does not replace these documents; it solves the earlier step—letting programming assistants start work according to the official path, rather than temporarily inventing a project structure.

There are three supporting Skills in the same repository with different responsibilities and should not be mixed:
- voltagent-best-practices: Architectural conventions for Agent/Workflow, memory, and servers
- voltagent-core-reference: Reference for VoltAgent class options and lifecycle
- voltagent-docs-bundle: Access embedded documentation matching the current @voltagent/core version

The scope of create-voltagent is narrower: it only handles “creating a project from scratch”.

Core Features and Highlights¶

According to the official SKILL.md, when the user wants to create a VoltAgent project, the Agent must first ask:

How would you like to create your VoltAgent project?

Then present three options:
1. Automatic Setup: Run npm create voltagent-app@latest directly and handle interactive prompts
2. Interactive Guide: Confirm the server framework, model provider, and API key first, then execute the CLI
3. Manual Installation: Install dependencies, write configurations, and complete the runnable example step by step according to the documentation

This is the difference between framework-specific Skills and generic Skills. A generic “create a Node project” will only give you a package.json and an entry file; this Skill hardcodes the choices that VoltAgent has already finalized: Hono or Elysia, six model providers, .env field names, tsdown packaging, and the official example weather Tool and expense approval Workflow.

What the CLI will ask and what it will generate¶

The interactive flow of create-voltagent-app is specifically written in the Skill:
1. Project name (default my-voltagent-app)
2. Server framework: Hono (recommended) or Elysia
3. AI provider: OpenAI, Anthropic, Google, Groq, Mistral, Ollama
4. Fill in the API key when required (Ollama can be skipped)
5. Install dependencies and generate the scaffolding
6. Write .env, README.md, tsconfig.json, tsdown.config.ts, and Docker-related files
7. Initialize the Git repository if Git is available locally

The generated directory convention is as follows:

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/ is used to store the local LibSQL database (the Skill example uses memory.db and observability.db), it is not an optional cache directory.

Environment variables are also standardized¶

The CLI will write to .env according to the selected provider (leave a placeholder if there is no key). The common fields listed in the 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 are for the VoltOps client. When running a local Agent without connecting to the Console for now, the Skill example allows setting them to empty strings, but the fields themselves still remain in the template.

The manual path is not “rewriting the CLI again”¶

When you do not want to use the scaffolding, the Skill provides a complete 10-step process: create a directory, install packages such as @voltagent/core, add package.json scripts, write tsconfig.json and tsdown.config.ts, configure .env, implement Tool/Workflow, write src/index.ts, and finally run npm run dev.

For manual installation, you have two server package options: @voltagent/server-hono or @voltagent/server-elysia. Development dependencies are fixed as typescript, tsx, tsdown, @types/node, @biomejs/biome. The volt script in package.json points to the VoltAgent CLI, and the Skill notes that it can be used for project tools such as init, deploy, eval, prompts, tunnel, update.

Installation and Enablement¶

This Skill is included in the VoltAgent/skills repository. The official README installation method uses npx skills add as the standard; this command will install the entire set of Skills in the repository, not just create-voltagent.

Official Recommendation (Agents that support add-skill)¶

npx skills add VoltAgent/skills

If you only want to install this single Skill on skills.sh, the command is:

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

The official documentation Docs for AI Assistants splits Local Skills and MCP documentation services into two lines: Skills are suitable for assistants that can read local files; if you want to check documentation, examples, and changelogs on demand in Cursor / VS Code, you can use @voltagent/docs-mcp. The latter is not create-voltagent itself, but it is part of the same toolchain as “letting AI write VoltAgent code according to official materials”.

Manual Clone¶

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

Then place skills/create-voltagent/ into the Skill directory that each tool will scan. SKILL.md is in the universal format. According to the Cursor documentation, project-level Skills are automatically discovered from .agents/skills/, .cursor/skills/; user-level paths correspond to ~/.agents/skills/, ~/.cursor/skills/. Compatible directories also include .claude/skills/, .codex/skills/ and their corresponding user-level paths. When placing manually, the directory should look similar to:

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

or:

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

For Claude Code, project-level path is .claude/skills/create-voltagent/SKILL.md, user-level path is ~/.claude/skills/create-voltagent/SKILL.md. Codex CLI scans $CODEX_HOME/skills (default ~/.codex/skills) and the project’s .codex/skills/.

After enabling, you can manually call it by typing / in the conversation and searching for create-voltagent. When the user says “create a VoltAgent project” or “initialize voltagent-app”, the Agent should automatically select it according to the description.

Typical Usage Examples¶

Prerequisites¶

The Skill body specifies:
- Node.js 20+ (recommended >= 20.19.0)
- Git (optional, for automatic git init)
- API key from the selected model provider (not required for Ollama)

The official Quick Start has stricter Node version requirements: the environment needs Node.js 20.19 or newer, otherwise the tsdown packaging used when generating the project may encounter ESM resolution issues. If third-party sites still mention Node 18 or npm create voltagent@latest, note that the package name is inconsistent with the official CLI; use npm create voltagent-app@latest as the standard.

Fastest Path: Let the Agent run the CLI¶

You can directly say in the conversation where the Skill has been installed:

Please help me create a VoltAgent project using create-voltagent.
Use Automatic Setup, project name my-voltagent-app, select Hono as the server, and OpenAI as the model provider.

The Agent should execute:

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

The equivalent commands for pnpm / yarn / bun are also included in the Skill:

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

Specify a directory, or pull an example from the official repository:

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

The source of --example is voltagent/voltagent/examples. Some package managers need to add -- before --example. After pulling the example, you also need to run npm install and npm run dev.

Start the development server after entering the project:

cd my-voltagent-app
npm run dev

If you selected Ollama, the Skill additionally requires pulling the model first:

ollama pull llama3.2

The startup information recorded in the official Quick Start is: the HTTP service is at http://localhost:3141, the Swagger UI is at http://localhost:3141/ui, and you are prompted to use the VoltOps Console to test the Agent. The example conversation asks “What’s the weather in San Francisco?”, which corresponds to the weather Tool in the scaffolding.

Minimal Runnable Shape in the Manual Path¶

The entry example in the Skill registers the Agent, Memory, Observability, Workflow, and Hono server together. The model string format is provider/model, for example openai/gpt-4o-mini, anthropic/claude-3-5-sonnet, ollama/llama3.2. The official documentation states that when using this string format, you do not need to separately import the provider SDK, just write the corresponding API key into the environment variable. There is also the Vercel AI SDK写法 such as openai("gpt-4o-mini") in the repository README, both formats appear in official materials; the manual step in the Skill uses the string format.

The Tool example src/tools/weather.ts uses createTool + Zod to declare parameters. It should be noted that the example’s execute returns a hard-coded 21 C and sunny, which is used to demonstrate Tool registration, not a real weather API.

The Workflow example expenseApprovalWorkflow uses createWorkflowChain: amounts under 500 are automatically approved by the system; amounts over 500 are suspended, waiting for the manager to resume with resumeData. This is the same “human-in-the-loop” example from the official Quick Start, you can test automatic approval and suspension in the Workflows page of the Console using the following two sets of inputs:

{
  "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"
}

When selecting Elysia, the Skill requires replacing honoServer with elysiaServer and changing the corresponding import, the rest of the structure remains unchanged.

The official production build command is:

npm run build
npm start

build uses tsdown to package src/index.ts and the sibling tools/ and workflows/ directories into dist/index.js to avoid the Node ESM loader throwing ERR_UNSUPPORTED_DIR_IMPORT.

When you need to expose the local service to colleagues or receive webhooks, the official Quick Start uses:

npx @voltagent/cli init
pnpm volt tunnel 3141

The default port is 3141. This is a capability of the VoltAgent CLI, and create-voltagent only connects the volt script in the package.json, and does not cover all parameters of tunnel.

Applicable Scenarios and Notes¶

Suitable For¶

Creating a VoltAgent project from scratch, hoping the Agent runs the official CLI instead of handwriting a directory structure that “looks like LangChain / looks like Next.js”
Needing to check existing scaffolding against official conventions: Hono/Elysia, .voltagent/, tsdown, environment variable names
Teams already using Cursor / Claude Code / Codex, hoping that “creating an Agent project” can be standardized and shared

Notes for Use¶

This is a scaffolding Skill, not an architecture manual. After the project is created, directory conventions, memory selection, and multi-Agent collaboration should be handled by the same repository’s voltagent-best-practices / voltagent-core-reference, or directly check the official documentation.
Node version must be 20.19+. The Skill writes 20+ and recommends >= 20.19.0; the Quick Start clearly requires 20.19, otherwise ESM resolution issues may occur with tsdown.
The CLI package name is create-voltagent-app. Do not write it as create-voltagent. The latter is the name of the Skill, not the npm scaffolding package name.
The weather Tool is a placeholder implementation. The example returns a fixed temperature and weather, you need to modify the execute function to connect to a real weather API.
API keys will be written to .env. The CLI will prompt you to fill them in when needed. If you want to commit to the repository, confirm that .gitignore covers .env (the scaffolding will generate this file).
Ollama still requires local models. You can skip the cloud vendor API key, but the Skill requires ollama pull llama3.2, and the .env file should have OLLAMA_HOST=http://localhost:11434.
Currently, only SKILL.md exists in the Skill directory. There is no attached test suite. The effect depends on whether the model first asks the three creation paths and whether it executes the official commands, rather than skipping the CLI and directly coding a project.

Summary¶

create-voltagent wraps VoltAgent’s official “how to start a new project” into a portable Skill: first ask for Automatic / Interactive / Manual, then follow npm create voltagent-app@latest or the 10-step manual process to use Hono/Elysia, provider, environment variables, and example Tool/Workflow. It does not teach you to design multi-Agent systems, but it can prevent programming assistants from bypassing the framework’s own scaffolding and using generic templates to create projects.

Official address:
https://github.com/voltagent/skills/tree/main/skills/create-voltagent

Framework documentation:
https://voltagent.dev/docs/

# create-voltagent: Initialize AI Agent Project in Accordance with VoltAgent Specification Using Official Skill