# CleanSkills — Skill Certification (Agent Guide)

CleanSkills certifies a `SKILL.md` file for an AI agent skill package. Pay $1,
get an immutable CLR-ID certificate and a verifiable on-chain record — issued
instantly the moment payment clears. No account, no subscription, no review queue.

- Provider: BTNOMB (https://btnomb.com)
- Base URL: https://cleanskills.btnomb.com
- Price: $1 USDC, flat, per certification
- Payment: x402 (gasless USDC on Base)
- Delivery: instant

## What it does

You submit the contents of a `SKILL.md` file (or a URL pointing to one).
CleanSkills records it, hashes the contents (SHA-256), issues a unique
CLR-ID certificate, and returns a shareable cert page plus an embeddable badge.
The certificate is verifiable at a stable URL forever.

## Certify a skill

`POST https://cleanskills.btnomb.com/api/certify`

Payment: $1 USDC via x402 on Base. The first request returns HTTP 402 with a
payment challenge; retry with the x402 payment header (any x402-compatible
client library handles this automatically).

### Input

Provide exactly one of `skillmd` or `url`:

```json
{ "skillmd": "---\nname: web-search\n---\n# Web Search\n...full SKILL.md contents..." }
```

or

```json
{ "url": "https://raw.githubusercontent.com/acme/skills/main/SKILL.md" }
```

Optional fields: `candidateName`, `candidateEmail`.

### Output

```json
{
  "certId": "CLR-1A2B3C4D5E6F7A8B",
  "certUrl": "https://cleanskills.btnomb.com/cert/CLR-1A2B3C4D5E6F7A8B",
  "badge": "https://cleanskills.btnomb.com/badge/CLR-1A2B3C4D5E6F7A8B.svg",
  "timestamp": "2026-07-07T00:00:00.000Z",
  "skill": "web-search",
  "content_sha256": "…",
  "status": "certified",
  "verified": true,
  "payment": { "amount": "1.00", "currency": "USDC", "network": "base", "protocol": "x402" }
}
```

## Verify a certificate (free)

`GET https://cleanskills.btnomb.com/api/verify/{certId}`

Returns `{ clr_id, status, verified, x402_trust, issued_at, issuer, ... }`.
No payment or auth required.

## Embed the badge

Add the returned `badge` SVG to your README:

```markdown
[![CleanSkills Certified](https://cleanskills.btnomb.com/badge/CLR-XXXX.svg)](https://cleanskills.btnomb.com/cert/CLR-XXXX)
```

The badge reflects live certification status.

## Discovery

- This guide: `GET https://cleanskills.btnomb.com/skill.md`
- Agent manifest: `GET https://cleanskills.btnomb.com/.well-known/agent.json`
- AI plugin manifest: `GET https://cleanskills.btnomb.com/.well-known/ai-plugin.json`
- OpenAPI spec: `GET https://cleanskills.btnomb.com/api/openapi.json`

## Example (curl, once you have an x402 client)

```bash
curl -X POST https://cleanskills.btnomb.com/api/certify \
  -H "Content-Type: application/json" \
  -d '{"url":"https://raw.githubusercontent.com/acme/skills/main/SKILL.md"}'
# -> HTTP 402 with x402 payment challenge; pay $1 USDC on Base and retry
```