vn-skills

vn-skills

Teach your AI agent to work with VietQR, e-invoices, the new 34-province addresses and more — with one command.

Tiếng Việt · 5-minute quickstart

Coding agents (Claude Code, Codex, Cursor, …) get Vietnam-specific tasks wrong: they invent bank BINs, use the pre-2025 provinces and districts, misread amounts in words, or confuse the Chinese and Vietnamese lunar calendars. vn-skills fixes that with three layers built on one offline core:

What it is: an offline toolkit. No accounts or API keys; it builds, parses and validates VietQR payloads and images. What it is not: a payment gateway. It does not collect payments or confirm transfers, and never calls bank or NAPAS APIs; pair it with a payment gateway for that.

Skills

Bulk-convert stored addresses (one per line → NDJSON, or a CSV column; exit code 2 if some rows fail):

vn-skills address convert-file addresses.txt
vn-skills address convert-file customers.csv --csv --column address > converted.csv

Install the skills

Claude Code plugin (all skills + the MCP server, one command):

/plugin marketplace add beiryu/vn-skills
/plugin install vn-skills@vn-skills

Claude Code (project or user scope):

git clone https://github.com/beiryu/vn-skills
cp -r vn-skills/skills/vietqr ~/.claude/skills/          # or .claude/skills/ inside your project

Then ask: "tạo QR chuyển 500k vào VCB số tài khoản 0011001234567" → Claude runs the skill and returns qr.png.

Or use the CLI (skills are bundled in the package):

npx -y @vn-skills/cli install vietqr --agent claude            # .claude/skills/vietqr (project)
npx -y @vn-skills/cli install all --agent cursor --global      # ~/.cursor/skills/*

--agent is claude, cursor or codex. Existing folders are not overwritten without --force; --dry-run prints the actions only.

Cursor / Codex / other agents: copy the same folders into the agent's skills directory (.cursor/skills/, .codex/skills/, or wherever your agent discovers SKILL.md). The skills only need Node.js 22+ because they call npx -y @vn-skills/cli.

Inside this repository run node packages/cli/dist/index.js … instead of npx -y @vn-skills/cli … to get clean JSON. pnpm vn-skills … also works but adds wrapper output (the echoed command and [ELIFECYCLE] on failures).

MCP server

claude mcp add vn-skills -- npx -y @vn-skills/mcp

Setup for other clients is in MCP client setup. Or in any MCP client config:

{ "mcpServers": { "vn-skills": { "command": "npx", "args": ["-y", "@vn-skills/mcp"] } } }

The server exposes 28 tools, grouped by skill:

MCP client setup

Requires Node.js 22+. Each client has its own file and shape; check the linked docs for the exact location.

Claude Code:

claude mcp add vn-skills -- npx -y @vn-skills/mcp

Claude Desktop — claude_desktop_config.json:

{ "mcpServers": { "vn-skills": { "command": "npx", "args": ["-y", "@vn-skills/mcp"] } } }

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), same mcpServers shape:

{ "mcpServers": { "vn-skills": { "command": "npx", "args": ["-y", "@vn-skills/mcp"] } } }

VS Code — .vscode/mcp.json (top-level servers, not mcpServers):

{
  "servers": {
    "vn-skills": { "type": "stdio", "command": "npx", "args": ["-y", "@vn-skills/mcp"] }
  }
}

Codex — ~/.codex/config.toml:

[mcp_servers.vn-skills]
command = "npx"
args = ["-y", "@vn-skills/mcp"]

Other clients: use the generic mcpServers block above.

Library

import {
  buildVietQR,
  convertAddress,
  validateTaxId,
  moneyToWords,
  lunarInfo,
  computeTotals,
} from '@vn-skills/core';

buildVietQR({ bank: 'VCB', account: '0011001234567', amount: 500000, note: 'don 123' }).payload;
convertAddress('12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM').new.formatted; // "12 Nguyễn Huệ, Phường Sài Gòn, Thành phố Hồ Chí Minh"
validateTaxId('0100233488-001').kind; // "branch"
moneyToWords(1_200_000).words; // "một triệu hai trăm nghìn đồng"
lunarInfo(29, 1, 2025).text; // "Mùng 1 tháng Giêng năm Ất Tỵ"

Every function returns { ok: true, ... } or { ok: false, error: { code, message, hint } } — no exceptions for bad input.

Development

pnpm install && pnpm build && pnpm test
pnpm build-data          # refresh bundled datasets from pinned upstream commits (network)

Data sources, licenses and dates are listed in packages/core/data/SOURCES.md. See CONTRIBUTING.md.

Roadmap

Next up: a Python port and real e-invoice sandbox adapters. Full list with acceptance criteria: ROADMAP.md.

Community

Contributing · Governance · Code of Conduct · Security · Name & brand policy · Sponsor

Disclaimer

This project provides technical tooling only. It is not tax, legal or accounting advice, does not query or scrape any government system, and does not guarantee that a tax ID is registered or that an address is accepted by a carrier. Verify with the competent authority where it matters.

VietQR and NAPAS are trademarks of the National Payment Corporation of Vietnam (NAPAS); bank names belong to their owners. vn-skills is not affiliated with, endorsed by or certified by NAPAS, any bank or any Vietnamese authority.

License

MIT. Bundled data is derived from MIT-licensed community datasets (see SOURCES.md and their licences in THIRD_PARTY_NOTICES.md); the lunar calendar is an independent implementation of the formulas in Jean Meeus, Astronomical Algorithms.