Agent skill

create-voltagent

Skill for creating AI agent projects using the VoltAgent framework. Guide for CLI setup and manual bootstrapping.

View SKILL.md on GitHub Repository

Stars 9

Forks 1

Install this agent skill to your Project

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

Metadata

Additional technical details for this skill

author: VoltAgent
version: 1.0.0
repository: https://github.com/VoltAgent/skills

SKILL.md

Create VoltAgent Skill

Complete guide for creating new VoltAgent projects. Includes the CLI flow and a full manual setup.

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

Start Here

When a user wants to create a VoltAgent project, ask:

"How would you like to create your VoltAgent project?"

Automatic Setup - run npm create voltagent-app@latest and handle prompts
Interactive Guide - walk through each step and confirm choices
Manual Installation - set up dependencies and a full working example

Based on their choice:

Option 1: run the CLI, capture server and provider choices, and finish setup
Option 2: gather server, provider, and API key, then run the CLI
Option 3: follow the manual steps below

Before You Start

Node.js 20+ (>= 20.19.0 recommended)
Git (optional, for auto git init)
An API key for your model provider (not needed for Ollama)

Fast Path

Create a new VoltAgent project with one command:

bash

npm create voltagent-app@latest

Other package managers:

bash

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

CLI Flow

The create-voltagent-app command:

Asks for a project name (default: my-voltagent-app)
Prompts for a server framework (Hono or Elysia)
Prompts for an AI provider (OpenAI, Anthropic, Google, Groq, Mistral, Ollama)
Prompts for an API key when required
Installs dependencies and scaffolds the project
Writes .env, README.md, tsconfig.json, tsdown.config.ts, and Docker files
Initializes a git repo when available

CLI Walkthrough

Run:
bash
```
npm create voltagent-app@latest
```
When prompted:
- Choose a server (Hono recommended or Elysia)
- Choose an AI provider
- Enter your API key (skip if using Ollama)

Start the dev server:

bash

cd <your-project-directory>
npm run dev

If you chose Ollama:
bash
```
ollama pull llama3.2
```

CLI Flags and Examples

Create in a specific directory:

bash

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

Download an example from the VoltAgent repo:

bash

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

pnpm / yarn / bun equivalents:

bash

pnpm create voltagent-app@latest -- --example with-workflow
yarn create voltagent-app@latest -- --example with-workflow
bun create voltagent-app@latest -- --example with-workflow

Notes:

Examples are pulled from https://github.com/voltagent/voltagent/tree/main/examples
Some package managers require -- before --example.
After an example download, run npm install and npm run dev.

Generated Layout

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

If you run the docs sync script in this repo, you may also see packages/core/docs generated.

Env Keys

The CLI writes .env with your provider key (or a placeholder). Common keys:

env

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=...

Manual Setup (Full)

If you prefer not to use the CLI, follow these steps:

Step 1: Create the project directory

bash

mkdir my-voltagent-app && cd my-voltagent-app
npm init -y
mkdir -p src/tools src/workflows .voltagent

Step 2: Install dependencies

Choose one server package:

bash

npm install @voltagent/core @voltagent/libsql @voltagent/logger @voltagent/server-hono @voltagent/cli ai zod dotenv

bash

npm install @voltagent/core @voltagent/libsql @voltagent/logger @voltagent/server-elysia @voltagent/cli ai zod dotenv

Dev dependencies:

bash

npm install -D typescript tsx tsdown @types/node @biomejs/biome

Step 3: Add scripts to package.json

json

{
  "scripts": {
    "dev": "tsx watch --env-file=.env ./src",
    "build": "tsdown",
    "start": "node dist/index.js",
    "lint": "biome check ./src",
    "lint:fix": "biome check --write ./src",
    "typecheck": "tsc --noEmit",
    "volt": "volt"
  }
}

volt is the VoltAgent CLI. Use it for project utilities (for example init, deploy, eval, prompts, tunnel, update).

Step 4: Configure TypeScript

Create tsconfig.json:

json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "outDir": "dist",
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Step 5: Add tsdown config

Create tsdown.config.ts:

typescript

import { defineConfig } from "tsdown";

export default defineConfig({
  entry: ["./src/index.ts"],
  sourcemap: true,
  outDir: "dist",
});

Step 6: Create .env

env

OPENAI_API_KEY=your-api-key-here
VOLTAGENT_PUBLIC_KEY=your-public-key
VOLTAGENT_SECRET_KEY=your-secret-key
NODE_ENV=development

For Ollama:

env

OLLAMA_HOST=http://localhost:11434

Step 7: Create a tool

Create src/tools/weather.ts:

typescript

import { createTool } from "@voltagent/core";
import { z } from "zod";

export const weatherTool = createTool({
  name: "getWeather",
  description: "Get the current weather for a specific location",
  parameters: z.object({
    location: z.string().describe("City or location to get weather for"),
  }),
  execute: async ({ location }) => {
    return {
      weather: {
        location,
        temperature: 21,
        condition: "Sunny",
        humidity: 45,
        windSpeed: 8,
      },
      message: `Current weather in ${location}: 21 C and sunny.`,
    };
  },
});

