Przejdź do treści
Biblioteka skilli
AI i agenci · Konwersja i formaty

openapi-to-skill

/openapi-to-skill

Zamienia specyfikację OpenAPI lub Swagger (plik albo URL) w instalowalny skill, który uczy agentów kodujących poprawnie wywoływać dane API.

Repozytorium
accounted ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
04.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
4
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/openapi-inventory.mjs

Co robi i kiedy

Zamienia specyfikację OpenAPI lub Swagger (plik albo URL) w instalowalny skill, który uczy agentów kodujących poprawnie wywoływać dane API.

Wyzwalacze z opisu

build a skill for this APIgenerate a skill from this specmake our API docs agent-ready
Oryginalny opis (EN)

Turn an OpenAPI/Swagger spec (JSON or YAML, file or URL) into an installable agent skill that teaches coding agents how to call that API correctly. Use when the user says "build a skill for this API", "generate a skill from this spec", "make our API docs agent-ready", or points at an openapi.json / swagger.yaml and wants an integration skill. Produces a SKILL.md + references/ folder ready for `npx skills add`.

Jak działa

  1. Inputs
  2. Process
  3. Anti-patterns
Sekcje z nagłówków SKILL.md, w oryginale · 118 linii, 802 słów
Podgląd SKILL.md
---
name: openapi-to-skill
description: >-
  Turn an OpenAPI/Swagger spec (JSON or YAML, file or URL) into an installable
  agent skill that teaches coding agents how to call that API correctly. Use
  when the user says "build a skill for this API", "generate a skill from this
  spec", "make our API docs agent-ready", or points at an openapi.json /
  swagger.yaml and wants an integration skill. Produces a SKILL.md +
  references/ folder ready for `npx skills add`.
---

# OpenAPI spec to agent skill

You are building a **consumer-side skill**: a folder of distilled instructions
that lets an agent integrate correctly against an API on the first attempt.
The output is NOT a restatement of the spec. A spec restatement grades D: the
agent could have read the spec itself. The value you add is selection
(what matters), compression (condensed schemas), conventions (the cross-cutting
rules), and verification (what the live API actually does).

## Inputs

Collect these before starting (ask only for what is missing):

1. **Spec location**: file path or URL. If URL, download it next to your work.
2. **Output directory**: `skills/<api-name>/` in the repo when the skill will
   be distributed (installable via `npx skills add owner/repo --skill <api-name>`),
   `.claude/skills/<api-name>/` when it is for personal/project use only.
3. **Credentials for verification** (optional but strongly preferred): a base
   URL and an env var holding a low-privilege or test API key. Read-only
   verification only; never call write endpoints without explicit user consent.

## Process

### 1. Inventory the spec

Run the bundled tool (portable, stdlib-only Node):

```bash
node scripts/openapi-inventory.mjs <spec.json>              # overview: groups + one line per operation
node scripts/openapi-inventory.mjs <spec.json> --group <g>  # full detail for one group
```

YAML specs: convert first (`npx -y js-yaml spec.yaml > spec.json`).

The overview gives you: title, servers, auth schemes, operation count, and
operations grouped by tag (or by dominant path segment when the spec has no
tags). Read it fully before writing anything.

### 2. Extract the conventions

The conventions section is the most valuable part of the output skill: it is
what lets an agent predict endpoint behaviour instead of looking everything up.
Hunt for them in this order:

- `info.description`: many agent-first APIs state their invariants here.
- `components.securitySchemes`: auth header shape, token format, where keys
  come from (docs often say; if not, ask the user).
- Recurring response envelope: sample 3-4 operations with `--group` and
  compare. Note pagination style (cursor vs offset), error envelope, request
  id fields.
- Recurring parameters and headers: idempotency keys, dry-run flags, expand
  parameters, rate limits.
- `x-*` extensions: risk levels, scopes, idempotency markers. Surface them;
  they exist for agents.

If the spec is thin on conventions, check the API's human docs (ask the user
for the docs URL) rather than guessing.

