11b82cbb91
* feat(api): installable accounted-api agent skill + openapi-to-skill generator Three layers, per the July/August 2026 agent-skills ecosystem (skills.sh / npx skills add, as used by Stripe/Cloudflare/Supabase for their APIs): - skills/openapi-to-skill/: generic, installable skill that turns any OpenAPI spec into a consumer-side integration skill, with a portable stdlib-only inventory/condenser tool and an output template + quality checklist encoding the distill-not-restate methodology. - skills/accounted-api/: the installable skill for our own API, rendered deterministically by scripts/api-skill/generate.ts from the v1 endpoint registry + hand-authored overlays (auth, conventions, domain gotchas). CI gate: npm run apiskill:check (core-build.yml). - lib/api/v1/registry.ts: generateOpenApiSpec now emits requestBody (incl. multipart binary parts) and path parameters, and the Zod converter learned .default()/z.record()/.pipe()/.transform(), so the public spec carries request contracts instead of prose-only. Docs: /docs/api landing + /llms.txt now point agents at the skill install; corrected the stale test-key description in the landing (test keys read real data and force dry-run writes; they are not sandbox-company bound). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skills): escape backslashes in markdown table cells (CodeQL js/incomplete-sanitization) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
5.7 KiB
name, description
| name | description |
|---|---|
| openapi-to-skill | Turn an OpenAPI/Swagger spec (JSON or YAML, file or URL) into an installable agent skill that teaches coding agents how to call that API correctly. Use when the user says "build a skill for this API", "generate a skill from this spec", "make our API docs agent-ready", or points at an openapi.json / swagger.yaml and wants an integration skill. Produces a SKILL.md + references/ folder ready for `npx skills add`. |
OpenAPI spec to agent skill
You are building a consumer-side skill: a folder of distilled instructions that lets an agent integrate correctly against an API on the first attempt. The output is NOT a restatement of the spec. A spec restatement grades D: the agent could have read the spec itself. The value you add is selection (what matters), compression (condensed schemas), conventions (the cross-cutting rules), and verification (what the live API actually does).
Inputs
Collect these before starting (ask only for what is missing):
- Spec location: file path or URL. If URL, download it next to your work.
- Output directory:
skills/<api-name>/in the repo when the skill will be distributed (installable vianpx skills add owner/repo --skill <api-name>),.claude/skills/<api-name>/when it is for personal/project use only. - Credentials for verification (optional but strongly preferred): a base URL and an env var holding a low-privilege or test API key. Read-only verification only; never call write endpoints without explicit user consent.
Process
1. Inventory the spec
Run the bundled tool (portable, stdlib-only Node):
node scripts/openapi-inventory.mjs <spec.json> # overview: groups + one line per operation
node scripts/openapi-inventory.mjs <spec.json> --group <g> # full detail for one group
YAML specs: convert first (npx -y js-yaml spec.yaml > spec.json).
The overview gives you: title, servers, auth schemes, operation count, and operations grouped by tag (or by dominant path segment when the spec has no tags). Read it fully before writing anything.
2. Extract the conventions
The conventions section is the most valuable part of the output skill: it is what lets an agent predict endpoint behaviour instead of looking everything up. Hunt for them in this order:
info.description: many agent-first APIs state their invariants here.components.securitySchemes: auth header shape, token format, where keys come from (docs often say; if not, ask the user).- Recurring response envelope: sample 3-4 operations with
--groupand compare. Note pagination style (cursor vs offset), error envelope, request id fields. - Recurring parameters and headers: idempotency keys, dry-run flags, expand parameters, rate limits.
x-*extensions: risk levels, scopes, idempotency markers. Surface them; they exist for agents.
If the spec is thin on conventions, check the API's human docs (ask the user for the docs URL) rather than guessing.
3. Choose the reference grouping
Target 6 to 12 reference files. Merge tiny groups thematically (e.g.
customers + articles into invoicing); split any group that would exceed
roughly 500 lines rendered. Every operation must land in exactly one
reference file.
4. Write the skill
Follow references/output-template.md for the exact shape. Non-negotiables:
- SKILL.md stays under ~400 lines. Frontmatter description must name the API and its domain so the skill triggers (the agent sees only name + description at discovery time).
- Conventions before endpoints. Auth + base URL + envelope + pagination + error handling first; the endpoint index after.
- Endpoint index: one line per operation (
METHOD path : summary [badges]), grouped, each group naming its reference file. The inventory tool's overview output is already in this format. - References: start from
--groupoutput, then edit. Deduplicate boilerplate the spec repeats per operation (shared error lists, envelope wrappers) up into the conventions section, keep operation-specific pitfalls inline, and add a worked example (request + realistic response) for the 2-3 most-used operations per group. - Schemas in condensed TypeScript-ish form, never raw JSON Schema.
5. Verify against the live API
This step separates a usable skill from a plausible-looking one. Desk review and live testing find different failure classes.
With credentials: smoke-test read-only endpoints (health/list endpoints, one or two per group), using the exact auth header the skill documents. Compare actual responses against the documented envelope and schemas. Every mismatch is gold: record it in a Gotchas section in SKILL.md. Replace invented examples with real (redacted) response bodies.
Without credentials: add a Verification section stating the skill was generated from the spec and not yet tested live, with the smoke-test commands a future session should run once a key exists.
6. Grade it
Score the output against the checklist at the bottom of
references/output-template.md. Fix what fails, once. Then report to the
user: what was generated, what was verified live vs. desk-only, and how to
install it (npx skills add <owner>/<repo> --skill <name>).
Anti-patterns
- Restating the spec operation-by-operation with no selection or added operational knowledge.
- Raw JSON Schema dumps, or full request/response schemas for every endpoint when a condensed form plus one worked example carries more information.
- Auth buried mid-file. It is always the first section after the intro.
- Inventing example responses when a live call could have produced a real one.
- A giant single SKILL.md instead of progressive disclosure via references/.
- Skipping the grade step because the output "looks complete".