Bridge between agentskills.io skills and a local OpenAPI server.
An agentskills.io skill can contain rich supporting files beyond SKILL.md:
<skill-name>/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
Claude.ai's skill integration currently only reads SKILL.md. All optional subdirectories are invisible to the agent.
skill-openapi-bridge solves this with two commands:
generate— fetches a skill from GitHub at a pinned commit and produces a<skillname>-openapi-spec.jsonembedding all referenced file content as a valid OpenAPI 3.1.0 specserve— reads that spec and starts a local HTTP server inside the agent's container session, exposing all skill content via 25 REST routes following Progressive Disclosure
No external servers. No tunnels. Everything runs on localhost inside the container.
pip install skill-openapi-bridge
# or with uv:
uv add skill-openapi-bridgeShell tab completion (free via Typer):
skill-openapi-bridge --install-completionPin to a specific commit (recommended):
skill-openapi-bridge generate \
--repo https://github.com/roebi/agent-skills \
--commit abc123def456abc123def456abc123def456ab12 \
--skill skills/brainstorming-topic-dialog-creative-mentor-enAuto-resolve from branch:
skill-openapi-bridge generate \
--repo https://github.com/roebi/agent-skills \
--branch main \
--skill skills/brainstorming-topic-dialog-creative-mentor-enOutputs: brainstorming-topic-dialog-creative-mentor-en-openapi-spec.json
Custom output path:
skill-openapi-bridge generate \
--repo https://github.com/roebi/agent-skills \
--branch main \
--skill skills/brainstorming-topic-dialog-creative-mentor-en \
--output ./specs/brainstorming-en.jsonskill-openapi-bridge serve brainstorming-topic-dialog-creative-mentor-en-openapi-spec.json
# skill-openapi-bridge serving on http://127.0.0.1:52357
# READY on :52357Custom port and host:
skill-openapi-bridge serve spec.json --port 8080 --host 0.0.0.0The agent installs the package and starts the server:
pip install skill-openapi-bridge
skill-openapi-bridge serve brainstorming-topic-dialog-creative-mentor-en-openapi-spec.json &
sleep 1
curl http://localhost:52357/GET / HATEOAS root — skill list with full URLs
GET /<skill>/ Top-level entries
GET /<skill>/SKILL.md SKILL.md content
GET /<skill>/references/ Reference file listing
GET /<skill>/references/<ref> Reference file content
GET /<skill>/scripts/ Script file listing
GET /<skill>/scripts/<file> Script file content
GET /<skill>/assets/ Asset file listing
GET /<skill>/assets/<file> Asset file content
GET /list Human-readable skill list (HTML)
GET /to-prompt <available_skills> XML for all skills
GET /to-conventions Markdown conventions block for all skills
GET /validate JSON validation results for all skills
GET /meta JSON frontmatter for all skills
GET /pin JSON {commit, repo, path} for all skills
GET /find/<partial> 302 redirect to best matching SKILL.md
GET /schema/openapi.json OpenAPI 3.1.0 spec (all routes)
GET /schema/swagger Swagger UI
GET /<skill>/to-prompt <available_skills> XML for this skill
GET /<skill>/to-conventions Markdown conventions block for this skill
GET /<skill>/validate JSON validation result for this skill
GET /<skill>/meta JSON frontmatter for this skill
GET /<skill>/pin JSON {commit, repo, path} for this skill
GET /<skill>/schema/openapi.json OpenAPI 3.1.0 spec scoped to this skill
GET /<skill>/schema/swagger Swagger UI scoped to this skill
Content-Type: text/markdown; charset=utf-8
ETag: "sha256:<hex>"
Cache-Control: immutable, max-age=31536000
X-Skill-Name: <skill-name>
X-Skill-Commit: <full-commit-sha>
X-Content-SHA256: <hex>
Content is pinned to a commit — Cache-Control: immutable is correct and permanent.
GitHub repo (pinned commit)
|
| skill-openapi-bridge generate
v
<skillname>-openapi-spec.json (valid OpenAPI 3.1.0, all file content embedded)
|
| skill-openapi-bridge serve
v
localhost:<port> (pure stdlib HTTP server, in-container)
|
| curl / fetch — Progressive Disclosure
v
Agent
GET / Discovery — skill list + URLs
GET /<skill>/SKILL.md Activation — full skill instructions
GET /<skill>/references/x Loading — reference files on demand
- agentskills.io specification
- roebi/agent-skills — skill repository
- aider-skills — agentskills.io integration for aider
MIT