api2skill 0.7.1

api2skill

Convert an OpenAPI/Swagger document into a self-contained Agent Skill package — a SKILL.md plus scripts and reference docs — so an existing REST API becomes something any agent that supports the Agent Skills standard can call correctly, with authentication, without you hand-writing the wrapper. Works with Claude, Cursor, and other compatible hosts.

api2skill generate ./petstore.json
# -> ./swagger-petstore/
#      SKILL.md               # compact overview + auth setup + operation index
#      reference/<tag>.md     # full per-operation detail, loaded on demand
#      scripts/call.cs        # the dispatcher (.cs by default; --script fsx|csx also available)
#      secrets.example.json   # template — copy to secrets.json and fill in real credentials
#      .api2skill.json        # generation manifest — records options for `update`
#      .gitignore             # excludes secrets.json

Drop the output directory into your host's skills root (for example ~/.claude/skills/, .claude/skills/, .cursor/skills/, or another Agent Skills–compatible path) and the agent can use it immediately.

Full documentation: wiki/Home.md — getting started, CLI reference, authentication, and Mermaid diagrams. Docs live in this repo under wiki/; see wiki/README.md for how to browse them. Planned directions: ROADMAP.md.

Why

Writing a correct, well-documented Agent Skill for an API by hand is repetitive: endpoint and parameter docs, auth handling, and example requests all have to be derived from the API's own OpenAPI spec anyway. api2skill automates that derivation.

Install

Requires the .NET 10 SDK.

dotnet tool install --global api2skill

Or build from source (this repo pins the SDK version via global.json):

dotnet build --configuration Release
dotnet run --project src/Api2Skill -- generate <spec> [options]

Quickstart

# From a local file
api2skill generate ./petstore.json

# From a running service (self-signed dev cert: add --insecure)
api2skill generate https://svc.local/swagger.json --insecure

# Custom name and output path — options are recorded in .api2skill.json
api2skill generate ./petstore.json --name my-petstore --out ./skills/my-petstore

# Refresh when the spec changes (reuses saved --script/--include/--out from manifest)
api2skill update ./skills/my-petstore ./petstore-v2.json
api2skill update ./skills/my-petstore   # re-fetch original spec source

# Rename or relocate while updating (secrets.json, auth.json, .auth-cache.json move with it)
api2skill update ./skills/my-petstore ./petstore-v2.json --name petstore-prod --out ./apis/petstore

# Install the creator skill so an agent can interview you and build generate/update commands
api2skill install-creator                          # TTY: pick Cursor / Claude / Copilot / Agentic
api2skill install-creator --target .cursor/skills --force

Then, inside the generated skill directory:

cp secrets.example.json secrets.json   # fill in real credentials
dotnet run scripts/call.cs -- getPetById --petId 3

Multi-spec (same base URL)

Several Swagger/OpenAPI docs against one host → one skill. Full guide: wiki/Multi-Spec-Skills.md. Interactive walkthrough (pick scenario → copy command): docs/interactive/multi-spec-guide.html — open in a browser, or follow wiki/Interactive-Guides.md for Cursor / Copilot Canvas, Claude Artifacts, and Codex sites.

# Compose docs at generate time (--base-url when servers disagree or are missing)
api2skill generate \
  --spec ./public.json --spec-id public \
  --spec ./admin.json --spec-id admin \
  --base-url https://api.example.com \
  --out ./skills/acme

# Merge skills you already generated separately (sources kept; secrets first-wins)
api2skill merge --into ./skills/acme ./skills/acme-public ./skills/acme-admin

# Append one OpenAPI file to an existing skill (not merge)
api2skill add-spec ./skills/acme ./billing.json --spec-id billing

# Refresh all parts, or replace one part's source
api2skill update ./skills/acme
api2skill update ./skills/acme ./new-admin.json --spec-id admin

Different auth per document → prefer auth.json with tag/global profiles (wiki/Authentication.md). For an agent-led setup, install api2skill-creator and use Cursor Plan mode (plan questions on auth, base URL, secrets, and merge vs generate before running CLI) — see wiki/Install-Creator.md.

Authentication (basics)

# Quick bearer token scaffold
api2skill generate ./api.json --auth bearer

# Auto-scaffold auth.json from OpenAPI security schemes (first generate, no --auth flags)
api2skill generate ./api.json --out ./my-skill
# → ./my-skill/auth.json (inactive template) + SKILL.md "Auth profile names" section
# Activate after editing:
api2skill generate ./api.json --auth-config ./my-skill/auth.json --force --out ./my-skill

# Full auth config (OAuth2, Entra, script commands, custom headers)
api2skill generate ./api.json --auth-config ./auth.json --login

--auth and --auth-config are mutually exclusive. See wiki/Authentication.md for profile types, Entra preset, script auth, and HTTPS loopback login (dotnet dev-certs, --cert / PEM flags).

Install creator skill

api2skill install-creator copies a bundled helper skill into project agent skill roots so an agent can ask about OpenAPI path(s), base URL, secrets placement, --out, --name, --script, --auth / --auth-config, --login, callbackUrl, --force, and --insecure — including multi-spec generate --spec, merge --into, add-spec, and multi-part update — then emit exact CLI commands.

For multi-spec interviews, prefer Plan mode so the agent plans those questions before emitting commands. Check for updates with api2skill creator check-update (bundled version matches the package <Version>). Supported roots (exactly four): .cursor/skills/, .claude/skills/, .github/skills/, .agents/skills/. Non-TTY runs require --target. Details: wiki/Install-Creator.md.

Project layout

src/Api2Skill/       the generator (console app)
tests/Api2Skill.Tests/   xUnit — unit, golden, and integration tests
wiki/                in-repo documentation (start at wiki/Home.md)
specs/               feature specs (Spec Kit)

Status

MVP complete: three script emitters (cs/fsx/csx), explicit auth (bearer, basic, custom, script, OAuth2/Entra), generate / update / merge / add-spec / install-creator, multi-spec composition (same base URL), filtering, and atomic output staging. See specs/001-openapi-to-skill/spec.md and specs/012-multi-spec-skill/spec.md.