### 3. Choose the reference grouping

Target 6 to 12 reference files. Merge tiny groups thematically (e.g.
`customers` + `articles` into `invoicing`); split any group that would exceed
roughly 500 lines rendered. Every operation must land in exactly one
reference file.

### 4. Write the skill

Follow `references/output-template.md` for the exact shape. Non-negotiables:

- **SKILL.md stays under ~400 lines.** Frontmatter description must name the
  API and its domain so the skill triggers (the agent sees only name +
  description at discovery time).
- **Conventions before endpoints.** Auth + base URL + envelope + pagination +
  error handling first; the endpoint index after.
- **Endpoint index**: one line per operation (`METHOD path : summary [badges]`),
  grouped, each group naming its reference file. The inventory tool's overview
  output is already in this format.
- **References**: start from `--group` output, then edit. Deduplicate
  boilerplate the spec repeats per operation (shared error lists, envelope
  wrappers) up into the conventions section, keep operation-specific pitfalls
  inline, and add a worked example (request + realistic response) for the 2-3
  most-used operations per group.
- **Schemas in condensed TypeScript-ish form**, never raw JSON Schema.

### 5. Verify against the live API

This step separates a usable skill from a plausible-looking one. Desk review
and live testing find different failure classes.

With credentials: smoke-test read-only endpoints (health/list endpoints, one
or two per group), using the exact auth header the skill documents. Compare
actual responses against the documented envelope and schemas. Every mismatch
is gold: record it in a **Gotchas** section in SKILL.md. Replace invented
examples with real (redacted) response bodies.

Without credentials: add a **Verification** section stating the skill was
generated from the spec and not yet tested live, with the smoke-test commands
a future session should run once a key exists.

### 6. Grade it

Score the output against the checklist at the bottom of
`references/output-template.md`. Fix what fails, once. Then report to the
user: what was generated, what was verified live vs. desk-only, and how to
install it (`npx skills add <owner>/<repo> --skill <name>`).

## Anti-patterns

- Restating the spec operation-by-operation with no selection or added
  operational knowledge.
- Raw JSON Schema dumps, or full request/response schemas for every endpoint
  when a condensed form plus one worked example carries more information.
- Auth buried mid-file. It is always the first section after the intro.
- Inventing example responses when a live call could have produced a real one.
- A giant single SKILL.md instead of progressive disclosure via references/.
- Skipping the grade step because the output "looks complete".
Pliki w paczce (4)
  • SKILL.md 6 KB
  • references/output-template.md 4 KB
  • scripts/openapi-inventory.d.mts 1 KB
  • scripts/openapi-inventory.mjs 16 KB

Wersje

W bazie nie ma innych skilli o nazwie openapi-to-skill.

Migawka bazy z 13.11.2026 · wersja paczki eaf1de286212 (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

  • 100openapi-to-mcp
    Buduje i wdraża serwer MCP ze specyfikacji OpenAPI lub Swagger przez SDK mcp-use w TypeScript, udostępniając API REST modelom takim jak Claude i ChatGPT.
  • 100postman-openapi-converter
    Konwertuje specyfikacje OpenAPI 3.x i Swagger 2.0 w YAML lub JSON na gotowe do importu pliki JSON kolekcji Postman v2.1.
  • 90backend-openapi-documentation
    Dokumentuje API metodą spec-first w OpenAPI 3.x, z generowaniem kodu i wersjonowanymi specyfikacjami.
  • 95api-documentation-generator
    Generuje specyfikacje OpenAPI i Swagger oraz dokumentację API z kodu albo projektu.
  • 90skavelo-skills-from-openapi
    Zamienia specyfikację OpenAPI lub Swagger w umiejętności Skavelo: odczyty danych konta użytkownika i działania zmieniające je dopiero po zatwierdzeniu.
  • 100api-docs
    Pisze dokumentację referencyjną lub specyfikację OpenAPI API na podstawie kodu źródłowego, np. listę endpointów i trasy.

Uwagi i zgłoszenia

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