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.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/matt-riley/agent-skills --skill http-api

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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.
来自同一仓库

更多 Skills

全部 Skills