Set up your AI agent

Install the Voltage Agent Skill Pack to give your coding agent Voltage API guidance, payment workflows, and CLI instructions. The pack currently includes one skill: voltage-api.

You can plan an integration and write code before connecting a Voltage account.

Prerequisites

• A supported coding agent, such as Claude Code, Codex, Hermes Agent, OpenCode, Cursor, or Gemini CLI.
• Node.js 22.20 or later, with npm and npx available in your terminal.
• Access to GitHub to download the pack.

Check your local tools:

node --version
npm --version

Confirm that Node.js meets the minimum version before continuing. The skills installer documents its current requirements and supported agents.

One-command install for most agent harnesses

Run this in your terminal:

npx skills add voltagecloud/agent-skills --global --skill voltage-api --yes

This installs voltage-api globally for detected supported agents. Global installation makes it available across projects. The command installs skill files; it does not install agent applications, install the Voltage CLI, or connect your account.

To choose agents interactively, omit --yes. To install into the current project instead, omit --global.

If your agent is not detected, run only its command below. See the supported-agent list for other harnesses and installation paths.

Claude Code

npx skills add voltagecloud/agent-skills --global --skill voltage-api --agent claude-code --yes

Codex

npx skills add voltagecloud/agent-skills --global --skill voltage-api --agent codex --yes

Hermes Agent

npx skills add voltagecloud/agent-skills --global --skill voltage-api --agent hermes-agent --yes

OpenCode

npx skills add voltagecloud/agent-skills --global --skill voltage-api --agent opencode --yes

Cursor

npx skills add voltagecloud/agent-skills --global --skill voltage-api --agent cursor --yes

Gemini CLI

npx skills add voltagecloud/agent-skills --global --skill voltage-api --agent gemini-cli --yes

Verify the installation

List globally installed skills:

npx skills list --global

Look for voltage-api in the output and confirm that your agent appears among its targets. For a project install, run npx skills list from that project instead.

Close your current agent session and open a new one so it can discover the installed skill. Then ask:

Use the voltage-api skill. Describe what it covers and which reference you would use for API request schemas.

The agent should identify Voltage payment and wallet guidance, with the published OpenAPI contract as the authoritative API source. If it cannot find voltage-api, follow the troubleshooting steps below.

Ask your agent to get started

Start with a concrete result:

Use the voltage-api skill to help me build an application that accepts Lightning payments. Start with the integration plan and code. Explain what I need to configure in Voltage before testing.

Other useful tasks:

• “Use voltage-api to add hosted checkout to this application.”
• “Use voltage-api to build a webhook receiver that verifies signatures and reconciles payment state.”
• “Explain which parts of this integration apply to my credit-backed or node-backed wallet.”

Connect a development wallet

For API calls, you need a Voltage organization, environment, wallet, and credentials with the required access. Use the Wallet Setup Guide if you need a development wallet.

Use the Voltage CLI

Follow the CLI installation and sign-in guide, or ask your agent:

Use voltage-api to help me install the Voltage CLI and configure a profile for my development environment. I will complete browser login myself.

The CLI stores profiles separately from the skill’s request-helper configuration. Its credentials normally use your operating system’s credential store. Follow the CLI guide for API-key automation or headless setups.

Use the direct-request helper

If you use the pack’s optional Python request helper, it requires Python 3.9+ and curl. Create its local configuration file with private permissions:

mkdir -p ~/.voltage
chmod 700 ~/.voltage
(umask 077; touch ~/.voltage/.env)
chmod 600 ~/.voltage/.env

Create an environment API key using the Developer Guide. Edit the file locally, preserve any existing values, and replace these placeholders:

VOLTAGE_API_KEY=<environment-api-key>
VOLTAGE_ORGANIZATION_ID=<organization-uuid>
VOLTAGE_ENVIRONMENT_ID=<environment-uuid>
VOLTAGE_WALLET_ID=<development-wallet-uuid>

The wallet ID is an optional default. The CLI does not read this file. Process environment values override the helper file; see the pack’s configuration guide when switching environments.

Keep API keys out of prompts, screenshots, source control, and browser code.

Check the connection

Start with a read-only task:

Use voltage-api to check my configured development wallet’s network and available balance. Do not print credentials.

Confirm that the wallet belongs to the intended environment and uses Mutinynet before testing Lightning payments. See Staging Environment for wallet choices. When ready, follow the CLI test-invoice example.

A generated invoice does not mean it has been paid. Pay it from another compatible test wallet and check the final payment status.

Keep the pack up to date

Update the globally installed skill:

npx skills update voltage-api --global

For a project install, use npx skills update voltage-api --project from that project. After updating, open a new agent session and repeat the installation check.

Troubleshooting

• npx is unavailable or reports an unsupported Node.js version: Install Node.js 22.20 or later, reopen your terminal, and check both version commands again.
• The skill is missing from the installer list: Check global versus project scope. Rerun the matching install command.
• The installer lists the skill, but your agent cannot find it: Rerun installation with the explicit --agent value, then restart the agent session.
• The agent finds the skill but cannot access your wallet: Check the intended organization, environment, and credential permissions locally. Verify which connection method you configured; CLI profiles and the helper file are separate.

For installer options, see the installer command reference. Find skill sources and examples in the Voltage Agent Skill Pack repository.