Http Api

Shape HTTP/JSON APIs—resources and verbs, error payloads, pagination, idempotency, and docs. Use when designing new endpoints, reviewing PRs, or aligning tea...

Security Scan

This is an instruction-only API-design guidance skill that requests no credentials, does not install code, and its instructions are consistent with its stated purpose.

Purpose & Capability

The name/description (HTTP API design and reviews) matches the SKILL.md content. There are no environment variables, binaries, or config paths requested that would be unrelated to API design.

Instruction Scope

SKILL.md contains only prose-level guidance for API modeling, HTTP semantics, errors, DX, and review order. It does not instruct the agent to read files, access environment variables, call external endpoints, or collect user/system data.

Install Mechanism

No install specification and no code files are present (instruction-only). Nothing will be written to disk or downloaded as part of installation.

Credentials

The skill requests no environment variables, credentials, or configuration paths; nothing disproportionate is requested for the stated design/review purpose.

Persistence & Privilege

Skill flags show default behavior (not always: true) and model invocation is allowed (platform default). There is no indication the skill tries to persist or modify other skills or system-wide configuration.

Assessment

This skill is an offline, text-only guide for designing and reviewing HTTP/JSON APIs and does not access credentials or your filesystem. It appears safe and coherent to install, but remember: it's advice—validate any suggested changes against your organization's security, compatibility, and operational policies before applying them. If you need machine-executable checks or integrations (tests, CI automation, versioning policies), look for or request a skill that explicitly declares those capabilities and the minimal required credentials or install steps.

Design and review HTTP-facing APIs (usually JSON): predictable URLs, honest status codes, and errors clients can build on—without duplicating everything your api-compat skill covers for long-lived versioning policy.

Scope

• Modeling: nouns/resources, collections, actions when RPC-style is clearer than fake REST.
• HTTP semantics: which methods, idempotency, caching headers when relevant.
• Errors: stable machine-readable codes, correlation ids, avoid leaking internals.
• DX: examples, OpenAPI snippets, consistent pagination/filter patterns.

Out of scope (hand off)

• OAuth/OIDC protocol details → identity-focused skills.
• GraphQL-only schema design → graphql-schema skill.
• Multi-year deprecation policy and client migration programs → pair with api-compat.

Review order

1. Read paths — Can a client navigate the domain without guessing?
2. Write safety — Retries safe? Duplicate submits handled?
3. Errors — One shape everywhere; 4xx vs 5xx honest.
4. Evolution — Document what may change vs what is stable (compat details in api-compat).

Smells

• Status 200 with {error: ...}; every POST returns 200; unbounded list endpoints; secrets in error bodies.

Done when

• A new engineer can call the API from docs alone; failure cases are testable and consistent.