Skill Creator

---
name: skill-creator
description: Use this skill when a contributor wants to build, author, scaffold, verify, or submit a new skill to the SELAT skill hub (selat-skills) — e.g. "create a skill", "build a selat skill", "add a skill to the hub", "contribute a skill", "how do I write a manifest.json", "verify my skill", "submit my skill", "wrap an MPP endpoint as a skill". Guides you through the official `selat skill` flow (new → author → validate → verify → register → submit) and encodes the gotchas that make a skill actually pay.
license: Apache-2.0
compatibility: Requires Node.js 18+, the selat CLI, and selat-pay >= 0.12.0 on PATH. Verifying routed skills needs SELAT_ROUTER_URL set; `selat skill verify --live-probe` (without --pay) is free and needs no funded wallet.
metadata:
  author: SELAT-AI
  version: "1.2"
  kind: guidance
---

# 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`](../../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`):

```bash
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.

## 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 | Payable `endpoint.url` + method + price per step, from `selat search` |
| 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 payable URL, NOT the provider URL.** A record has a
  *descriptive* provider URL (`service.url`, e.g. `https://api.tomba.io`) and a
  *payable* one (`endpoint.url`, on the catalogue `serviceUrl` host, e.g.
  `https://mpp.orthogonal.com/tomba/...`). The 402 is served only at the payable
  host; the provider host yields "no challenge" and a failed verify.
- **Discover from `selat search`, not a cached catalogue file.** It reads the same
  hosted catalogue `selat run` ranks; a stale local dump wires endpoints agents
  are no longer routed to.
- **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> --live-probe` → every step reachable and ≤ `maxAmount`
  (writes the verify receipt). `--pay` confirms a real settled 200 — optional for
  you, required by the maintainer before merge.
- `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):

```bash
selat-pay POST "https://mpp.orthogonal.com/<merchant>/<path>" \
  --body '{"<param>":"<value>"}' --chain base --probe-only --live-probe
# 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`](../../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 with `selat search` 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`](../../references/agent-skill-authoring-sop.md) — the authoring standard.