skill-creator

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.