Create src/tools/index.ts:

typescript

export { weatherTool } from "./weather";

Step 8: Create a workflow

Create src/workflows/index.ts:

typescript

import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

export const expenseApprovalWorkflow = createWorkflowChain({
  id: "expense-approval",
  name: "Expense Approval Workflow",
  purpose: "Process expense reports with manager approval for high amounts",
  input: z.object({
    employeeId: z.string(),
    amount: z.number(),
    category: z.string(),
    description: z.string(),
  }),
  result: z.object({
    status: z.enum(["approved", "rejected"]),
    approvedBy: z.string(),
    finalAmount: z.number(),
  }),
})
  .andThen({
    id: "check-approval-needed",
    resumeSchema: z.object({
      approved: z.boolean(),
      managerId: z.string(),
      comments: z.string().optional(),
      adjustedAmount: z.number().optional(),
    }),
    execute: async ({ data, suspend, resumeData }) => {
      if (resumeData) {
        return {
          ...data,
          approved: resumeData.approved,
          approvedBy: resumeData.managerId,
          finalAmount: resumeData.adjustedAmount || data.amount,
          managerComments: resumeData.comments,
        };
      }

      if (data.amount > 500) {
        await suspend("Manager approval required", {
          employeeId: data.employeeId,
          requestedAmount: data.amount,
          category: data.category,
        });
      }

      return {
        ...data,
        approved: true,
        approvedBy: "system",
        finalAmount: data.amount,
      };
    },
  })
  .andThen({
    id: "process-decision",
    execute: async ({ data }) => {
      return {
        status: data.approved ? "approved" : "rejected",
        approvedBy: data.approvedBy,
        finalAmount: data.finalAmount,
      };
    },
  });

Step 9: Create the entry point

Create src/index.ts:

typescript

import "dotenv/config";
import {
  Agent,
  Memory,
  VoltAgent,
  VoltAgentObservability,
  VoltOpsClient,
} from "@voltagent/core";
import { LibSQLMemoryAdapter, LibSQLObservabilityAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
import { expenseApprovalWorkflow } from "./workflows";
import { weatherTool } from "./tools";

const logger = createPinoLogger({ name: "my-voltagent-app", level: "info" });

const memory = new Memory({
  storage: new LibSQLMemoryAdapter({
    url: "file:./.voltagent/memory.db",
    logger: logger.child({ component: "libsql" }),
  }),
});

const observability = new VoltAgentObservability({
  storage: new LibSQLObservabilityAdapter({
    url: "file:./.voltagent/observability.db",
  }),
});

const agent = new Agent({
  name: "my-voltagent-app",
  instructions: "A helpful assistant that can check weather and help with various tasks",
  model: "openai/gpt-4o-mini",
  tools: [weatherTool],
  memory,
});

new VoltAgent({
  agents: { agent },
  workflows: { expenseApprovalWorkflow },
  server: honoServer(),
  logger,
  observability,
  voltOpsClient: new VoltOpsClient({
    publicKey: process.env.VOLTAGENT_PUBLIC_KEY || "",
    secretKey: process.env.VOLTAGENT_SECRET_KEY || "",
  }),
});

Model format is provider/model. Examples:

openai/gpt-4o-mini
anthropic/claude-3-5-sonnet
google/gemini-2.0-flash
groq/llama-3.3-70b-versatile
mistral/mistral-large-latest
ollama/llama3.2

If you chose Elysia, replace honoServer with elysiaServer and update the import.

Step 10: Run the dev server

bash

npm run dev

Maintainer

VoltAgent Core maintainer

Source details

Full Name: VoltAgent/skills
Branch: main
Path in repo: skills/create-voltagent
License: MIT License

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

VoltAgent/skills

voltagent-docs-bundle

Look up VoltAgent documentation embedded in node_modules/@voltagent/core/docs for version-matched docs. Use for API signatures, guides, and examples.

9 1

Explore

VoltAgent/skills

voltagent-core-reference

9 1

Explore

VoltAgent/skills

voltagent-best-practices

VoltAgent architectural patterns and conventions. Covers agents vs workflows, project layout, memory, servers, and observability.

9 1

Explore

mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758

Explore

mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758

Explore

mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

Metadata

SKILL.md

Create VoltAgent Skill

Start Here

Before You Start

Fast Path

CLI Flow

CLI Walkthrough

CLI Flags and Examples

Generated Layout

Env Keys

Manual Setup (Full)

Step 1: Create the project directory

Step 2: Install dependencies

Step 3: Add scripts to package.json

Step 4: Configure TypeScript

Step 5: Add tsdown config

Step 6: Create .env

Step 7: Create a tool

Step 8: Create a workflow

Step 9: Create the entry point

Step 10: Run the dev server

Recommended Agent Skills

voltagent-docs-bundle

voltagent-core-reference

voltagent-best-practices

setup-pre-commit

handoff

edit-article