public-api-design
/public-api-design
Projektuje i ocenia publiczne kontrakty dla deweloperów: API bibliotek, SDK, interfejsy wtyczek, endpointy HTTP, CLI, konfigurację i serwery MCP, także przy zmianach łamiących zgodność.
- Autor
- gustavovalverde ↗
- Repozytorium
- skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 19.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 6
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 19.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Projektuje i ocenia publiczne kontrakty dla deweloperów: API bibliotek, SDK, interfejsy wtyczek, endpointy HTTP, CLI, konfigurację i serwery MCP, także przy zmianach łamiących zgodność.
Oryginalny opis (EN)
Design or review developer-facing contracts such as library APIs, SDKs, plugin and extension interfaces, HTTP endpoints, CLIs, configuration, generated clients, and tools that agents call, such as MCP servers. Use when adding or changing a public surface, judging whether an API is easy to use correctly, or weighing a breaking change. Not for internal module boundaries with no outside consumers (software-design) or for writing endpoint documentation (docs-writing).
Jak działa
- Approach
- Gotchas
- Finish
- References
Podgląd SKILL.md
--- name: public-api-design description: Design or review developer-facing contracts such as library APIs, SDKs, plugin and extension interfaces, HTTP endpoints, CLIs, configuration, generated clients, and tools that agents call, such as MCP servers. Use when adding or changing a public surface, judging whether an API is easy to use correctly, or weighing a breaking change. Not for internal module boundaries with no outside consumers (software-design) or for writing endpoint documentation (docs-writing). license: MIT --- # Design a public API Start from the developer's task and the contract they consume, and make the common path direct without hiding the choices that matter. ## Approach Inspect representative callers, documentation, exported types, and relevant protocol or ecosystem conventions. Establish who depends on a surface before treating it as public; an internal export or database schema is not automatically one. Identify each kind of caller. Developers learn a surface from documentation, types, and examples. Agents choose an operation from its name, description, and schema alone, and act on its output without asking. The [agent caller checks](references/contract-review.md#serve-agent-callers) list what each needs. Write realistic common usage before choosing internal contracts. Include the setup and operation needed to complete the task, with inputs, results, and failure behavior. For an existing API, compare current and proposed usage. Label sketches as proposals rather than presenting invented calls as supported functionality. Separate necessary domain concepts and policy choices from implementation coordination. Hide wiring that callers should not need to manage, while keeping consequential choices, side effects, and resource ownership explicit. Judge the burden on callers rather than the number of methods or lines. Make the common path direct and idiomatic. Disclose advanced controls where demonstrated needs justify them, preserve required protocol concepts, and keep meaningful failure distinctions. Treat compatibility as part of the design. Account for existing consumers, wire formats, generated clients, and behavior before changing names, defaults, or types. A usability concern warrants a proportionate improvement, not an automatic breaking redesign. ## Gotchas - Multiple entrypoints or a shared handle can be right when they represent independent tasks, transactions, or lifetimes. - A convenient default can change the contract. Retries, idempotency, and atomicity do not follow from a simpler interface. - Fewer required arguments can still change behavior when a new default selects a different policy. - Text that agents or scripts parse is part of the contract, including error messages, output fields, and exit statuses. Rewording it can break them. - A compiling snippet does not prove the API is easy to use. Keep inspected examples, executed checks, and usability evidence distinct. ## Finish Check the canonical usage and public types as well as behavior, and exercise relevant errors, invalid setup, and integration boundaries. The [contract review](references/contract-review.md) lists the checks for each kind of surface. Present the proposed usage or concrete finding first, then the caller benefit, material tradeoffs, and migration implications. Scale the response to the decision. ## References - [Decision examples](references/examples.md) when weighing simpler setup against caller control or compatibility.
Pliki w paczce (6)
- LICENSE 1 KB
- SKILL.md 3 KB
- agents/openai.yaml 1 KB
- references/contract-review.md 6 KB
- references/examples.md 2 KB
- references/sources.md 2 KB
Wersje
W bazie nie ma innych skilli o nazwie public-api-design.
Migawka bazy z 13.11.2026 · wersja paczki 1c1395d32eb3 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100dx-audit
Audytuje powierzchnię CLI, SDK, biblioteki lub pakietu widoczną dla deweloperów: kontrakty API, błędy, typy publiczne, wdrożenie i konfigurację. - 90api-contracts
Projektuje lub zmienia kontrakt API dla nowych i istniejących klientów: endpointy, schematy, błędy, uwierzytelnianie i wersjonowanie. - 95api-design
Projektuje kontrakty REST i GraphQL przed implementacją oraz planuje przejścia wersji przy zmianach łamiących zgodność. - 100api-and-interface-design
Pomaga projektować stabilne API i granice modułów: publiczne interfejsy, endpointy REST i GraphQL oraz kontrakty typów między frontendem i backendem. - 95api-and-interface-design
Projektuje stabilne API i interfejsy: granice modułów, kontrakty typów oraz endpointy REST lub GraphQL między frontendem a backendem. - 100api-design
Pomaga projektować publiczne interfejsy bibliotek i narzędzi: minimalna powierzchnia, nazwy funkcji i flag CLI, konfiguracja, deprecjacje, projekt błędów i zmiany bez łamania użytkowników.