Skip to content
Skills Library
Programming · Planning

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.

Licence
MIT
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

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

  1. STOP - Read before ANY tool call
  2. Trigger
  3. Outcome
  4. Lazy-load (only when needed)
  5. Reference routing
  6. Process
  7. Must not
  8. Handoff
Original SKILL.md headings · 125 lines, 767 words
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

RepositoryScoreLicence
This page · tibursocampos/agent-dev-toolkit100MIT
andreibesleaga/gabbe100CC-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.