Agent skills

These pages are for people. Agent skills are the same ground written for a coding agent that is already at work in the vpay repository, or in a merchant codebase that talks to vpay. They live in their own repository, vaam-apps/vpay-skills, and install with one command:

bash

npx skills add https://github.com/vaam-apps/vpay-skills --skill vpay

vpay is the orientation skill. Start there, and it routes to the others. A merchant integrating the Node SDK needs only vpay-merchant-api and vpay-webhooks. It doesn't need the whole vpay tree.

Three audiences, three tiers

A human reading this site and an agent loading a skill need different things from the same facts. vpay keeps both, plus its own exhaustive record, and gates the drift between them.

flowchart LR
  code["vpay code<br/>at a release tag"]
  record["vpay docs/<br/>flows · status · ADRs<br/><i>the source of truth</i>"]
  human["vpay-docs<br/><b>this site</b><br/>for people deciding<br/>what to do"]
  skills["vpay-skills<br/>for agents already<br/>doing it"]
  code -- "Status sections<br/>machine-checked" --> record
  record -- "verify-parity<br/>(on every release)" --> human
  record -- "verify-coverage<br/>(daily, vs master)" --> skills
  human -. "every page links<br/>its skills" .-> skills

	vpay `docs/`	This site	vpay-skills
Written for	a contributor who needs every detail	a person evaluating, integrating or operating vpay	an agent making a change now
Judged on	is it complete and dated?	is it clear, and true of the release?	would an agent that read only this get it right first time?
Pinned to	the commit it lives in	a vpay release tag, in `vpay.lock.json`	a vpay commit, stamped in every `SKILL.md`
Drift caught by	vpay's own fifteen gates	`verify-parity`, on every vpay release	`verify-coverage`, daily against vpay's `master`

The parity rule

vpay's own rule is that a feature lands in three places or it has not landed: the code, the docs and the skills. Its reason is the one this site inherits. A status page that lags is worse than none, because people trust it. A skill that lags is worse still. An agent doesn't just trust it. It acts on it, fast, in every session that loads it.

So every page on this site names its skills in its frontmatter, and the theme prints them at the bottom with an install command. The parity check on this site fails when a page names a skill that doesn't exist, or when vpay-skills adds a skill that no page here references. When a skill is added, a page here has to acknowledge it.

Every skill

The table is generated when the site is built. It reads each SKILL.md from vpay-skills at the pinned commit and compares the skill's own verified-against stamp with the vpay release these pages document.

Skill	What it briefs an agent on	Verified against
`vpay`	Orientation for working in the vpay repository — a Rust + TypeScript payment orchestrator for Cameroon mobile money rails (MTN MoMo, Orange Money). Load this before any task in …	`67c90ea5` (2026-09-20) older than v0.4.1
`vpay-checkout`	The payer-facing checkout page at frontends/apps/checkout — the three surfaces (hosted, embedded, popup) and how a payer reaches each, why the client_secret rides in the URL …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-conventions`	How to write Rust and TypeScript in vpay — the two machine-enforced rules, ADR-0016's six engineering standards and precisely which three a gate checks, the thiserror/Classify …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-customers`	The vpay Customer object and the account-holder lookup — phone-first identity, the at-least-one-identifier rule, the address object whose GPS half is two integer microdegree …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-dashboard`	The staff operator console at frontends/apps/dashboard — it is the OAuth client and runs the code leg in its own process, the /dash/v1 read seam over two transports, the BFF that …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-data-layer`	vpay's persistence layer — `backends/migrations/*.sql` as the authoritative schema and the rule that a shipped migration is never edited, the CrateStack `.cstack` file that …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-docs-status`	How to finish a change in vpay — which status page takes your row, how to update a flow doc's Status section, when to write an ADR versus a reference page, the NotImplemented …	`67c90ea5` (2026-09-20) older than v0.4.1
`vpay-frontend`	The vpay pnpm workspace under frontends/ — the seven packages and what each really is, the Tailwind v4 + daisyUI 5 setup whose three load-bearing lines all fail silently, the …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-invoices`	vpay's Invoice and invoice-line objects — the nineteen-key wire shape, the draft/open/paid/void/uncollectible state machine that is enforced by compare-and-swap UPDATE statements …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-merchant-api`	The vpay HTTP surface — the /v1 merchant API, its route tables, OAuth2 private_key_jwt auth (there are no API keys), the mandatory Idempotency-Key, the Stripe-shaped error …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-mtn-momo`	The MTN MoMo Cameroon adapter (`vpay-adapter-mtn-momo`) — a push rail, and the only rail vpay has ever called for real. Covers the Collections token mint and the JSON-grant-body …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-ops`	Configuration, deployment and observability for vpay — the YAML layering and its boot-time refusals, the exit-code contract, ProviderHost and credential redaction, the single …	`35848b5c` (2026-09-19) older than v0.4.1
`vpay-orange-money`	The Orange Money Cameroun adapter (`vpay-adapter-orange-money`) — the Web Payment redirect rail, and the loudest caveat in the repository: it has never been called. Covers the …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-payments`	vpay's payment domain model — the PaymentIntent lifecycle (which has no failed status), the charge, refund and invoice state machines, the one-charge-per-intent rule, the refund …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-provider-adapters`	The vpay provider port (`vpay-provider`) and how to add a payment rail — the `ProviderAdapter` trait and its seven methods, the `Unsupported` vs `NotImplemented` rule that decides …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-reconciler`	The vpay worker — the job loop, the poll and delivery ladders, lease reaping, crash recovery, SIGTERM draining, and the worker-concurrency bound. Load this when changing anything …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-sdks`	The six packages under sdks/ and the parity rule that binds the two merchant SDKs — add a capability to one and you add it to all, or you write a dated gap row. Covers what each …	`999a23f9` (2026-09-22) newer than v0.4.1
`vpay-tooling`	How to build, test, lint and gate vpay — the just recipes that matter, the fifteen verify gates and how contributors trip each one, what just ci actually runs, the toolchain pins …	`67c90ea5` (2026-09-20) older than v0.4.1
`vpay-troubleshooting`	A symptom index for vpay — the exact error text or observed behaviour, its real cause, and the fix. Covers clippy and toolchain failures, rootless Docker and testcontainers …	`0799a8d2` (2026-09-18) older than v0.4.1
`vpay-webhooks`	vpay's outbound webhooks — the fifteen-type event vocabulary closed by a database CHECK, which two types nothing ever emits, the two refund types that started being emitted on …	`0799a8d2` (2026-09-18) older than v0.4.1

