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 --live-probe [--pay]  # 4. live-402 check (THE GATE)
npm run catalog                                 # 5. regenerate index.json + README table
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. 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 with selat search "<capability>" --json — the live hosted catalogue selat run ranks — and record each result's payable endpoint.url (NOT the descriptive provider service.url), method, and price. Skip Apify prepaid-token Actors; a step can't pay them per call. 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 = the payable endpoint.url, ${param} substitution, body for POST. Each step's rail is a descriptive label — set it from the mode that verify reports, since the actual payment mode is detected from the live 402 at run time, not read from the manifest.
   • 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> --live-probe 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 submit. Fix any step that's unreachable or over cap; prefer first-party providers over proxies. The free probe proves a step is payable, not that it delivers — that is what the paid call before merge is for (step 9).
7. Register: npm run catalog regenerates index.json and the README skills table from the manifests. Never hand-edit either file.
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. Before merge, a SELAT maintainer makes a real paid call (verify --live-probe --pay) and every step must settle a 200. No skill enters the registry without it — that paid call is what makes a hub skill vetted. Running --pay yourself first is optional (it spends from your wallet) but catches param bugs before review.
10. After merge: a scheduled CI job re-probes every skill (free) and records its status in reliability.json (ok / degraded / down), which selat skill list --available shows as a badge. A step that stops being served turns the skill degraded — fix or drop it.