Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

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ść.

Repozytorium
skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
19.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 19.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Approach
  2. Gotchas
  3. Finish
  4. References
Sekcje z nagłówków SKILL.md, w oryginale · 35 linii, 420 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.