api-standards
/api-standards
Apply agnostic HTTP/API design standards (REST shape, versioning, errors, naming) without company contracts. Use when designing or reviewing APIs or invoking /api-standards.
- Author
- tibursocampos ↗
- Repository
- agent-dev-toolkit ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 9
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Apply agnostic HTTP/API design standards (REST shape, versioning, errors, naming) without company contracts. Use when designing or reviewing APIs or invoking /api-standards.
Original author description
Apply agnostic HTTP/API design standards (REST shape, versioning, errors, naming) without company contracts. Use when designing or reviewing APIs or invoking /api-standards.
How it works
- STOP - Read before ANY tool call
- Trigger
- Outcome
- Lazy-load (only when needed)
- Reference routing
- Process
- Must not
- Handoff
SKILL.md preview
---
name: api-standards
description: Apply agnostic HTTP/API design standards (REST shape, versioning, errors, naming) without company contracts. Use when designing or reviewing APIs or invoking /api-standards.
---
## STOP - Read before ANY tool call
1. Read `{{GUARDRAILS_PATH}}`
2. Read `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/SESSION.md`; load session-state for `$Cwd`
3. If the relevant gate is not approved: **STOP** - ask user **(pt-BR)** - do **NOT** Write/Shell
4. SDD/develop skills: after **ONE** step/task, **STOP** session - handoff only
5. This skill body is **English**; user-facing prompts may be **(pt-BR)**
### Step -1 - Gate check (report in chat before continuing)
```
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] PIPELINE.md read (SDD skills only)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
```
---
# Skill: api-standards
## Trigger
**Negative signal:** Do not activate this skill when the request lacks one of the positive signals below or its required context; topic similarity or an isolated keyword alone is insufficient.
Invoke when the user requests: `/api-standards`, `api standards`, `REST conventions`, or asks for agnostic HTTP/API design guidance (not typed client generation).
**Arguments (optional):**
| Input | Meaning |
|-------|---------|
| Focus area | `rest` \| `versioning` \| `errors` \| `naming` \| `security` — load only that playbook |
| Artifact path | Existing OpenAPI / route map / controller folder to review against standards |
## Outcome
Agnostic API design guidance applied to the current workspace or design discussion:
1. Clear HTTP/REST shape recommendations (methods, status codes, resource URLs).
2. Versioning, error envelope, pagination, and naming conventions without vendor or company branding.
3. Security hygiene checklist that never embeds live secrets or proprietary contracts.
4. Handoff to `api-integrate` when the user needs OpenAPI → typed clients (out of scope here).
## Lazy-load (only when needed)
| When | Path (after syncing the active adapter) |
|------|----------------------------------------|
| Command playbook (step discovery after gates) | `{{TOOLKIT_ROOT}}/skills/api-standards/references/command.md` |
| Caveman Mode (if active) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md` - **Full cap** |
| Selective retrieval | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/SELECTIVE-RETRIEVAL.md` |
| Reference index (routing only) | `{{TOOLKIT_ROOT}}/skills/api-standards/reference.md` |
| Process step detail (lazy) | `{{TOOLKIT_ROOT}}/skills/api-standards/references/<section>.md` |
**Never by default:** do not preload all `references/*.md`, full OpenAPI dumps, `memory-bank/`, or PRD bodies. Do not load `api-integrate` playbooks unless handing off client generation. Load **one** `references/<section>.md` per Process step (`SKILL-REFERENCE-RETRIEVAL.md`).
## Reference routing
| Situation | Path |
|-----------|------|
| Step discovery after gates | `references/command.md` |
| REST / HTTP shape | `references/rest-http.md` |
| Versioning | `references/versioning.md` |
| Errors and pagination | `references/errors-pagination.md` |
| Naming and resource contracts | `references/naming-contracts.md` |
| Security (agnostic) | `references/security-agnostic.md` |
| Must not (full) | `references/must-not.md` |
## Process
After gates: **Read `references/command.md`** for ordered step discovery. Then load **one** `references/<section>.md` per step — **not** full `reference.md`.
### Step -1b - Caveman Mode (Full cap)
1. Read `{{SDD_ROOT}}/preferences.json` (create `{ "caveman_mode": false, "caveman_level": "full" }` if missing).
2. If `caveman_mode` is false: continue without compression.
3. If true: load `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md`; apply **Full** participation cap + prefs `caveman_level` (Lite skills never escalate); show once: `[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.`
4. Honor `caveman on|off|status|lite|full|ultra` (and `stop caveman` / `normal mode`) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per `CAVEMAN.md`.
### -1. Re-check guardrails and session
Confirm `guardrails.mdc` and `SESSION.md` are loaded. If missing, ask **(pt-BR)** before continuing.
### 0. Scope and focus
* Confirm the ask is **standards / design review**, not typed client generation (that is `api-integrate`).
* If the user named a focus area, load only that playbook; otherwise ask once which areas matter (max three).
* Apply selective retrieval (`SR-NO-FULL-DUMP`): paths + short excerpts only.
### 1. Inspect current surface (optional)
* If an artifact path exists, skim routes / OpenAPI / controllers for gaps vs loaded standards.
* Do not rewrite large APIs in one pass — prefer a short gap list with severity.
### 2. Apply standards
* Load the matching `references/*.md` section(s) one at a time.
* Produce agnostic recommendations (English identifiers; chat language for prose).
* Never invent company-specific product names, internal contract ids, or branded error codes.
### 3. Report and handoff
* Summarize recommendations and open questions.
* For OpenAPI → clients/DTOs: hand off to `api-integrate`.
* Offer `/commit` only if files were changed in the consumer repo.
## Must not
* Embed company, vendor, or product-specific API contracts, naming schemes, or branding.
* Generate typed API clients / DTOs (use `api-integrate`).
* Hardcode credentials, tokens, base URLs with secrets, or unretracted `.env` values.
* Dump entire `memory-bank/` or paste full PRD/OpenAPI into the session (`SELECTIVE-RETRIEVAL.md`).
* Pretend this skill replaces stack `*-developer` implementation work.
## Handoff
```
api-integrate - <openapi-or-schema-path>
```
Or continue with the stack skill for implementation after standards are agreed.
Files in this package (9)
- SKILL.md 6 KB
- reference.md 1 KB
- references/command.md 1 KB
- references/errors-pagination.md 1 KB
- references/must-not.md 1 KB
- references/naming-contracts.md 1 KB
- references/rest-http.md 1 KB
- references/security-agnostic.md 1 KB
- references/versioning.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · tibursocampos/agent-dev-toolkit | 100 | MIT |
| andreibesleaga/gabbe | 100 | CC-BY-4.0 |
Database snapshot: 13.11.2026 · package version 810a615390a2 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100design-api
Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract". - 100api-design
REST API design patterns for resource naming, HTTP methods, status codes, pagination strategy, error envelopes, versioning, and rate limiting. Use when designing, reviewing, or refactoring HTTP APIs and endpoint contracts. - 100common-api-design
Apply REST API conventions — HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework. Use when designing endpoints, choosing HTTP methods, implementing pagination, or writing OpenAPI specs. - 100common-api-design
Apply REST API conventions — HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework. Use when designing endpoints, choosing HTTP methods, implementing pagination, or writing OpenAPI specs. - 100http-api-guidelines
This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards. - 90api-design
API design patterns: REST naming/pagination/errors, GraphQL schema design, gRPC streaming, versioning strategies, idempotency keys, rate limiting. Use when designing APIs.