matt-riley/agent-skills

http-api

Keep HTTP APIs honest: sync OpenAPI contracts with handler behavior, and write or debug end-to-end HTTP integration tests for handlers, middleware, auth, and endpoint contracts.

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/matt-riley/agent-skills --skill http-api

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

HTTP API

Use this skill when

  • The task adds or changes a public HTTP endpoint and the OpenAPI contract must stay aligned.
  • Request/response schemas, status codes, auth requirements, or documented errors are changing together.
  • Code and API contract have drifted and the repo needs the correct sync workflow.
  • HTTP integration tests need adding or fixing for handlers, middleware, auth enforcement, status codes, validation, or side effects.

Do not use this skill when

  • The request is a generic REST/OpenAPI tutorial.
  • The task is only to generate a client SDK from an existing spec with no server-contract change.
  • The change is internal-only code with no HTTP contract or no OpenAPI surface in play.
  • The failure is clearly at the unit-test layer with no HTTP involved — use `testing-workflows`.

Inputs to gather

  • Where the API contract lives:
  • hand-authored spec files
  • code annotations/types/routes that generate the spec
  • a hybrid flow that updates both
  • Validation/generation commands for the repo (make validate-openapi, swagger-cli, codegen targets, etc.).
  • The exact endpoint surface being changed: path, method, auth, request body, success responses, error responses.
  • Whether the endpoint is public/external, internal-only, or intentionally undocumented.

First move

Determine the repo's contract flow before editing anything: spec-first, code-first, or hybrid. Do not assume openapi.yaml is the source of truth or that it should be hand-edited.

Workflow

  1. Identify the contract owner.
  • Read the repo docs, build targets, and generation tooling to see whether the spec is hand-maintained, generated from code, or maintained in both places.
  1. Follow the repo's contract path.
  • Spec-first repos: update the OpenAPI contract first, validate it, then implement handlers/middleware/tests to match.
  • Code-first repos: update the handler/types/annotations first, regenerate the spec/artifacts, then verify the generated contract matches the intended behavior.
  • Hybrid repos: update both authored surfaces in the order the repo expects, then run validation/generation to reconcile them.
  1. Verify the behavior-contract alignment.
  • Match auth requirements, request validation, response schemas, status codes, and documented error shapes.
  • Confirm the changed endpoint is included or intentionally excluded from the OpenAPI surface.
  1. Run the repo's API checks.
  • Validate the spec when the repo has a validator.
  • Run the relevant integration/unit/contract tests for the changed surface.
  1. Integration tests (when adding, fixing, or debugging HTTP-level coverage).
  • Run the targeted test verbosely and read the real request/response before proposing fixes.
  • Follow references/integration-testing-http.md for the runner, auth fixtures, DB bootstrap, and scoped reruns.
  • Worked cases are in references/integration-testing-http-examples.md; flaky, stateful, or generated-code traps in references/integration-testing-http-edge-cases.md.

Outputs

  • Updated contract-owner artifacts for the changed API surface, including spec, handler/type inputs, and any generated OpenAPI output the repo expects.
  • A documented behavior-to-contract alignment for auth requirements, request validation, response schemas, status codes, and error shapes.
  • Spec validation, generation, and/or API test evidence confirming the handler behavior and OpenAPI contract stay in sync.

Guardrails

  • Do not hand-edit generated OpenAPI output in code-first repos; change the source inputs that own it.
  • Do not change public endpoint behavior without the matching contract update or regeneration.
  • Auth requirements, status codes, and error shapes must align with the contract owner the repo actually uses.
  • If the repo has no OpenAPI contract for this surface, do not invent one unless the user asks for that design decision; document the gap instead.
  • When handler changes also affect generated clients/server stubs, coordinate with the code-generation workflow rather than patching generated artifacts directly.

Validation

  • The repo's spec validation or generation step succeeds.
  • Handler behavior, tests, and contract artifacts agree on auth, schemas, and status codes.
  • Any generated contract files or checked-in specs show only the expected diff.

Reference files

  • Read references/examples.md when you need examples of drift repair or endpoint changes that must keep contract and implementation aligned.
  • Read references/edge-cases.md when the repo lacks a spec, uses generated specs, or the request may really be SDK generation or a non-HTTP change.
z tego samego repozytorium

Więcej Skills

Wszystkie Skills