> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills

> Install VelaFi agent skills so Claude Code, Codex, Cursor and other AI coding assistants follow tested steps, rules and self-checks when they build a VelaFi integration.

Agent skills are packaged instructions that an AI coding assistant loads when you ask it to build something. The VelaFi skills tell the assistant which endpoints to call and in what order, which mistakes to avoid, and how to check the result, for each core use case. They complement the [docs MCP server](https://docs.velafi.com/docs/developer-tools/build-with-ai.md): the MCP server lets the assistant look things up, and the skills tell it how to build and verify the integration.

The skills are open source at [github.com/VelaFi-Tech/skills](https://github.com/VelaFi-Tech/skills) and follow the open [Agent Skills](https://agentskills.io) format.

> [!WARNING]
>
> `github.com/VelaFi-Tech/skills` is the only official source of VelaFi agent skills. Do not install VelaFi skills or plugins from any other repository, package or link, even if they use the VelaFi name.

## Install

> [tab] Claude Code CLI
>
> In a Claude Code session in your terminal, add the VelaFi marketplace and install the plugin:
>
> ```text theme={null}
> /plugin marketplace add VelaFi-Tech/skills
> /plugin install velafi-skills@velafi
> ```
>
> Or run the same steps from your shell:
>
> ```bash theme={null}
> claude plugin marketplace add VelaFi-Tech/skills
> claude plugin install velafi-skills@velafi
> ```
>
> The plugin also connects the VelaFi docs MCP server (`https://docs.velafi.com/mcp`). Update later with `/plugin marketplace update`.

> [tab] Claude desktop app
>
> These commands do not work in the desktop app: typing `/plugin` there only opens the plugin settings. Add the marketplace from the settings instead:
>
> 1. Open **Customize** and go to **Plugins**.
> 2. Click **Add**, choose **Add marketplace**, and select the GitHub repository option.
> 3. Enter `VelaFi-Tech/skills` and confirm.
> 4. Find **velafi-skills** in the VelaFi marketplace and install it.
>
> Menu names can differ slightly between app versions. If the option to add a marketplace is missing, install from the Claude Code CLI instead; plugins you install there are also available in the desktop app's Code tab.

> [tab] Codex
>
> Add the VelaFi marketplace to Codex and install the plugin:
>
> ```bash theme={null}
> codex plugin marketplace add VelaFi-Tech/skills
> codex plugin add velafi-skills@velafi
> ```
>
> The plugin installs all VelaFi skills and connects the VelaFi docs MCP server (`https://docs.velafi.com/mcp`). Update later with `codex plugin marketplace upgrade`.

> [tab] Other assistants
>
> For Cursor, Windsurf and other assistants supported by the [skills CLI](https://github.com/vercel-labs/skills), run:
>
> ```bash theme={null}
> npx skills add VelaFi-Tech/skills
> ```
>
> Update later with `npx skills update`. To connect the docs MCP server as well, see [Build with AI](https://docs.velafi.com/docs/developer-tools/build-with-ai.md).

## Available skills

| Skill | What it helps you build |
| - | - |
| `velafi-api-setup` | Credentials, token generation and refresh, error handling and `clientId` rules. Start here. Includes a token check script. |
| `velafi-webhooks` | Webhook registration, signature verification, the exact acknowledgement, and deduplication. Includes a local self-test for your webhook endpoint. |
| `velafi-collect-virtual-accounts` | [Collect local payments with virtual accounts](https://docs.velafi.com/docs/use-cases/collect-with-virtual-accounts.md). |
| `velafi-payouts-from-balance` | [Pay out local currency from your balance](https://docs.velafi.com/docs/use-cases/payouts-from-balance.md) and transfer between merchants. |
| `velafi-onramp` | [Convert local currency to stablecoins](https://docs.velafi.com/docs/use-cases/convert-to-stablecoins.md), prefunded or pay-per-order. |
| `velafi-offramp-payouts` | [Pay out local currency funded with stablecoins](https://docs.velafi.com/docs/use-cases/payouts-funded-by-stablecoins.md), including USD and EUR payouts. |
| `velafi-onboard-merchants` | [Onboard your customers as merchants](https://docs.velafi.com/docs/use-cases/onboard-your-customers.md) and activate their currency accounts. |
| `velafi-crypto-wallet` | Deposit addresses, the withdrawal whitelist, crypto withdrawals and transfers, and withdrawal monitoring. |
| `velafi-global-payments` | [Cross-border fiat-to-fiat payments](https://docs.velafi.com/docs/guides/global-payments.md). |
| `velafi-go-live-check` | A review of your integration before production: the [go-live checklist](https://docs.velafi.com/docs/use-cases/go-live-checklist.md), a step-by-step trace of each flow through your code, and, if you use the sandbox, an optional end-to-end run of each flow there. |

## Self-check scripts

Two skills include small Python scripts that the assistant can run for you:

* **Token check** (`velafi-api-setup`). Generates a token with your sandbox credentials from environment variables, to confirm the API key, signature and IP whitelist work. It calls only `GET /v2/token/generate`, refuses any host other than the sandbox unless you pass `--production`, and never prints your secret or the full token.
* **Webhook endpoint self-test** (`velafi-webhooks`). Sends signed test events to your own local webhook endpoint and checks that it verifies the signature, returns exactly `{"callbackStatus":"SUCCESS"}`, handles duplicates and responds quickly. It signs with its own test key, which you configure temporarily in your development environment, and it never contacts VelaFi. Webhooks are not sent in the sandbox, so this is how you test your handler before going live.

## Try it

After installing, ask your assistant, for example:

* "Integrate VelaFi so our customers in Mexico can pay us by SPEI, with one CLABE per customer."
* "Add a VelaFi webhook endpoint to this service and test it locally."
* "Pay out BRL by Pix from our USDT balance with VelaFi."
* "Run the VelaFi go-live check on this repository."

## Safety

* The skills contain no credentials. They tell the assistant to keep your API key and secret in environment variables or a secrets manager, never in code or logs, and to call VelaFi only from your server.
* The assistant works against the sandbox by default and must ask you before calling production or moving money.
* You stay in control of what gets built. Review the generated code and test it in the [sandbox](https://docs.velafi.com/docs/sandbox.md) before going live.

To report a problem with a skill, open an issue in the [GitHub repository](https://github.com/VelaFi-Tech/skills/issues). Issues are public, so never include API keys, secrets, tokens, merchant IDs or transaction details.


## Related topics

- [Build with AI](https://docs.velafi.com/docs/developer-tools/build-with-ai.md)
- [VelaFi API Docs](https://docs.velafi.com/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.