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.
fixes that with three layers built on one offline core:
@vn-skills/cli — npx -y @vn-skills/cli … (JSON output for agents)
nothing; the skills call it
MCP server
@vn-skills/mcp — the same functions as MCP tools
claude mcp add vn-skills -- npx -y @vn-skills/mcp
Library
@vn-skills/core — pure TypeScript, no network, data bundled
npm i @vn-skills/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.
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, codex, agents or copilot (.github/skills/, or ~/.copilot/skills/ with --global). 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. .agents/skills/ is read by Codex (docs), Cursor (docs), Gemini CLI (docs) and GitHub Copilot in VS Code, Copilot CLI and the cloud agent (docs); install there with --agent agents. For the Copilot cloud agent, install in project scope (--agent agents without --global), because the cloud agent does not load personal skills.
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:
MCP Apps hosts (Claude, ChatGPT, VS Code, …) show VietQR results (built with image: true) as an inline VietQR card with bank, account, amount and copy buttons; other clients see the usual JSON and image.
When a client declares the MCP elicitation capability, the address converter asks the user to pick the new ward if the old ward was split, and reports chosenBy (user or default).
Prompts
The server also offers prompt templates, shown as / commands in clients that support MCP prompts: tao-vietqr, doi-dia-chi-moi, kiem-tra-mst, doc-cccd, so-tien-bang-chu, ngay-lam-viec, doi-am-duong, kiem-tra-hoa-don.
Resources
Read-only data that clients can attach without a tool call (all application/json):
MCP client setup
Requires Node.js 22+. Each client has its own file and shape; check the linked docs for the exact location.
It binds to 127.0.0.1 by default; use --host 0.0.0.0 to expose it (e.g. docker run -p 3000:3000 vn-skills-mcp --http --host 0.0.0.0). Requests with a non-localhost Origin header get 403 unless you pass --allow-origin <origin> (repeatable). Without --http the server uses stdio.
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.
Google Sheets
packages/sheets (private, not on npm) builds Apps Script custom functions from @vn-skills/core:
pnpm --filter ./packages/sheets build writes packages/sheets/dist/vn-skills.gs, vn-skills-lite.gs and appsscript.json.
In a Google Sheet open Extensions → Apps Script and paste the contents of one .gs file.
Set the time zone to Asia/Ho_Chi_Minh (Project Settings, or use the timeZone in appsscript.json).
Save and use the functions in cells. Each accepts one value or a range and returns the same shape; a bad cell returns the error text.
Function
Example
VN_TIEN_CHU(amount, [thousand])
=VN_TIEN_CHU(A2), =VN_TIEN_CHU(A2:A9, "ngàn")
VN_SO_THANH_CHU(number)
=VN_SO_THANH_CHU(A2)
VN_MST(taxId)
=VN_MST(A2:A9) → TRUE/FALSE
VN_AM_LICH(date)
=VN_AM_LICH(A2) or =VN_AM_LICH("29/01/2025")
VN_NGAY_LAM_VIEC(date)
=VN_NGAY_LAM_VIEC(A2) → TRUE/FALSE
VN_CONG_NGAY_LAM_VIEC(date, n)
=VN_CONG_NGAY_LAM_VIEC(A2, 5) (yyyy-mm-dd text)
VN_DIA_CHI_MOI(address)
=VN_DIA_CHI_MOI(A2) (full bundle only)
Bundle sizes (as measured by the build): vn-skills.gs ≈ 2520 KiB (includes the address data), vn-skills-lite.gs ≈ 39 KiB (no address functions). If the full bundle is too large for your project, use the lite bundle.
Development
pnpm install && pnpm build && pnpm test
pnpm build-data # refresh bundled datasets from pinned upstream commits (network)
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.