From api-first
Use when starting any task that touches an API or a module boundary, before writing any implementation code
How this skill is triggered — by the user, by Claude, or both
Slash command
/api-first:api-first-workflowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Note on API types:** This workflow applies to all API types — the contract format and backward-compat tool differ by type. In v1, two types are implemented:
Note on API types: This workflow applies to all API types — the contract format and backward-compat tool differ by type. In v1, two types are implemented:
references/http-tooling.mdname + description); compat check = frontmatter diff script; see references/plugin-tooling.mdWhen DB, queue, gRPC, or code interface skills are added (v1.1+), they each provide a {type}-tooling.md reference. The core steps remain identical.
Before touching any code or spec:
REQUIRED SUB-SKILL: api-first:module-boundaries
SOFT REFERENCE: modularity:balanced-coupling — full three-dimensional coupling model if installed
Before any implementation code:
api/{service}/v1.yaml), bump info.versionname, description) — this IS the contract; write frontmatter before writing skill bodyREQUIRED SUB-SKILL: api-first:api-design (for HTTP)
See references/plugin-tooling.md (for plugin interfaces)
references/http-tooling.md for exact commandsreferences/plugin-tooling.mdOn breaking change in a stable (v1+) API:
v2.yaml (HTTP) or bump the plugin's major versionREQUIRED SUB-SKILL: api-first:api-versioning (on breaking change or version decision)
Apply TDD:
Never implement first, then write the test. The test is the spec's executable form.
All four layers must pass (Layer 4 is conditional on the framework) plus the custom agent-friendliness suite before proceeding.
REQUIRED SUB-SKILL: api-first:api-testing
docs/agent-integration.mdShips in the same commit as the API change. See references/agent-integration-format.md for the required format, the intent→endpoint table, and the token lifecycle section.
Update triggers: new endpoint, behaviour change, auth/rate-limit/error-format change, idempotency strategy change.
Verify before committing: all tests pass, no regressions, staged files include the spec change, the implementation, the docs update, and any regenerated client files.
One commit — not three.
Non-negotiable:
x-agent-* extensions, resolvable errors, documented intent) applied from the first commitAsk first:
Never:
If you catch yourself thinking any of these, stop and re-read this skill:
x-agent-* extensions later when we have agent consumers"conflicting_id"agent-integration.md is just duplicate docs"x-agent-* annotations because "no agents use this yet"If you realize mid-task that you violated Step 1:
git stash).Shortcut: none. The point of the discipline is that the spec shapes the implementation, not the other way around.
references/http-tooling.md — oasdiff, client generation, pytest, CI (HTTP/REST)references/plugin-tooling.md — frontmatter schema, compat script, Layer 4 validation (plugin interfaces)references/agent-integration-format.md — required sections for docs/agent-integration.mdnpx claudepluginhub u-abramchuk/skills --plugin api-firstSearches 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.