API Conventions
Wewnętrzne zasady REST, które Claude stosuje przy projektowaniu endpointów: kształt URL, data/error/meta, 422
Testowano · Działa
Co robi ten skill
Umiejętność referencyjna, która ładuje stały zestaw konwencji REST, gdy Claude pisze lub przegląda endpointy API: URL zasobów w liczbie mnogiej w formacie kebab-case z maksymalnie dwoma poziomami zagnieżdżenia, obowiązkowa obwiednia odpowiedzi data/error/meta, tabela kodów statusu, która kieruje błędy logiki biznesowej do 422, uwierzytelnianie Bearer z opcją @public opt-out oraz wersjonowanie ścieżki /api/v1. Uruchamia się na żądania zaprojektowania nowego endpointu, wyboru formatu odpowiedzi lub przeglądu kształtu istniejącej trasy i odpowiedzi na błędy. Zasady są zakodowane na stałe i subiektywne, więc rozwidl SKILL.md i zamień na własne standardy przed użyciem w prawdziwym projekcie.
Raport z testu
Zainstalowano w tymczasowym HOME=$(mktemp -d) i potwierdzono, że SKILL.md wylądował w ~/.claude/skills/api-conventions/SKILL.md; frontmatter sparsowany za pomocą yaml.safe_load (name, 273-znakowy description, allowed-tools Read/Grep/Glob), treść ma 1231 znaków odwołujących się do zera zewnętrznych plików, a grep dla curl|base64|eval|http://|/Users/ nic nie znalazł. To samo zadanie dwukrotnie — „design endpoints for listing a customer's coupons and redeeming one” — baseline.md vs skill.md w scratchpadzie: baseline zwrócił goły obiekt {"coupons":[...],"page","per_page","total"}, POST /api/coupons/{code}/redeem zwracający 200, i 409/410 dla już zrealizowanych/wygaśniętych; wersja umiejętności zwróciła {"data":[...],"error":null,"meta":{page,limit,total}} w każdej odpowiedzi, przeniosła akcję do POST /api/v1/coupons/{code}/redemptions zwracającego 201, połączyła 409 i 410 w 422, dodała przypadek własności 403 i uczyniła autoryzację jawną jako Bearer + adnotację @public na jednym otwartym endpointcie. Frazy wyzwalające, które oceniłem jako ładowane: „add a REST endpoint for listing a user's invoices — what should the URL and response body look like?”, „review this Express route file and tell me if the error responses are right”, „we're designing a new public orders API — what status code for a validation failure?”; ocenione jako nieładowane: „write a Python client that calls the Stripe API and retries on 429” (konsumowanie, nie projektowanie) i „the /users endpoint returns 500, help me find the null deref” (debugowanie w czasie wykonania, nie format) — 5/5 poprawnie. Prawdziwa uwaga: to demo kursu, więc konwencje są zakodowane na stałe w stylu jednego autora, a połowa prozy to chiński.
Testowano: 2026-07-21 · Claude Code 2.x (agent harness)
Instalacja
git clone --depth 1 https://github.com/huangjia2019/claude-code-engineering.git /tmp/api-conventions-src
mkdir -p ~/.claude/skills
cp -R /tmp/api-conventions-src/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions ~/.claude/skills/api-conventions
# Single self-contained SKILL.md (~1.7KB), no scripts, no deps, no API keys.
# Source repo is a Chinese course companion ("Claude Code 工程化实战") with 8+ demo skills;
# this slug is the 01-reference-skill example. Parts of the SKILL.md body (response-format
# and status-code notes) are written in Chinese; the rules themselves are language-neutral.
# IMPORTANT: the description says "conventions for this project" but the rules are the course
# author's, not yours. Edit ~/.claude/skills/api-conventions/SKILL.md to match your real
# standards, or it will push /api/v1, data/error/meta envelopes and 422 onto every codebase.
# frontmatter sets allowed-tools: Read, Grep, Glob (read-only). Komendy i przykładowe prompty
/api-conventionsWewnętrzne zasady REST, które Claude stosuje przy projektowaniu endpointów: kształt URL, data/error/meta, 422
Skille uruchamiają się na zwykłe polecenia — bez komend do zapamiętania. Po instalacji aktywują go prompty takie jak te (po angielsku):
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards