SELAT-AI/selat-skills

skill-creator

Author a new skill for the selat-skills hub and get it merged, using the official selat skill CLI. A skill is a declarative directory the selat CLI executes — never code that calls selat-pay itself. This is the hub's contribution guide (CONTRIBUTING.md points here); keep it open while you build.

When To Use

Use when someone wants to add a capability to the hub by composing one or more paid federated-catalogue endpoints into a named skill, or asks how the manifest/SKILL.md/evals fit together, how to find a payable endpoint, how to verify it, or how to submit. Not for editing the CLI or router — this is skill content only.

Workflow

The whole loop (matches CONTRIBUTING.md):

selat skill new my-skill --dir skills           # 1. scaffold
#   …edit the files (replace every TODO)…        # 2. author
selat skill validate ./skills/my-skill          # 3. static SOP check
selat skill verify   ./skills/my-skill [--pay]  # 4. live-402 check (THE GATE)
selat skill register ./skills/my-skill          # 5. add index.json entry
npm run validate                                # 6. whole-repo check (what CI runs)
selat skill submit   ./skills/my-skill          # 7. open the PR

1. Define + scaffold. One skill = one coherent capability; pick the rail (direct Circle nanopayment / routed MPP via the SELAT Router / mixed). Then selat skill new <name> --dir skills writes skills/<name>/ with manifest.json, SKILL.md, references/endpoints.md, evals/evals.json. (No CLI handy? scripts/new-skill.mjs does the same scaffolding offline.)
2. Discover endpoints in the federated catalogue and record each merchant's serviceUrl (NOT the descriptive provider url), method, path, price. See references/endpoint-discovery.md — this is where most skills break.
3. Enrich each endpoint's schema — pin the real request shape before writing any body/${param}, from a free source, because a wrong param name or shape still costs money: the SELAT Router settles the payment before the upstream validates the body, and a verify probe checks payability, not param correctness. Pull the gateway's OpenAPI (<serviceUrl-host>/openapi.json), decode the self-describing bazaar schema in the 402 payment-required header, or read the upstream's public API docs — then corroborate against the live API, which is the real source of truth (specs drift: observed tweet_id vs live tweetId, and "only field X required" when the live API rejects a body without more). Record every param (name, required, type, enum, format) in references/endpoints.md and map each manifest ${param} to the real API param name. See references/schema-enrichment.md.
4. Author — replace every TODO:
   • manifest.json — name (== folder), maxAmount (cap with headroom, a filter not a price), params (real defaults), steps[] with url = serviceUrl + path, ${param} substitution, body for POST.
   • SKILL.md — frontmatter + sections (When To Use, Workflow, Inputs And Outputs, Gotchas, Validation, References). No TODO may remain.
   • references/endpoints.md and evals/evals.json (skill_name == folder).
5. Validate (static): selat skill validate ./skills/<name>.
6. Verify (the gate): selat skill verify ./skills/<name> probes each step's real 402 price/rail (free) and checks it ≤ maxAmount; --pay makes a capped real call to confirm it settles 200. Pass required params as flags. This writes skills/<name>/.selat/verify-receipt.json — the provenance submit attaches to the PR and that gates merge. Fix any step that's unreachable or over cap; prefer first-party providers over proxies.
7. Register: selat skill register ./skills/<name> auto-adds/updates the index.json entry from the manifest.
8. Whole-repo check: npm run validate (exactly what CI runs).
9. Submit: selat skill submit ./skills/<name> (use --dry-run first). It requires a passing verify receipt, then branches, commits skills/<name> + the index.json entry, pushes, and opens a PR with the receipt as provenance. No write access? It prints fork-and-PR commands. A maintainer paid-re-verifies before merge.

Authoring Voice

A skill's reader is the agent; the agent's audience is often a non-technical user. Author for that split:

• Command blocks are instructions for the agent to execute — never content the user is expected to read.
• In Workflow, add a "tell the user" line wherever the agent should report back — especially before any spend ("this costs about $X — proceed?") and when relaying results in plain language.
• Keep endpoint URLs, wallet addresses, and raw response JSON out of what the agent is told to relay; plain language plus the dollar price is the default.

Available Scripts

• scripts/new-skill.mjs <name> [--rail …] [--kind …] [--dir skills] — offline scaffolder equivalent to selat skill new, for environments without the CLI. Non-interactive; --help for usage.

Inputs And Outputs

Input	What you provide
Capability	The one task the skill performs
Endpoints	Catalogue serviceUrl + path + method + price per step
Params	Named inputs with sensible defaults

Output: a skill that passes validate, has a passing verify receipt, and is ready for submit.

Gotchas

• Wire steps to the catalogue serviceUrl, NOT the provider url. A record has a descriptive url (https://api.tomba.io) and a payable serviceUrl (https://mpp.orthogonal.com/tomba). The 402 is served only at the serviceUrl; the provider host yields "no challenge" and a failed verify.
• POST/PUT params go in body, not the query string — a POST with ?k=v often returns no challenge.
• maxAmount is a spending filter, not the price. Set it with headroom over the live quote (gateway prices run a few percent above the catalogue) or verify flags the step as over-cap.
• Give params real defaults so verify (and users) can exercise each step.
• verify is the gate, and the live 402 is the source of truth. The catalogue lists endpoints the gateway may no longer serve. Never submit a step that doesn't verify; omit it and re-add when it's served.
• Enrich the schema from a free source before the first paid call — a wrong param still charges. The Router settles payment before the upstream validates the body, and a probe checks payability, not param correctness. Pin the shape from the gateway OpenAPI (<host>/openapi.json), the 402 bazaar extension, or upstream docs, then confirm with verify --pay. Specs drift from the live API; the live API wins (seen: OpenAPI tweet_id vs live tweetId; "only input required" when the live endpoint also demands model/models/preset).
• ${param} substitutes as a string — no type coercion. A numeric or array field wired as "${n}" sends "8" and 4xx's. Keep string-typed fields in the manifest body; document integer/array fields for a hand-built selat-pay call instead.
• Prefer first-party providers over proxies when equivalent — cheaper/equal, with real identity and recourse.
• The authoring SOP lives only at the repo root references/agent-skill-authoring-sop.md; don't copy it into your skill.
• name == folder, kebab-case, consistent across folder, manifest.json, and SKILL.md frontmatter; evals.json skill_name == folder too.

Validation

Before submit, all must hold:

• selat skill validate ./skills/<name> → passes (also the per-skill CI check).
• selat skill verify ./skills/<name> → every step reachable and ≤ maxAmount (writes the verify receipt). --pay confirms a real settled 200.
• npm run validate → 0 errors (whole-repo + index.json consistency).
• No TODO, secrets, or orth/CLI/subprocess calls — the skill is declarative.

Underlying free single-step probe (what verify runs per step):

selat-pay POST "https://mpp.orthogonal.com/<merchant>/<path>" \
  --body '{"<param>":"<value>"}' --chain base --probe-only
# success prints: detected mpp=yes, mode=routed-mpp, price=$X on eip155:8453

--chain base is only the flag the probe requires — probing reads a free, chain-independent quote and never settles. The settlement chain for a paid run is resolved at runtime from the wallet's funded Gateway balance, so a manifest does not declare one.

References

• CONTRIBUTING.md — repo-level quick reference that points back to this skill.
• references/manifest-reference.md — selat-skill/v1 manifest schema, params, rails, examples.
• references/endpoint-discovery.md — finding endpoints in the catalogue and the serviceUrl rule.
• references/schema-enrichment.md — pinning each endpoint's request schema from OpenAPI / the 402 bazaar extension / upstream docs, and verifying it against the live API.
• references/submission-checklist.md — the selat skill command sequence + pre-PR checklist.
• ../../references/agent-skill-authoring-sop.md — the authoring standard.