A skill is true of a vpay, not of vpay

A skill marked newer than the release was verified against a vpay commit that came after it. It may describe something this release doesn't have. The reverse holds too: a skill marked older than the release was verified before the release's latest changes. Read the skill's own stamp before trusting a claim that depends on the version, and when the two disagree, trust the repository. vpay-skills' VERSIONING.md is the full rule.

By task

flowchart TD
  start(["What is the agent about to do?"])
  start --> any["Anything in the repo"] --> vpay[vpay]
  start --> write["Write Rust or TypeScript"] --> conv[vpay-conventions]
  start --> run["Run a build, a gate, CI"] --> tool[vpay-tooling]
  start --> broke["Something broke oddly"] --> trouble[vpay-troubleshooting]
  start --> finish["Finish a change"] --> docs[vpay-docs-status]
  start --> money["Touch payments"]
  money --> pay[vpay-payments]
  money --> rec[vpay-reconciler]
  start --> wire["Touch the merchant wire"]
  wire --> api[vpay-merchant-api]
  wire --> hooks[vpay-webhooks]
  wire --> cust[vpay-customers]
  wire --> inv[vpay-invoices]
  start --> rail["Touch a rail"]
  rail --> port[vpay-provider-adapters]
  rail --> mtn[vpay-mtn-momo]
  rail --> om[vpay-orange-money]
  start --> ui["Touch a screen"]
  ui --> fe[vpay-frontend]
  ui --> co[vpay-checkout]
  ui --> dash[vpay-dashboard]
  start --> data["Touch the schema"] --> dl[vpay-data-layer]
  start --> sdk["Touch an SDK"] --> sdks[vpay-sdks]
  start --> ops["Configure or deploy"] --> opsn[vpay-ops]

Installing more than one

bash

npx skills add https://github.com/vaam-apps/vpay-skills --skill vpay
npx skills add https://github.com/vaam-apps/vpay-skills --skill vpay-merchant-api
npx skills add https://github.com/vaam-apps/vpay-skills --skill vpay-webhooks

npx skills add fetches one directory into .agents/skills/ and pins its hash in skills-lock.json. vpay itself uses the same mechanism for the skills it consumes, skills-lock.json.

Go deeper

vaam-apps/vpay-skills: the skills, coverage.json and the verify-coverage gate
AGENTS.md § Docs↔skills parity: vpay's statement of the three-places rule
How these docs stay current: this site's side of it

Agent skills ​

Three audiences, three tiers ​

The parity rule ​

Every skill ​

By task ​

Installing more than one ​