refactor: backend api skill

[nicolas-angelo]

Summary

Refactors the clerk-backend-api skill from a monolithic SKILL.md into a CLI-style command system with three self-contained agents: docs, request, and types.

Changes

Architecture

• SKILL.md → thin router (~80 lines): command table, global help, output style rules, and delegation logic
• Agent files under agents/: each command is a standalone markdown file (docs.md, request.md, types.md)
• Shared reference (references/api-specs.md): spec resolution, filesystem caching, output directory rules, and scope enforcement — consumed by all agents
• Scripts reorganized to scripts/openapi/ for clarity

docs — Browse and inspect API endpoints

Browse the OpenAPI spec without executing requests. Modes: list tags, browse tag endpoints, or inspect a specific endpoint schema.

/clerk-backend-api docs — list all API tags
/clerk-backend-api docs Users — browse endpoints for a tag
/clerk-backend-api docs GET /users — inspect endpoint schema
/clerk-backend-api docs GET /users -v 2025-11-10 — inspect using a specific spec version

request — Execute API requests

Resolve an endpoint from the spec, prompt for required parameters, enforce scope rules on write operations, and execute.

/clerk-backend-api request GET /users — fetch all users
/clerk-backend-api request POST /invitations — create an invitation (prompts for params)
/clerk-backend-api request DELETE /users/user_123 — delete with scope check

types — Generate TypeScript types from dashboard data

Fetches live data from the Clerk API (/organization_roles, /organization_permissions, /role_sets, /billing/plans) and generates TypeScript types using bundled templates.

/clerk-backend-api types sync — generate all types
/clerk-backend-api types sync roles permissions — filter by category
/clerk-backend-api types sync --dry-run — preview without writing
/clerk-backend-api types sync plans --overwrite — skip confirmation

Categories: roles, permissions, plans
Output: <project_root>/.clerk/types/types.ts and constants.ts

Spec caching

• Default: reads bundled assets/api-spec.yml (no network)
• -v 2025-01-01: checks <project_root>/.clerk/.cache/openapi/<version>.yml, fetches + caches if missing
• --no-cache: force-fetches latest from GitHub, updates bundled spec

Global options

• -o, --out [dir] — output directory (default: <project_root>/.clerk/)
• -v, --version [date] — use a specific spec version
• --no-cache — bypass cache, fetch fresh from GitHub

Docs

Updated README, CLAUDE.md, marketplace.json, and plugin.json with new command structure and directory layout.

Test Commands

Global

• /clerk-backend-api → prints global help with all three commands
• /clerk-backend-api --help → same

docs

• /clerk-backend-api docs --help → prints docs help without loading spec
• /clerk-backend-api docs → lists API tags from bundled spec
• /clerk-backend-api docs Users → lists endpoints for Users tag
• /clerk-backend-api docs GET /users → shows endpoint schema

request

• /clerk-backend-api request --help → prints request help
• /clerk-backend-api request GET /users → executes and returns response

types

• /clerk-backend-api types --help → prints types help without fetching API data
• /clerk-backend-api types sync --dry-run → prints generated types without writing
• /clerk-backend-api types sync roles permissions → generates only filtered categories