New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Old Coder API Design

by AmazingAng in AmazingAng/old-coder

Reviews or designs an HTTP/JSON API's endpoints, auth, pagination, versioning and deprecations, guarding against inventing a bespoke interface or silently breaking consumers.

MITAuto-check passedBackend & APIs

Install Old Coder API Design

skills CLI
$ npx skills add AmazingAng/old-coder --skill old-coder-api -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AmazingAng/old-coder old-coder-api --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AmazingAng/old-coder.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/old-coder-api .claude/skills/old-coder-api && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
old-coder-api
GitHub stars
749
Used in
1 other repo
Token cost
~3.4k tokens
SKILL.md length
1,793 words
Files
4 (incl. references)
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Reviews or designs an HTTP/JSON API's endpoints, auth, pagination, versioning and deprecations, guarding against inventing a bespoke interface or silently breaking consumers.

  • Adding or changing an HTTP endpoint
  • SKILL.md covers Step 0 — establish scope…, The gates, Deliberately not gates and Review output format, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Reviewing an OpenAPI spec or a route diff for breaking changes

What it does

Before designing anything, the skill has the agent answer three scoping questions out loud: whether the API is public or internal, since internal APIs can tolerate breaking changes that public ones cannot; whether it is an existing surface or greenfield, since an existing surface must run the breaking-changes reference first because compatibility outranks every other improvement; and whether the product's resource model actually supports the shape being proposed, naming an awkward underlying resource model instead of papering over it.

Its stated purpose is to stop two default failure modes: inventing a clever bespoke interface where a boring conventional one would serve consumers better, and breaking downstream callers by renaming or restructuring a field because it reads better now. Reference files cover breaking-change rules, example request and response shapes, and general design patterns. For review-only requests with no implementation planned, the skill's review format is used directly rather than manufacturing a development loop, and when composed with a separate old-coder skill, this one owns the HTTP and JSON contract while the other owns workflow order and evidence.

When your agent uses it

  • Adding or changing an HTTP endpoint
  • Reviewing an OpenAPI spec or a route diff for breaking changes
  • Deciding whether an API change is safe to ship without warning consumers

Example prompts

  • “Review this OpenAPI diff and tell me if it breaks any existing consumers.”
  • “Design a paginated endpoint for listing orders, and check whether our resource model actually supports it.”
  • “Is renaming this response field a breaking change for a public API?”

What it can do on your machine

Read from SKILL.md and the folder at commit a0eb529. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Old Coder API Design loads about 3.4k tokens when it runs, and up to ~7.8k if it reads all its reference files. Until then it costs about 120 tokens; SKILL.md has 1,793 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~120
When it runs · the whole SKILL.md, loaded when a task matches
~3.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~7.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AmazingAng/old-coder at commit a0eb529, republished under its MIT licence (© AmazingAng). 1,793 words, ~3,383 tokens.

Download SKILL.mdSave it as .claude/skills/old-coder-api/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
old-coder-api
description
Design, change, or review an HTTP/JSON API surface — endpoints, request/response shapes, authentication and authorization, pagination, idempotency, rate limits, versioning, and deprecations. Use when adding or modifying an HTTP endpoint, reviewing an OpenAPI spec or HTTP route diff, or deciding whether an HTTP API change breaks consumers. Do not use as a protocol-compatibility checklist for gRPC/protobuf, GraphQL, WebSockets, or other non-HTTP/JSON interfaces.

old-coder-api

Inspired by Sean Goedecke, Everything I know about good API design (2025-08-24).

This skill covers HTTP/JSON contract and operability concerns. Its compatibility rules assume JSON consumers. For gRPC/protobuf, GraphQL, WebSockets, or another protocol, apply the transport-independent principles only alongside that protocol's own compatibility rules. This is not a substitute for a full application-security review.

Good APIs are boring. For the people who build them, an API is a product. For the people who use them, it is a tool in the way of something else. Every minute a consumer spends thinking about your API instead of their goal is waste. An interesting API is a bad API — or would be a better one if it were less interesting.

Two failure modes an agent falls into by default, and this skill exists to stop both:

  1. Inventing. Producing a clever, bespoke interface where the boring conventional one would do.
  2. Breaking. Renaming, restructuring, or tightening a field because it reads better now — and silently breaking every downstream caller.

Composition with old-coder: when both skills apply, this skill owns the HTTP/JSON contract while old-coder owns workflow order, SPEC approval, the gauntlet, and EVIDENCE. Run Step 0 and the gates before SPEC approval; put the surviving API constraints and risks into SPEC and verify them through the gauntlet. For review-only work with no implementation, use this skill's review format without manufacturing a development loop.

Step 0 — establish scope before designing anything

Answer these three, out loud, before writing a route:

QuestionWhy it changes the work
Public or internal? Can you ship code for every consumer?Internal: breaking changes are affordable, complex authentication is fine, non-engineer ergonomics don't matter. Public: none of that holds.
Existing surface or greenfield?Existing → run references/breaking-changes.md first; compatibility outranks every improvement below.
Does the product's resource model support this API?API design tracks the product's basic resources. If the resources are awkward (state machines with no name, records that only exist inside a job, parent/child relations that aren't modeled), the API will be awkward no matter how carefully you design it. Say so instead of papering over it.

Honesty rule for step 0: when the ugliness comes from the underlying model, name it and propose the model fix as the real option. A background-job-polling interface bolted onto a read that should be a read is how the worst APIs happen — technical constraints that the UI hides get laid bare in the API, forcing consumers to understand far more of your system than they should have to.

The gates

Run every gate. Use ✓ only for a verified pass, ✗ + concrete fix for a verified failure, N/A + reason only when the gate truly does not apply, and ? + reason when it remains unverified. Never skip silently.

1. Boring

A competent consumer should be able to guess this endpoint before reading any docs.

  • Resources are the product's nouns (/issues, /projects, /users), plural, stable.
  • Standard verbs and status codes, following the established convention of this API. Use 400 for a general client error; use 422 only when the content type and syntax are valid but the contained instructions cannot be processed. Use 404 for missing and 429 for rate-limited.
  • Standard field names: id, created_at, next_page, url. Match the names the rest of this API already uses — internal consistency beats external convention when they conflict.
  • REST + JSON unless there's a reason. An established, internally consistent HTTP RPC surface can also be boring; do not rename it to resource paths for REST purity. Don't relitigate HATEOAS or JSON-vs-anything; it isn't important.
  • Anything surprising needs a written justification line. If you can't write one, make it boring.
2. Don't break userspace

Applies only to changes on an existing surface. Full matrix in references/breaking-changes.md.

  • Additive is fine: new endpoints, new optional params, new response fields. Consumers are expected to ignore unknown fields.
  • Removing a field, renaming it, changing its type, moving it (user.address → user.details.address), narrowing an enum, or tightening validation is a break. Don't, even if it's neater. The HTTP referer header is a misspelling and it is still there.
  • If a break is genuinely unavoidable: versioning, as a last resort — see the reference.
3. Authentication: make the simplest safe path easy

Many server-to-server integrations start life as a curl or a 20-line script. For developer-facing server-to-server APIs, default to simple, scoped, revocable API keys.

  • Use OAuth or another short-lived or sender-constrained flow instead for browser/mobile clients, user-delegated access, high-sensitivity data, or environments where policy requires it. Do not ship long-lived bearer credentials into those clients.
  • For every credential type, define scope, rotation, revocation, secure transport, and a way to identify or disable the credential during an incident.
  • N/A for internal credential ergonomics: use the mechanism the infrastructure already provides (mTLS, workload identity, service tokens), while still verifying its operational controls.
4. Authorization: enforce who may do what to which resource

Authentication identifies a caller; it does not authorize an action. For every endpoint, identify the actor, action, resource, and tenant boundary.

  • Enforce authorization server-side on the resolved resource. Do not trust a caller-supplied tenant_id, owner ID, role, or scope without checking it against the authenticated principal.
  • Apply the same checks to list, search, bulk, export, nested-resource, and indirect lookup paths; filtering after fetching is not an authorization boundary.
  • N/A only for intentionally anonymous public operations, with a one-line reason. For security-sensitive changes, require a dedicated security review in addition to these API gates.
5. Idempotency on anything that takes action

A 500 or a timeout tells the caller nothing about whether the action happened. Without an idempotency key, the caller must choose between a lost operation and a duplicate one.

  • Every operation that is not already idempotent and creates, triggers, or applies a relative change accepts an idempotency key (header or param); repeat keys return the original result instead of acting twice.
  • Keep it optional for low-stakes operations where an occasional duplicate is cheaper than added adoption friction.
  • When a duplicate is unacceptable — payments, transfers, medication, irreversible external side effects — require an idempotency key or an intrinsic unique operation ID, and enforce deduplication atomically with the effect.
  • Not needed for reads (harmless) or DELETE /comments/32 (the ID is the key — the retry just 404s). Exception: non-ID-scoped operations like "delete the most recent".
  • Storage recipe in references/patterns.md.
Show full SKILL.md (753 more words)Show less
6. Blast radius, rate limits, killswitch

UI users are limited by the speed of their hands. Anything you expose via API is called at the speed of code, forever, in a loop, by someone who read no docs.

  • Before shipping: write down what one caller in a tight while true loop costs you. Fan-outs, /index endpoints, bulk imports, and anything doing per-record work in a request are the dangerous ones.
  • Rate limit everything, with tighter limits on expensive operations.
  • Return X-RateLimit-Remaining and Retry-After so well-behaved clients can back off — that metadata is what lets you set stricter limits than you otherwise could.
  • Keep a per-consumer killswitch. You will need it during an incident caused by an integration you never imagined.
7. Pagination
  • Any collection that could plausibly grow large: cursor-based, always. WHERE id > :cursor ORDER BY id LIMIT :n stays fast at record one million; OFFSET gets slower every page and the migration away from it later is expensive.
  • Bounded-forever collections (a user's API keys, a project's 5 environments): page/offset is fine.
  • Never return an unbounded list. Always include next_page (URL or cursor) so consumers don't compute it.
8. Expensive fields are optional and off by default

If a field needs an extra service call, a join over a big table, or a computation, don't put it in the default response.

  • Gate it behind ?include=subscription / an includes[] array; keep the default response cheap and constant-cost.
  • This is the useful 20% of the GraphQL idea without the cost.
  • Don't propose GraphQL unless the user asks or the codebase is already GraphQL: high barrier for non-engineers, arbitrary client-crafted queries complicate caching and multiply edge cases, and the backend is fiddlier. It's a last resort, not a default.
9. No implementation leakage

Read the response as a stranger. Does using it correctly require knowing how you store things?

  • Leaks: next_comment_id chains the client must walk; a POST /fetch_job + poll dance for what should be a GET; internal enum values; internal table IDs; pagination whose page size depends on your shard layout.
  • Either hide it behind a boring interface, or state the debt explicitly in the PR — don't let it slip into a public contract unremarked.

Deliberately not gates

Guard against over-design as hard as under-design:

  • Don't build versioning machinery up front. A /v1/ prefix is itself a public product choice, not a free placeholder. Adopt path or header versioning only when the product's compatibility policy calls for it; do not build multi-version negotiation before a second version exists.
  • Don't add includes or cursors to internal endpoints with one caller and a bounded result set. The Pagination and Expensive fields gates are about potentially large or expensive responses. For Idempotency, caller count does not remove retry risk: omit it only when the operation is already idempotent or duplicate effects are explicitly acceptable.
  • Don't rewrite a working API to be prettier. Prettiness is not worth a compatibility break, and it isn't worth the review time either.
  • Remember API quality is marginal. If the product is valuable, people integrate with a terrible API (Facebook, Jira). If it isn't, a beautiful API won't save it. API quality decides between two roughly equivalent products; having no API at all is the real defect. So: apply these gates, don't gold-plate past them.

Review output format

When reviewing rather than writing, report only findings that survive verification and skip taste. For repository code, specs, and diffs, cite file:line. For published contracts outside the repository, cite a stable URL and exact section; source-code evidence must use an immutable commit permalink, not a moving branch. A missing public guarantee means consumers cannot rely on the behavior; it does not prove that the backend lacks an undocumented implementation. Give a gate ✓ only when the reviewed evidence supports it. When repository context is available, inspect beyond the diff instead of treating silence as a pass. If the input is intentionally limited and further evidence is unavailable, use ? (unverified: <reason>); reserve N/A for a gate that truly does not apply. Gate summaries evaluate the artifact under review, not the hypothetical state after suggested fixes. Order: breaks first, security boundaries second, incidents third, ergonomics last.

## API review: <surface>
Scope: public|internal · greenfield|existing

### Breaking changes (blocking)
- <field/endpoint> — <what breaks for a consumer doing X> — file:line
  Fix: <additive alternative>

### Security boundary
- <authentication/authorization finding> — <credential or unauthorized action/resource> — file:line

### Incident risk
- <idempotency/blast-radius finding> — <the loop or retry that hurts> — file:line

### Ergonomics
- <boring/pagination/field-cost/implementation-leak finding> — file:line

### Gates: Boring <status> · Compatibility <status> · Authentication <status> · Authorization <status> · Idempotency <status> · Blast radius <status> · Pagination <status> · Expensive fields <status> · No implementation leakage <status>

If nothing survives, say so plainly — an empty review is a valid result.

References

  • references/breaking-changes.md — compatibility matrix, versioning playbook, deprecation sequence. Read before changing any existing endpoint.
  • references/patterns.md — implementation recipes: idempotency keys, cursor pagination, rate-limit headers, includes.
  • references/examples.md — three compact, local examples: an existing route/spec diff, a greenfield proposal, and an established HTTP RPC route. Read only when a concrete calibration example is useful.

© AmazingAng, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in skills/old-coder-api of AmazingAng/old-coder.

  • SKILL.md
  • references/breaking-changes.md
  • references/examples.md
  • references/patterns.md

Open the folder on GitHubat commit a0eb529

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in AmazingAng/old-coder, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Old Coder API Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Old Coder API Design compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Old Coder API Design this skillAmazingAng/old-coder7491 repos~3.4kAutomated safety check: PassMIT
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
OpenAPI Spec Generationwshobson/agents40k9 repos~511Automated safety check: PassMIT
API Design Patternsrohitg00/awesome-claude-code-toolkit2.7k—~1.2kAutomated safety check: PassApache-2.0
API DesignWrongStack/WrongStack368—~1.3kAutomated safety check: PassMIT
API Contract Designrsmdt/the-startup536—~1.1kAutomated safety check: PassMIT

Similar skills

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed

  • OpenAPI Spec Generation

    wshobson/agents

    Create, validate and maintain OpenAPI 3.1 specs for REST APIs, whether designed first or generated from existing code, and use them for docs and client SDKs.

    40k GitHub starsUsed in 9 repos~511 tokens
    Backend & APIsAuto-check passed

  • API Design Patterns

    rohitg00/awesome-claude-code-toolkit

    REST API design with resource naming, pagination, versioning, and OpenAPI spec generation

    2.7k GitHub stars~1.2k tokensUpdated 4 mo ago
    Backend & APIsAuto-check passed

  • API Design

    WrongStack/WrongStack

    A skill your agent uses when designing, implementing, or reviewing an HTTP API — endpoints, request and response shapes, errors, pagination, versioning, and authorization.

    368 GitHub stars~1.3k tokensUpdated today
    Backend & APIsAuto-check passed

  • API Contract Design

    rsmdt/the-startup

    REST and GraphQL API design patterns, OpenAPI/Swagger specifications, versioning strategies, and authentication patterns.

    536 GitHub stars~1.1k tokensUpdated 2 mo ago
    Backend & APIsAuto-check passed

  • API Design

    epam/ai-dial-chat

    Design, review, or change HTTP API contracts for AI DIAL Chat.

    504 GitHub stars~1.2k tokensUpdated today
    Backend & APIsAuto-check passed

More from AmazingAng/old-coder

  • Evidence-First Development Loop

    AmazingAng/old-coder

    Replaces line-by-line code review with an approved executable spec and a gauntlet of tests, types, coverage, and mutation checks the code must survive.

    749 GitHub stars~5.4k tokensUpdated 1 mo ago
    Auto-check: notes

Works with

Categories

Questions about Old Coder API Design

What does Old Coder API Design do?

Reviews or designs an HTTP/JSON API's endpoints, auth, pagination, versioning and deprecations, guarding against inventing a bespoke interface or silently breaking consumers. Before designing anything, the skill has the agent answer three scoping questions out loud: whether the API is public or internal, since internal APIs can tolerate breaking changes that public ones cannot; whether it is an existing surface or greenfield, since an existing surface must run the breaking-changes reference first because compatibility outranks every other improvement; and whether the product's resource model actually supports the shape being proposed, naming an awkward underlying resource model instead of papering over it.

When should I use Old Coder API Design?

Old Coder API Design fits situations like: adding or changing an HTTP endpoint; reviewing an OpenAPI spec or a route diff for breaking changes; deciding whether an API change is safe to ship without warning consumers.

How do I install Old Coder API Design in Claude Code?

Run `npx skills add AmazingAng/old-coder --skill old-coder-api -a claude-code`. Or copy the skill folder (skills/old-coder-api in AmazingAng/old-coder) into .claude/skills/old-coder-api in your project. Claude Code loads it when a task matches its description.

How do I install Old Coder API Design in Codex?

Run `npx skills add AmazingAng/old-coder --skill old-coder-api -a codex`. Or copy the skill folder (skills/old-coder-api in AmazingAng/old-coder) into .agents/skills/old-coder-api in your project. Codex loads it when a task matches its description.

Can I use Old Coder API Design in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AmazingAng/old-coder --skill old-coder-api -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/old-coder-api, .gemini/skills/old-coder-api, .github/skills/old-coder-api and .opencode/skills/old-coder-api in your project.

What does Old Coder API Design need to run?

SKILL.md names no scripts, command-line tools or credentials: Old Coder API Design is instructions for the agent only.

Does Old Coder API Design access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Old Coder API Design safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Old Coder API Design use?

Old Coder API Design is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Old Coder API Design use?

About 3.4k tokens (SKILL.md is roughly 14k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.4k tokens, read only when the agent opens those files.

What are the alternatives to Old Coder API Design?

Skills that share tags, products or a category with Old Coder API Design: API Designer (Jeffallan/claude-skills, 12k stars), OpenAPI Spec Generation (wshobson/agents, 40k stars), API Design Patterns (rohitg00/awesome-claude-code-toolkit, 2.7k stars) and API Design (WrongStack/WrongStack, 368 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Old Coder API Design?

AmazingAng (a GitHub user) maintains it in AmazingAng/old-coder, which has 749 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on August 18, 2026.

Source: AmazingAng/old-coder on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.