Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add johnqtcg/awesome-skills --skill api-designgit clone --depth 1 https://github.com/johnqtcg/awesome-skillsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/johnqtcg/awesome-skills/api-design)<a href="https://agentmods.dev/skills/johnqtcg/awesome-skills/api-design"><img src="https://agentmods.dev/badge/skills/johnqtcg/awesome-skills/api-design/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/johnqtcg/awesome-skills/api-design"><img src="https://agentmods.dev/badge/skills/johnqtcg/awesome-skills/api-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>- NVIDIA SkillSpector pass
What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00123 | $0.07448 |
| Opus 5.5 | $0.00049 | $0.02979 |
| Sonnet 5.5 | $0.00025 | $0.01490 |
| Haiku 4.5 | $0.00012 | $0.00745 |
Grade A, and why
api-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 475 lines — stays where its author put it; the contents beside it link to each section on GitHub.
REST API Design Review
Quick Reference
| If you need to… | Go to |
|---|---|
| Understand what this skill covers | §1 Scope |
| Know how binding each rule is | §2 Rule Nature and Finding Severity |
| Check mandatory prerequisites | §3 Mandatory Gates |
| Choose review depth | §4 Depth Selection |
| Handle incomplete context | §5 Degradation Modes |
| Evaluate API design item by item | §6 Design Checklist |
| Avoid common API design mistakes | §7 Anti-Examples |
| Score the review result | §8 Scorecard |
| Format review output | §9 Output Contract |
| Deep-dive error model patterns | references/error-model-patterns.md |
| Check compatibility rules | references/compatibility-rules.md |
§1 Scope
In scope — REST API contract design and review:
- Resource modeling (URL structure, naming, hierarchy)
- HTTP method semantics (GET/POST/PUT/PATCH/DELETE)
- Status code selection (2xx/4xx/5xx semantic correctness)
- Error model design (machine-parseable codes, field-level details)
- Pagination, filtering, sorting, search patterns
- Idempotency (Idempotency-Key header, retry safety)
- Concurrency control (ETag, If-Match, optimistic locking)
- Auth/AuthZ per endpoint, IDOR prevention
- Rate limiting (per-actor, 429 + Retry-After)
- Versioning, backward compatibility, deprecation planning
- OpenAPI/Swagger contract generation
Out of scope — delegate to dedicated skills:
- API integration testing →
api-integration-test - gRPC/Protobuf design → separate skill
- Application code implementation →
go-code-reviewer
What ships with it
31 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
- references/api-anti-examples.md 7.5 KB
- references/compatibility-rules.md 10 KB
- references/error-model-patterns.md 10 KB
- scripts/lint_api_doc.py 33 KB runs code
- scripts/run_regression.sh 721 B runs code
- scripts/tests/COVERAGE.md 12 KB
- scripts/tests/golden/001_verb_in_url.json 1.6 KB
- scripts/tests/golden/002_200_for_errors.json 1.2 KB
- scripts/tests/golden/003_no_error_code.json 1.1 KB
- scripts/tests/golden/004_no_idempotency.json 1.8 KB
- scripts/tests/golden/005_idor_vulnerability.json 1.7 KB
- scripts/tests/golden/006_breaking_change.json 1.8 KB
- scripts/tests/golden/007_well_formed_crud.json 1.3 KB
- scripts/tests/golden/008_good_pagination.json 1.1 KB
- scripts/tests/golden/009_degraded_no_context.json 1.3 KB
- scripts/tests/golden/010_greenfield_design.json 1.6 KB
- scripts/tests/golden/011_no_rate_limit.json 1.5 KB
- scripts/tests/golden/012_legal_delete_200.json 1.8 KB
- scripts/tests/golden/013_403_denial_policy.json 2.0 KB
- scripts/tests/golden/014_last_write_wins.json 2.0 KB
- scripts/tests/golden/015_field_reorder_non_breaking.json 2.4 KB
- scripts/tests/golden/016_rfc9457_problem_details.json 1.9 KB
- scripts/tests/golden/017_error_leaks_internals.json 1.8 KB
- scripts/tests/golden/018_put_partial_update.json 1.4 KB
- scripts/tests/golden/019_validation_unspecified.json 1.5 KB
- scripts/tests/golden/020_unbounded_pagination.json 1.4 KB
- scripts/tests/golden/021_lww_false_premise.json 1.9 KB
- scripts/tests/golden/022_lww_honest_multiwriter.json 2.2 KB
- scripts/tests/test_doc_lint.py 11 KB runs code
- scripts/tests/test_golden_scenarios.py 15 KB runs code
- scripts/tests/test_skill_contract.py 24 KB runs code
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 1mo ago First seen · 475 lines · 123 tokens per session scan A 0d4cc7cc0428
api-design is a skill published in the GitHub repository johnqtcg/awesome-skills (30 stars, last pushed 16d ago), licensed MIT. It adds 123 tokens to every session and 7,448 once invoked, about $0.0005 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
api-designer
Design RESTful and RPC APIs — OpenAPI specs, request/response schemas, error codes, versioning, and documentation.
claude-api
Build apps with the Anthropic Claude API — chat completions, tool use, streaming, vision, and multi-turn conversations.
discord-bot
Create Discord bots — slash commands, embeds, voice, roles, threads, and Discord.js/Pycord implementations.
github-integration
Integrate with GitHub — Actions, Apps, webhooks, Octokit, and repository automation workflows.
graphql-builder
Design and implement GraphQL schemas — types, queries, mutations, subscriptions, resolvers, and federation.
mcp-builder
Scaffold and implement Model Context Protocol servers — tools, resources, prompts, and sampling handlers.