Add OpenAPI spec transformer Claude Code skill

[web3jenks]

Summary

• Add a fully autonomous Claude Code skill for transforming Swagger 2.0 API specs to OpenAPI 3.0.0
• Checked into .claude/skills/ so any collaborator who clones the repo gets it automatically
• Updated .gitignore to track skills but exclude local Claude Code settings

What the skill does

Converts API specs from babylonlabs-io/babylon and babylonlabs-io/staking-api-service (Swagger 2.0) into the OpenAPI 3.0.0 format required by docusaurus-plugin-openapi-docs, with:

• Tag reorganization (single "Query" tag → 10 module-specific tags)
• Server endpoint configuration (mainnet/testnet/local)
• Schema name cleanup (removes ugly Go package paths)
• Enum normalization (v1 snake_case, v2 SCREAMING_SNAKE_CASE, x-enum-varnames)
• x-tags schema grouping by API version
• Sidebar.ts empty Schemas category fix
• Live API endpoint validation
• Full site build verification

Files

File	Purpose
.claude/skills/openapi-spec-transformer/SKILL.md	Main skill definition (557 lines)
.claude/skills/openapi-spec-transformer/references/examples.md	Before/after examples
.claude/skills/openapi-spec-transformer/references/tag-mapping.md	Path-to-tag rules
.claude/skills/openapi-spec-transformer/references/servers.md	Server endpoints
.gitignore	Ignore .claude/settings.local.json, track skills

How to use

1. Open Claude Code in the repo directory
2. The skill is auto-discovered from .claude/skills/
3. Type: Update the API specs from source repositories
4. Claude runs all 8 steps autonomously
5. Review the summary and validate locally with npm run serve

Test plan

• Clone repo fresh — verify skill appears in Claude Code
• Run the skill — verify it fetches both source Swagger AND current specs
• Verify diff summary shows endpoint counts
• Verify npm run build passes after transformation

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR primarily adds a Claude Code skill (checked into .claude/skills/) to autonomously transform upstream Swagger 2.0 specs into the OpenAPI 3.0.0 format used by this Docusaurus documentation site, and includes reference material to guide consistent transformations.

Changes:

• Added the openapi-spec-transformer Claude skill with an end-to-end, autonomous workflow for fetching, transforming, validating, and regenerating API docs.
• Added reference docs for tag mapping, server endpoints, and before/after transformation examples.
• Updated .gitignore for Claude local settings, and added a new BABE research guide page.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/guides/research/babe_verification.mdx	Adds a new research guide page linking to the BABE paper PDF.
.gitignore	Ignores Claude local settings file; also adds ignore patterns for tests/ and test-results/.
.claude/skills/openapi-spec-transformer/SKILL.md	Defines the autonomous Swagger 2.0 → OpenAPI 3.0 workflow and repo update steps.
.claude/skills/openapi-spec-transformer/references/examples.md	Provides before/after examples for key transformation patterns.
.claude/skills/openapi-spec-transformer/references/tag-mapping.md	Documents path-prefix → tag rules and x-tagGroups structure.
.claude/skills/openapi-spec-transformer/references/servers.md	Documents server URLs and basic endpoint checks for validation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The download commands use curl -sL, which can silently write an HTML error page on 404/5xx and still exit 0. To make the autonomous workflow reliably fail fast (as the step text requires), use curl flags that fail on HTTP errors (e.g., include -f) and consider adding basic retry/backoff.

Suggested change

	curl -sL -o /tmp/babylon-swagger2.yaml \
	https://raw.githubusercontent.com/babylonlabs-io/babylon/main/client/docs/swagger-ui/swagger.yaml
	# Staking API spec
	curl -sL -o /tmp/staking-swagger2.yaml \
	curl -fsSL --retry 3 --retry-delay 5 -o /tmp/babylon-swagger2.yaml \
	https://raw.githubusercontent.com/babylonlabs-io/babylon/main/client/docs/swagger-ui/swagger.yaml
	# Staking API spec
	curl -fsSL --retry 3 --retry-delay 5 -o /tmp/staking-swagger2.yaml \

[Copilot]

npx swagger2openapi ... without a version pin makes the transformation non-reproducible over time and may prompt for interactive install confirmation, which can break an autonomous run. Pin the tool version (and run in non-interactive mode) so collaborators get consistent output.

Suggested change

	npx swagger2openapi /tmp/babylon-swagger2.yaml -o /tmp/babylon-openapi3-base.yaml
	npx swagger2openapi /tmp/staking-swagger2.yaml -o /tmp/staking-openapi3-base.yaml
	npx --yes swagger2openapi@7.0.8 /tmp/babylon-swagger2.yaml -o /tmp/babylon-openapi3-base.yaml
	npx --yes swagger2openapi@7.0.8 /tmp/staking-swagger2.yaml -o /tmp/staking-openapi3-base.yaml

[Copilot]

The path→tag mapping here looks incomplete relative to the Babylon gRPC spec currently in-repo (e.g., it contains /babylon/zoneconcierge/... endpoints). As written, any Babylon module not listed will fall into an implicit fallback (often other) and lose module grouping; consider adding mappings for all /babylon/<module>/ prefixes present in the source/current specs (or define an explicit rule for unmapped modules, plus ensure the corresponding tags/x-tagGroups exist).

[Copilot]

This prefix→tag table appears to cover only a subset of Babylon gRPC modules. The current spec in static/swagger/babylon-grpc-openapi3.yaml includes additional /babylon/<module>/... prefixes (e.g., zoneconcierge) that wouldn’t match anything here, which can lead to inconsistent tagging/grouping during transformation. Consider extending the mapping (and x-tagGroups) to include all Babylon module prefixes present in the source/current specs, or document a clear fallback strategy.