API Conventions
Interní REST pravidla, která Claude aplikuje při návrhu endpointů: tvar URL, data/error/meta, 422
Otestováno · Funguje
Co umí
Referenční dovednost, která načítá pevně danou sadu REST konvencí, když Claude píše nebo reviduje API endpointy: množné kebab-case URL zdrojů s maximálně dvěma úrovněmi vnoření, povinná obálka odpovědi data/error/meta, tabulka stavových kódů, která směruje selhání obchodní logiky na 422, Bearer autentizace s @public opt-out a verzování cesty /api/v1. Spouští se na požadavky na návrh nového endpointu, výběr formátu odpovědi nebo revizi tvaru existující trasy a chybových odpovědí. Pravidla jsou pevně zakódovaná a subjektivní, takže před použitím na skutečném projektu si SKILL.md forkněte a vložte do něj vlastní standardy.
Testovací report
Nainstalováno do dočasného HOME=$(mktemp -d) a potvrzeno, že SKILL.md se umístil do ~/.claude/skills/api-conventions/SKILL.md; frontmatter parsován pomocí yaml.safe_load (name, 273znakový description, allowed-tools Read/Grep/Glob), tělo má 1231 znaků odkazujících na nula externích souborů a grep na curl|base64|eval|http://|/Users/ nenašel nic. Stejný úkol dvakrát — „navrhnout endpointy pro výpis kupónů zákazníka a jeden uplatnit“ — baseline.md vs skill.md v poznámkovém bloku: baseline vrátila holý objekt {"coupons":[...],"page","per_page","total"}, POST /api/coupons/{code}/redeem vracející 200 a 409/410 pro již uplatněné/vypršené; verze dovednosti vrátila {"data":[...],"error":null,"meta":{page,limit,total}} na každou odpověď, přesunula akci na POST /api/v1/coupons/{code}/redemptions vracející 201, sloučila 409 a 410 do 422, přidala případ vlastnictví 403 a explicitně uvedla autentizaci jako Bearer + anotaci @public na jednom otevřeném endpointu. Spouštěcí fráze, které jsem posoudil jako načtení: „přidejte REST endpoint pro výpis faktur uživatele — jak by mělo vypadat URL a tělo odpovědi?“, „zkontrolujte tento soubor Express trasy a řekněte mi, zda jsou chybové odpovědi správné“, „navrhujeme nové veřejné API pro objednávky — jaký stavový kód pro validaci selhání?“; posouzeno jako nenačtení: „napište Python klienta, který volá Stripe API a opakuje pokusy při 429“ (konzumace, ne návrh) a „endpoint /users vrací 500, pomozte mi najít null deref“ (ladění za běhu, ne formát) — 5/5 správně. Skutečná výhrada: jedná se o demo kurzu, takže konvence jsou pevně zakódovány do stylu jednoho autora a polovina prózy v těle je čínština.
Testováno: 2026-07-21 · Claude Code 2.x (agent harness)
Instalace
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). Příkazy a ukázkové prompty
/api-conventionsInterní REST pravidla, která Claude aplikuje při návrhu endpointů: tvar URL, data/error/meta, 422
Skilly se spouštějí běžnými požadavky — žádné příkazy k zapamatování. Po instalaci ho aktivují prompty jako tyto (anglicky):
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards