sota-api-design — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited sota-api-design (Agent Skill) and scored it 96/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 1 flagged
A bulleted imperative like {match} tells the agent to never reveal, disclose, or mention something to the user. Used adversarially it can instruct the agent to hide its tool calls or lie about what it did — stripping the transparency a user relies on to trust the agent.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Expert-level rules for building and auditing API surfaces: HTTP/REST semantics, GraphQL, gRPC/protobuf, realtime (WebSocket/SSE/WebTransport), webhooks, contract evolution, and the security/operational envelope around all of them. Rules are imperative with rationale and good/bad examples; every rules file ends with an audit checklist. Use the index table below to load only the files relevant to the task — do not read all files for a narrow question.
When designing or implementing an API:
rules/04 §1 first if the choice(REST vs GraphQL vs gRPC vs realtime transport) is open. Default: gRPC service-to-service, REST at the edge, GraphQL only for multi-client shape diversity, SSE for server-push, WS only for true bidirectional.
resource model, error shape (RFC 9457), pagination, and naming right in the spec — they are nearly impossible to fix later (rules/01, rules/02).
3339 timestamps, opaque IDs, open enums, tolerant-reader contract, CI breaking-change diff from day one (rules/02).
Retry-After, timeout budgets, problem+json errors, size limits — these are features, not hardening passes (rules/01 §6, rules/07).
heartbeat, resume, ordering, backpressure, and close semantics (rules/05); signing, retries, SSRF egress controls (rules/06) before writing code.
per-principal rate limits, tenant isolation derived from credentials, audit logging (rules/07).
your own design as a self-review.
When reviewing an existing API:
handlers, webhook senders/receivers, gateway config) and load the matching rules files.
verify in code, don't trust docs or comments. Prefer reading: route definitions, middleware chains, error handlers, pagination queries, proto history, WS connection handlers, webhook dispatch code, gateway/limiter config.
pagination on big tables, 200 {"error":…}, missing deadlines, unbounded WS send buffers, unsigned webhooks, SSRF in webhook egress, origin-reflection CORS, tenant ID taken from the request body.
missing object-level/tenant authz, unsigned or non-constant-time-verified webhooks, SSRF-able webhook egress, credential leakage (query strings/logs), origin-reflection CORS with credentials, reused proto field numbers, double-execution of payments (no idempotency on money writes).
change shipped without versioning/deprecation, no rate limiting on authed surface, missing deadlines/timeout hierarchy, unbounded pagination or request sizes, no WS backpressure/resume (silent data gaps), non-idempotent webhook consumers.
9457 error sprawl, offset pagination at scale, spec/implementation drift, no Sunset/Deprecation signaling, missing rate-limit headers, N+1 resolvers, closed response enums.
operationIds,missing preflight cache, suboptimal cache headers, missing pagination link hints.
[SEVERITY] <one-line title>
Where: <file:line | endpoint | schema element>
Rule: <rules-file §section>
Issue: <what is wrong, with the observed evidence (code/HTTP exchange)>
Impact: <concrete consequence — who breaks, what leaks, what corrupts>
Fix: <specific change; example snippet/header/schema where load-bearing>Order findings by severity; one finding per root cause; no speculative findings without evidence in code or spec.
| File | Read this when... |
|---|---|
rules/01-rest-http-design.md | Designing/auditing REST endpoints: resource modeling, methods/status codes, cursor pagination, filtering, partial responses, idempotency keys, ETags/conditional requests, HATEOAS pragmatism, RFC 9457 errors, OpenAPI-first, contract testing. |
rules/02-versioning-evolution.md | Changing an existing API, adding/removing fields, choosing URL vs header versioning, planning deprecation (Sunset/Deprecation headers), enum/schema evolution, tolerant readers, CI breaking-change gates. |
rules/03-graphql.md | Any GraphQL work: schema/nullability/connections design, N+1 and dataloaders, depth/cost/alias limits, persisted-query allowlists, error channels (userErrors vs errors), resolver authz, when GraphQL is the wrong choice. |
rules/04-grpc-protocols.md | gRPC/protobuf work or protocol selection: field-number/reserved evolution rules, deadlines and cancellation propagation, streaming patterns, rich error details, gRPC-Web/Connect, L7 load balancing, REST vs GraphQL vs gRPC decision table. |
rules/05-realtime-websockets-sse.md | WebSocket/SSE/realtime features: transport choice (WS vs SSE vs WebTransport), upgrade auth & CSWSH, heartbeats, reconnect backoff + resume tokens, ordering/delivery guarantees, backpressure, close codes, SSE replay, pub/sub fanout scaling, presence. |
rules/06-webhooks.md | Sending or receiving webhooks: HMAC signing + timestamp + rotation, replay protection, retry/backoff design, ordering caveats, idempotent consumers, outbox dispatch, reconciliation APIs, SSRF defenses for user-supplied URLs. |
rules/07-security-operations.md | Cross-cutting security/ops on any API: authn scheme selection (keys/OAuth2/mTLS), rate limiting + 429/Retry-After, quotas, request size limits, timeout budgets, CORS, audit logging, multi-tenant isolation, cross-tenant testing. |
the credential, never from the request; cross-tenant access returns a consistent 404. (rules/07 §1, §7)
problem+json error shape API-wide, machine-readable codes, trace ID, no internals leaked. (rules/01 §3, §9)
grow; stable sort with unique tiebreaker; no unbounded lists in REST or GraphQL. (rules/01 §4, rules/03 §2)
replay on anything that moves money or sends things; webhook consumers dedupe on event ID. (rules/01 §6, rules/06 §4)
check); clients ignore unknown fields; breaking changes go through the announce→Deprecation/Sunset→measure→410 pipeline. (rules/02)
long work is async (202 + status resource), never a long-held connection. (rules/04 §3, rules/07 §4)
headers, enforced in a shared store; expensive operations cost-weighted. (rules/07 §2)
IDs + bounded replay buffer, explicit resume-failure → snapshot; bounded send queues with a defined slow-consumer policy. (rules/05 §2)
constant time with replay window; senders block private/metadata IPs with resolve-pin-connect and follow no redirects. (rules/06 §2, §8)
(reserve removed ones), enum zero = UNSPECIFIED, GraphQL non-null only when guaranteed, every data-touching resolver behind a dataloader. (rules/04 §2, rules/03 §2–3)
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.