Agent skills for SolvaPay, on both sides of a payment: adding SolvaPay to a project (paid MCP servers, and app integration with hosted checkout, paywalls, usage, webhooks and billing UI), and paying through SolvaPay when an agent meets a SolvaPay paywall.
| Skill id | Purpose |
|---|---|
solvapay |
Router — disambiguates vague intent and points at the right surface skill |
solvapay/pay-with-solvapay |
The paying side: what a SolvaPay paywall response means (402, paywallReason), the account tools on SolvaPay MCP servers, top-up and auto-recharge, and connecting an agent so it can pay merchants itself (sandbox, test money) |
solvapay/create-mcp-app |
Create or scaffold a paid MCP server in TypeScript (Cloudflare Workers; from OpenAPI or hand-written), Python or Go (containers; hand-written), add a paywall to an existing one, or sell its tools to agents |
solvapay/app-integration |
Hosted checkout and customer portal, paywalls, usage, webhooks, and billing UI for an existing app, API or website (Next.js, React, Express, Supabase Edge, Vite + Supabase, FastAPI / Starlette, Go net/http), and selling API calls to agents. Formerly sdk-integration; also absorbs the retired website-checkout and lovable-checkout skills — --skill website-checkout and --skill lovable-checkout no longer resolve; install --skill app-integration. |
- "Scaffold a paid MCP server from this OpenAPI spec" →
solvapay/create-mcp-app - "Add SolvaPay paywall to my Express API" →
solvapay/app-integration - "Build a paid MCP server in Python" / "in Go" →
solvapay/create-mcp-app - "Paywall my FastAPI endpoint" / "my Go
net/httpAPI" →solvapay/app-integration - "Add usage metering to my MCP server" →
solvapay/create-mcp-app - "Add hosted checkout to my Next.js site" →
solvapay/app-integration - "Add checkout to my Vite + Supabase (Lovable) app" →
solvapay/app-integration - "This API returned 402 with a checkoutUrl" / "let my agent pay for APIs" →
solvapay/pay-with-solvapay - "I just want to add SolvaPay" (vague) →
solvapayasks one disambiguation question, then routes
Pick the variant that matches the context.
| Context | Command | Notes |
|---|---|---|
| Top-of-funnel (README hero, marketing) | npx skills add solvapay/skills |
Opens a multi-select prompt across all 4 skills. Best for human discovery. |
| Quickstart / "install everything" | npx skills add solvapay/skills --all -y |
Installs all 4 to every detected agent, no prompts. Optional convenience. |
| Surface-specific (e.g. a docs page for one product) | npx skills add solvapay/skills --skill create-mcp-app -y |
Install just one skill. Routing id is solvapay/<surface>; CLI --skill uses the flat folder name. |
| Power user / CI | npx skills add solvapay/skills --all -g -y |
Non-interactive global install. |
Vague intent? Install
solvapayalone — it routes by routing id (solvapay/<surface>) and tells the agent to runnpx skills add solvapay/skills --skill <surface> -ywhen needed (flat CLI name, e.g.create-mcp-app).
Every skill in this family uses the same retrieval chain:
- SolvaPay Docs MCP server: https://docs.solvapay.com/mcp
- Fallback docs index: https://docs.solvapay.com/llms.txt
- Direct docs.solvapay.com page fetch
If MCP is unavailable, the skill continues with fallbacks. MCP setup is a recommended optional improvement.
Regression specs for description triggering and output quality live at evals/ (not loaded when a skill activates). See evals/README.md for the harness contract, routing boundaries, and SKILLS_REPO / EVAL_DEV_MODE env vars.
Per skill: trigger-queries.json (8–10 should-trigger + 8–10 should-not, train/validation split) and evals.json (output cases with assertions).
Maintainer notes (versioning, dev backend, what must stay out of a skill) are in CONTRIBUTING.md.
For live editing, symlink every skill in this repo into the agent skill search
paths (~/.agents/skills/<name> plus a ~/.claude/skills/<name> mirror) so
edits are picked up without reinstalling:
npm run dev:link # local development ON — symlink all skills to this repo
npm run dev:status # show what is linked where
npm run dev:unlink # local development OFF — remove symlinks, restore any backupsdev:link moves any pre-existing standalone copy aside to <name>.local-backup
and restores it on dev:unlink, so toggling is non-destructive. Run dev:link
again after git pull only if new skills were added.
Then validate each skill with prompt checks:
- Edit skill files in this repository (changes are live via the symlinks above).
- Run 2–3 prompt checks per skill: routing intent, happy-path implementation, failure-path / troubleshooting.
- Verify outputs follow each skill's guardrails and the shared docs source priority.
Alternatively, install a snapshot with npx skills add . --skill <name> (or --all -y to mount everything) — but that copies files rather than linking, so edits require a reinstall.
To list all discoverable skills before pushing:
npx skills add . --listTo validate every skill against the agentskills.io spec:
npm run validateThis runs npx skills-reference validate on every directory under skills/ that contains a SKILL.md, then scripts/check-language-headings.mjs, which fails when the ## headings of a skill's references/languages/*.md files differ.
Pushing a vX.Y.Z tag runs .github/workflows/release-skills.yml. It builds one release asset per skill, writes an Agent Skills discovery index (index.json) with each skill's frontmatter description and the SHA-256 of its asset, and attaches everything to the release. The release is created as a draft, the uploaded assets are downloaded and re-verified, and only then published.
The index type is picked per skill, following the spec's distribution guidance:
| Skill folder holds | Index type |
Release asset |
|---|---|---|
only SKILL.md (e.g. solvapay) |
skill-md |
<name>.md, the raw SKILL.md bytes |
anything else (references/, scripts/, …) |
archive |
<name>.tar.gz, folder contents at the archive root |
Adding a first reference file to a single-file skill switches it to archive on the next release; there is nothing to configure. Symlinks fail the build, because the skills CLI rejects links in archives. Archives are deterministic: a skill that hasn't changed keeps the same digest across releases.
Build and verify locally without releasing:
npm run release:dry-runOutput goes to dist/release/. The latest index is always at https://github.com/solvapay/skills/releases/latest/download/index.json.
A skill is considered complete when:
- it has clear when-to-use scope and "Use when" trigger keywords in its frontmatter
- it has guardrails with explicit "Never" / "Always" rules
- it has a step-by-step implementation flow
- it has verification and troubleshooting guidance
- it uses docs-only, topic-based references resilient to docs URL changes
skills/
├── solvapay/ # Router (routing id: solvapay)
│ └── SKILL.md
├── pay-with-solvapay/ # routing id: solvapay/pay-with-solvapay (single SKILL.md)
│ └── SKILL.md
├── create-mcp-app/ # routing id: solvapay/create-mcp-app
│ ├── SKILL.md
│ ├── scripts/ # incl. check-toolchain.mjs
│ └── references/ # incl. languages/{ts,python,go}.md, hosting/container.md
└── app-integration/ # routing id: solvapay/app-integration
├── SKILL.md
├── scripts/
└── references/ # incl. hosted-checkout-*.md, python.md, go.md, agent-payments.md
Routing ids use the solvapay/<surface> namespace for handoffs. Each directory's name frontmatter matches the folder (e.g. create-mcp-app); npx skills add --skill uses that flat name.