# Skills

> The community catalog of HTTP 402–gated APIs that pay and AI agents read from.

[`pay-skills`](https://github.com/solana-foundation/pay-skills) is the registry behind `pay skills search`. It's a curated repository of provider definitions, each pointing at an x402- or MPP-gated endpoint, with the metadata an agent needs to understand pricing, authentication, and shape.

If you've ever wondered "where does `pay skills search 'translate'` get its answers?" — it's this repo, built and published to a CDN.

## Layout

The source of truth is the `providers/` directory:

```
providers/
  quicknode/rpc/PAY.md                       ← native operator (2 levels)
  paysponge/2captcha/PAY.md                  ← proxied gateway (3 levels)
  merit-systems/stableenrich/enrichment/PAY.md
  solana-foundation/google/translate/PAY.md
```

The path is the provider's fully-qualified name (FQN): `quicknode/rpc`, `paysponge/2captcha`. Two levels for an operator running its own endpoint; three levels for a gateway operator proxying somebody else's API.

Each provider directory contains:

| File           | Required | Purpose                                                                |
| -------------- | -------- | ---------------------------------------------------------------------- |
| `PAY.md`       | yes      | Frontmatter + prose describing the provider.                           |
| `openapi.json` | usually  | Committed OpenAPI 3 or Google Discovery snapshot for the upstream API. |

A typical `PAY.md` frontmatter:

```yaml
---
name: rpc
title: 'Quicknode'
description: 'Pay-per-request JSON-RPC endpoints for 140+ blockchain networks…'
use_case: 'Use for blockchain JSON-RPC, querying account or contract state…'
category: compute
service_url: https://x402.quicknode.com
openapi:
  path: openapi.json
---
```

The frontmatter is what the agent reads when deciding whether a provider matches a task. `use_case` is the most important field for discovery — it's prose-shaped guidance for an LLM.

Public registry entries must commit the OpenAPI document next to `PAY.md` and reference it with `openapi.path` (or inline it with `openapi.content`). `openapi.url` is not accepted for published providers.

## How `pay` consumes it

`pay-skills` is the **input** repository. The CLI doesn't read it directly; it reads the **built index** from a CDN.

The lifecycle:

1. A contributor edits `providers/<fqn>/PAY.md` and opens a PR.
2. GitHub Actions runs `pay catalog check` on the PR — frontmatter validation, live HTTP probes, Solana-payment verdicts. A bad PAY.md or a dead endpoint blocks the merge.
3. On merge to `main`, the workflow runs `pay catalog build .` and publishes `dist/skills.json` to `gs://pay-skills/v1/skills.json` plus per-provider detail files.
4. `pay skills update` (called explicitly or automatically) fetches the index from the CDN. `pay skills search` queries it.
5. When the user selects a provider, the agent fetches the per-provider detail file (`gs://pay-skills/v1/<fqn>.json`) — that holds the OpenAPI document.

Within a few minutes of merge, the new provider is discoverable from any `pay skills search` worldwide.

## Two artifacts to know about

### `skills.json`

The built catalog index — generated, not hand-edited. Contains metadata for every provider: FQN, title, description, category, declared currencies, endpoint count, and the URL to the per-provider detail JSON. Published at `gs://pay-skills/v1/skills.json`. Don't commit changes here; commit changes to `providers/` and let CI rebuild.

### `x402-solana-catalog.md`

A human-readable inventory of every x402-on-Solana endpoint accepting USDC. Organized by category (analytics, social, enrichment, e-mail, voice, etc.). It's manually curated and serves as a reference document — useful for browsing, not used as a build input.

## Add a provider

```sh
pay catalog scaffold acme/search https://api.acme.example/openapi.json --output-dir providers
```

This generates `providers/acme/search/PAY.md` from the upstream OpenAPI doc with TODO markers for the discovery-critical fields. Fill in `category` and `use_case`, make sure the OpenAPI snapshot is committed next to `PAY.md`, then validate locally:

```sh
pay catalog check providers/acme/search/PAY.md
```

Before opening a PR, run the changed-provider check against the upstream branch:

```sh
pay catalog check . --changed-from origin/main
```

A merged PR auto-publishes. See [Commands → catalog](/docs/toolchain/commands/developers#pay-catalog) for the full reference.

## Add a provider source

A team running its own catalog (not the official one) can publish their own `skills.json` and register it locally:

```sh
pay install your-org/your-repo
pay skills update
pay skills search "your search"
```

`pay install` is shorthand for `pay skills add` — see [Commands → other](/docs/toolchain/commands/other#pay-install). Multiple sources stack; `pay skills search` queries all of them.

## Browse the catalog

The canonical browser view is built into the pay.sh site at `/services` (the same data, surfaced on the web). For CLI-side discovery:

```sh
pay skills search "translate"
pay skills search "data" --category data
pay skills show google/bigquery jobs
```