More screenshots
Works with the AI Agents you already use
Claude Code
Cursor
Codex CLI
Muse
Dots+22 moreClaude CodeCursorCodex CLIMuseDots
OpenClaw
Manus
Grok
Grok Bot+18 agentsSpecseal: Agree the API contract before you build it
Validated schemas, one error shape, status-code rules, pagination, idempotency keys, scopes and rate limits in one OpenAPI file or typed contract, with contract tests and a breaking-change checklist.
$15
Specseal: Agree the API contract before you build it
Example session with this skill installed
Specseal, review our job board API before the mobile app launches. Routes are in src/routes (Express + Zod). Tell me what to fix first.
- Read your context and instructions
- Compiled the specseal
Reviewed 6 endpoints in src/routes (example project). Consumers: web app, mobile app (cannot update instantly), nightly cron.
| Endpoint | Issue | Severity | Fix |
|---|---|---|---|
| GET /jobPosts | Returns every row, no pagination; path not kebab-case | High | Cursor pagination, default 20, max 100; rename to /job-posts |
| GET /job-posts/{id} | 200 with an error body when missing | High | 404 with code JOB_NOT_FOUND |
| POST /applications | No idempotency; a retry creates a duplicate | High | Accept Idempotency-Key, store key, caller and response hash with a TTL |
| PATCH /users/{id} | Any signed-in user can edit any id | High | Ownership check; 404 when not visible to the caller |
| POST /auth/login | No rate limit | Medium | Per-caller limit, 429 with Retry-After |
| GET /teams/{id}/members/{mid}/roles | Nested two levels | Low | Move to /members/{mid}/roles |
4 high, 1 medium, 1 low. Fix the error shape and validation first:
{ "error": { "code": "JOB_NOT_FOUND", "message": "Job not found", "details": [], "requestId": "req_7f3a" } }
Breaking for the mobile app: the /jobPosts rename and the new page-size default. Ship both under /v1 with a Sunset header on the old route, or agree a migration window with the mobile team.
Next steps
- Add the central error handler and the shared error schema.
- Write
openapi.yamland contract tests for the 4 high items. - Run the breaking-change checklist against the deployed contract before ship.
Connects securely to your tools. The creator never sees your data.
About this skill
Every route returns its own error format, a renamed field crashes the mobile app that cannot update, and a retried POST creates the order twice. The cause is that nobody agreed what the API promises. Specseal writes that contract first, so clients, tests and docs come from one source.
What it does
- Use-case first design derives endpoints from each consumer's actor, action, data in and data out, not from the tables.
- Validated schemas check params, query, body and headers at the boundary with the schema library your stack already has (Zod, Pydantic, JSON Schema).
- One success and one error shape with stable machine codes, field-level validation details and a request id.
- Status-code rules, including "never 200 with an error body".
- Lists, retries and scopes: every list paginated with a max page size, an
Idempotency-Keyon retry-sensitive POSTs, scopes and ownership checks on every path id. - Rate limits and versioning written into the contract, with 429 plus
Retry-Afterand a deprecation path for breaking changes.
How it works
- Consumers and naming: one line per use case, then plural kebab-case paths, one field case and nesting of at most one level.
- Schemas and rules: request, response and error schemas per endpoint, with the rules above applied.
- Contract as source: an OpenAPI 3.1 file or a typed schema module that generates OpenAPI, linted in CI.
- Contract tests: valid request, each documented error, missing auth, wrong owner and idempotent replay.
- Breaking-change checklist: the contract is diffed against the deployed version before ship.
Frameworks & tools
OpenAPI 3.1 or a typed schema module, using Zod, Pydantic or JSON Schema. Variants cover internal apps, public APIs, API reviews and webhook providers.
Why this beats prompting it yourself
A plain prompt designs endpoints one at a time and lets each one invent its own rules. Specseal applies one rule set across the whole API, traces every endpoint to a use case, and ends with contract tests and a breaking-change diff.
Use cases
- New backends designed before handlers exist.
- Payload disputes between frontend and backend.
- Partner or mobile APIs whose clients cannot update instantly.
- Live endpoint changes checked for breakage.
Known limitations
Does not design database tables or migrations, and does not cover credit or payment idempotency inside a ledger. For a server-rendered page with no external client, a typed server function may be enough.
How to use
Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill passes our trust checks below.
Security scanned
Passed our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scanned
Verified clean 1 day ago
- Passed all security checks, Safe to install
Requires