openapi-skill

Development project for the openapi-reader Claude Code plugin — token-efficient access to OpenAPI specifications.

Structured output is emitted as TOON (Token-Oriented Object Notation). Combined with the built-in junk-token trimmer, the plugin delivers ~58% fewer bytes than raw JSON on the shipped fixture without semantic loss. See src/openapi-reader/README.md for format details and docs/EVAL.md for the current measurement report.

Accepts OpenAPI 3.x JSON specs from either a local file or an HTTP(S) URL (--spec path.json or --spec https://…/openapi.json). Swagger 2.0 loads with a warning — most subcommands work, but schema lookups require 3.x (components/schemas).

Install

Inside Claude Code:

/plugin marketplace add paul-basanets/claude_openapi_skill
/plugin install openapi-reader@basanets-plugins
/reload-plugins

See src/openapi-reader/README.md#installation for local-directory and manual-copy install modes.

Structure

.claude-plugin/         marketplace catalog (basanets-plugins)
src/openapi-reader/     plugin source (see its README for usage)
├── .claude-plugin/     plugin manifest (v0.5.5)
├── commands/           /openapi slash command
├── scripts/            openapi_tool.py — zero-dep Python CLI + TOON encoder
└── skills/openapi/     skill guidance + query-patterns reference

evals/run_eval.py       evaluation harness (12 UX scenarios + population-wide metrics)
docs/EVAL.md            generated evaluation report
bundle.py               builds dist/openapi-reader.zip
dist/                   build output

Development

The tool is stdlib-only, so no venv is required to run it — python is enough. A venv is only useful for dev work (linters, the eval harness, etc.):

# macOS / Linux
python -m venv .venv && source .venv/bin/activate

# Windows (Git Bash, which Claude Code uses)
python -m venv .venv && source .venv/Scripts/activate

Then test the CLI against the fixture (use python3 on Linux/macOS systems where the python alias isn't provided):

python src/openapi-reader/scripts/openapi_tool.py summary
python src/openapi-reader/scripts/openapi_tool.py endpoint POST /api/resource/add
python src/openapi-reader/scripts/openapi_tool.py schema ResourceResponse

Build

python bundle.py
# → dist/openapi-reader.zip