> ## 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

> 安装 VelaFi Agent Skills，让 Claude Code、Codex、Cursor 等 AI 编程助手在构建 VelaFi 集成时遵循经过验证的步骤、规则和自检。

Agent Skills（智能体技能）是打包好的指令，AI 编程助手在您让它构建某项功能时会加载这些指令。针对每个核心使用场景，VelaFi Skills 会告诉助手按什么顺序调用哪些接口、需要避免哪些错误，以及如何检查结果。它们与 [文档 MCP 服务器](https://docs.velafi.com/cn/docs/developer-tools/build-with-ai.md) 互为补充：MCP 服务器让助手查阅文档，Skills 则告诉助手如何构建和验证集成。

这些 Skills 在 [github.com/VelaFi-Tech/skills](https://github.com/VelaFi-Tech/skills) 开源，遵循开放的 [Agent Skills](https://agentskills.io) 格式。

> [!WARNING]
>
> `github.com/VelaFi-Tech/skills` 是 VelaFi Agent Skills 唯一的官方来源。请勿从任何其他代码仓库、软件包或链接安装 VelaFi Skills 或插件，即使它们使用了 VelaFi 的名称。

## 安装

> [tab] Claude Code CLI
>
> 在终端中的 Claude Code 会话里，添加 VelaFi 插件市场并安装插件：
>
> ```text theme={null}
> /plugin marketplace add VelaFi-Tech/skills
> /plugin install velafi-skills@velafi
> ```
>
> 也可以在 shell 中执行相同的步骤：
>
> ```bash theme={null}
> claude plugin marketplace add VelaFi-Tech/skills
> claude plugin install velafi-skills@velafi
> ```
>
> 该插件还会连接 VelaFi 文档 MCP 服务器（`https://docs.velafi.com/mcp`）。之后可通过 `/plugin marketplace update` 更新。

> [tab] Claude 桌面应用
>
> 这些命令在桌面应用中无效：在桌面应用中输入 `/plugin` 只会打开插件设置。请改为在设置中添加插件市场：
>
> 1. 打开 **Customize**（自定义），进入 **Plugins**（插件）。
> 2. 点击 **Add**（添加），选择 **Add marketplace**（添加插件市场），然后选择 GitHub 代码仓库选项。
> 3. 输入 `VelaFi-Tech/skills` 并确认。
> 4. 在 VelaFi 插件市场中找到 **velafi-skills** 并安装。
>
> 不同版本的应用菜单名称可能略有不同。如果找不到添加插件市场的选项，请改用 Claude Code CLI 安装；在 CLI 中安装的插件同样可以在桌面应用的 Code 标签页中使用。

> [tab] Codex
>
> 在 Codex 中添加 VelaFi 插件市场并安装插件：
>
> ```bash theme={null}
> codex plugin marketplace add VelaFi-Tech/skills
> codex plugin add velafi-skills@velafi
> ```
>
> 该插件会安装所有 VelaFi Skills，并连接 VelaFi 文档 MCP 服务器（`https://docs.velafi.com/mcp`）。之后可通过 `codex plugin marketplace upgrade` 更新。

> [tab] 其他助手
>
> 对于 Cursor、Windsurf 以及 [skills CLI](https://github.com/vercel-labs/skills) 支持的其他助手，运行：
>
> ```bash theme={null}
> npx skills add VelaFi-Tech/skills
> ```
>
> 之后可通过 `npx skills update` 更新。如需同时连接文档 MCP 服务器，请参阅[使用 AI 开发](https://docs.velafi.com/cn/docs/developer-tools/build-with-ai.md)。

## 可用的 Skills

| Skill | 帮助您构建的内容 |
| - | - |
| `velafi-api-setup` | 凭证、令牌生成与刷新、错误处理以及 `clientId` 规则。请从这里开始。包含令牌检查脚本。 |
| `velafi-webhooks` | Webhook 注册、签名验证、准确的确认响应以及去重。包含针对您 Webhook 端点的本地自检。 |
| `velafi-collect-virtual-accounts` | [通过虚拟账户收取本地付款](https://docs.velafi.com/cn/docs/use-cases/collect-with-virtual-accounts.md)。 |
| `velafi-payouts-from-balance` | [从余额支付本地货币](https://docs.velafi.com/cn/docs/use-cases/payouts-from-balance.md)，以及商户之间的划转。 |
| `velafi-onramp` | [将本地货币兑换为稳定币](https://docs.velafi.com/cn/docs/use-cases/convert-to-stablecoins.md)，支持预先注资或按单付款。 |
| `velafi-offramp-payouts` | [以稳定币注资支付本地货币](https://docs.velafi.com/cn/docs/use-cases/payouts-funded-by-stablecoins.md)，包括 USD 和 EUR 付款。 |
| `velafi-onboard-merchants` | [将您的客户接入为商户](https://docs.velafi.com/cn/docs/use-cases/onboard-your-customers.md)并开通其币种账户。 |
| `velafi-crypto-wallet` | 充值地址、提现白名单、加密货币提现与划转，以及提现监控。 |
| `velafi-global-payments` | [跨境法币兑法币支付](https://docs.velafi.com/cn/docs/guides/global-payments.md)。 |
| `velafi-go-live-check` | 上线前审查您的集成：对照[上线检查清单](https://docs.velafi.com/cn/docs/use-cases/go-live-checklist.md)，在代码中逐步追踪每个流程；如果您使用沙盒，还可以选择在沙盒中端到端运行每个流程。 |

## 自检脚本

有两个 Skill 包含小型 Python 脚本，助手可以替您运行：

* **令牌检查**（`velafi-api-setup`）。使用环境变量中的沙盒凭证生成令牌，确认 API key、签名和 IP 白名单均配置正确。它只调用 `GET /v2/token/generate`；除非传入 `--production`，否则拒绝沙盒以外的任何主机；并且绝不会打印您的 secret 或完整令牌。
* **Webhook 端点自检**（`velafi-webhooks`）。向您自己的本地 Webhook 端点发送已签名的测试事件，检查它是否验证签名、是否准确返回 `{"callbackStatus":"SUCCESS"}`、是否正确处理重复事件以及是否快速响应。它使用自己的测试密钥签名（您需要在开发环境中临时配置该密钥），且从不连接 VelaFi。沙盒环境不会发送 Webhook，因此上线前可以用它测试您的处理程序。

## 试一试

安装后，可以向助手提出例如：

* “集成 VelaFi，让我们在墨西哥的客户通过 SPEI 付款，每个客户一个 CLABE。”
* “为这个服务添加 VelaFi Webhook 端点，并在本地测试。”
* “通过 VelaFi，用我们的 USDT 余额以 Pix 支付 BRL。”
* “对这个代码仓库运行 VelaFi 上线检查。”

## 安全

* Skills 中不包含任何凭证。它们要求助手将您的 API key 和 secret 保存在环境变量或密钥管理服务中，绝不写入代码或日志，并且只从您的服务器调用 VelaFi。
* 助手默认使用沙盒环境，在调用生产环境或转移资金之前必须征得您的同意。
* 构建什么始终由您掌控。上线前请检查生成的代码，并在[沙盒环境](https://docs.velafi.com/cn/docs/sandbox.md)中测试。

如需报告 Skill 的问题，请在 [GitHub 仓库](https://github.com/VelaFi-Tech/skills/issues)中提交 issue。Issue 是公开的，请勿包含 API key、secret、令牌、商户 ID 或交易详情。


## Related topics

- [使用 AI 开发](https://docs.velafi.com/cn/docs/developer-tools/build-with-ai.md)
- [VelaFi API 文档](https://docs.velafi.com/cn/index.md)


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