From api-first
Use when auditing an existing OpenAPI spec or plugin skill inventory, reviewing a service or plugin for api-first compliance, or identifying design gaps in an existing API
How this skill is triggered — by the user, by Claude, or both
Slash command
/api-first:api-reviewingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Two review modes:**
Two review modes:
Calibrate review effort before applying the full checklist:
securitySchemes and contract strength; verify the boundary encapsulates provider details| Checklist section | Default severity | Rationale |
|---|---|---|
| Module boundary health | FAIL | Boundary violations compound — fix before merge |
| Spec quality | FAIL | Contract errors mislead all consumers |
| Agent-friendliness | FAIL for hard rules (x-agent-*, format: date-time, conflicting_id); WARN for documentation gaps (intent table, token lifecycle) | Hard rules are testable; documentation gaps are fixable post-merge |
| Design quality | FAIL for 422 misuse, missing idempotency; WARN for missing consistency model | |
| Versioning hygiene | FAIL for breaking changes in minor; WARN for missing Sunset header | |
| Testing coverage | WARN (blocking only if spec drift tests are entirely absent) |
Override with judgment: a WARN in a core subdomain may warrant FAIL treatment.
/projects/{id} — that belongs in project-service)operationId (camelCase verb+noun)Error componentapi-first:api-design)Error component has: code, detail, correlation ID — consistent naming across all services{"items", "total", "offset", "limit"} envelope; empty state returns full envelope, never nullsecuritySchemes; all routes require auth except observability + authentication endpointsinfo.version follows full semver (1.2.0, not 1.2)/openapi.json exposed without auth (capability discovery)x-agent-retryable setx-agent-timeout setx-agent-idempotency header name set on operations supporting Idempotency-KeyTOKEN_EXPIRED vs TOKEN_INVALID (vs TOKEN_REVOKED, INSUFFICIENT_SCOPE) error codesconflicting_id (or equivalent)format: date-timedocs/agent-integration.md has intent→endpoint table and token lifecycle sectionapplication/merge-patch+json and return the full resourceparameters with defaults stateddetail messages are actionable — consumer can fix without reading source codegit log -- api/)deprecated: true + Sunset headerinfo.descriptiontests/test_openapi.py) including x-agent-* and format: date-time checkstest_agent_friendliness.py exists (idempotency, token codes, pagination accuracy, 429 header)test_generated_spec.py exists for services with framework-generated specs (FastAPI, Flask-RESTX, DRF)## API Review: {service}
### Subdomain: {core | supporting | generic} — {brief justification}
### Summary
- X failures (blocking)
- Y warnings (should fix)
- Z info findings
### Failures
- [FAIL] {path} {method}: {issue}. Fix: {actionable fix}
### Warnings
- [WARN] {path} {method}: {issue}. Suggestion: {suggestion}
### Module boundary findings
- [INFO] {observation}
name and description in frontmatterdescription follows "Use when [specific conditions]" format — a trigger phrase, not a summaryplugin-name:skill-name format (no bare paths)REQUIRED SUB-SKILL: and SOFT REFERENCE: markers used consistentlyplugin.jsondescription changes that alter when the skill fires without a major version bumpplugin.json version field follows semver and is currentplugin.json has name, version, skills path (Claude Code/Cursor)package.json has main pointing to OpenCode loader (if OpenCode supported)## Plugin Review: {plugin-name}
### Subdomain: {core | supporting | generic} — {brief justification}
### Summary
- X failures (blocking)
- Y warnings (should fix)
### Failures
- [FAIL] {skill-name}: {issue}. Fix: {actionable fix}
### Warnings
- [WARN] {skill-name}: {issue}. Suggestion: {suggestion}
api-first:api-design (HTTP mode)api-first:api-versioningapi-first:module-boundariesapi-first-workflow/references/plugin-tooling.md (plugin mode)modularity:review — deeper coupling analysis across the full codebaseNote: This skill defines the review process. A future api-spec-reviewer agent (v1.2) will apply it to a specific spec file automatically.
Searches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Implements vector databases with Pinecone, Weaviate, Qdrant, Milvus, pgvector for semantic search, RAG, recommendations, and similarity systems. Optimizes embeddings, indexing, and hybrid search.
npx claudepluginhub u-abramchuk/skills --plugin api-first