api2cli: Скилл для генерации CLI из API

--- name: api2cli description: Generate a working CLI from any API, then wrap it in a Claude Code skill. Point it at API docs, a live URL, or a peek-api capture and get a dual-mode Commander.js CLI (human + agent output) plus a ready-to-use skill folder. Use when user wants to wrap an API in a CLI, generate a CLI from API docs, turn an API into a command-line tool, scaffold a CLI from discovered endpoints, or create a skill for an API. --- # api2cli Generate a working Node.js CLI from any API, then wrap it in a Claude Code skill. Discovers endpoints, scaffolds a dual-mode Commander.js CLI with a full-featured API client, and creates a skill folder so Claude knows how to use it. ## Workflow 1. **Identify the API** -- user provides a docs URL, a live API base URL, or a peek-api capture 2. **Discover endpoints** -- parse docs, probe the API, or read a peek-api catalog 3. **Build endpoint catalog** -- normalize all discovered endpoints into a standard format 4. **Generate CLI** -- scaffold Commander.js CLI from the catalog 5. **User chooses destination** -- scaffold into current project or create standalone project 6. **Generate skill** -- create a SKILL.md that teaches Claude how to use the generated CLI ## Step 1: Identify the API Ask the user: - "What API do you want to wrap? Share a docs URL, a base URL, or point me at a peek-api capture." Determine which discovery paths to use based on what they provide: | Input | Discovery Path | |-------|---------------| | Docs URL (e.g., `https://docs.stripe.com/api`) | Docs parsing + active probing | | Base URL (e.g., `https://api.example.com/v1`) | Active probing | | peek-api capture dir (e.g., `./peek-api-linkedin/`) | Read existing catalog | | Live website URL | Suggest running peek-api first, then active probing | Also ask: - "What auth does this API use?" (API key, Bearer token, cookies, OAuth, none) - "Do you want this CLI in your current project or as a standalone project?" ## Step 2: Discover Endpoints Use all applicable discovery paths. Combine results into a single catalog. ### Path A: Docs Parsing 1. Fetch the docs URL with WebFetch 2. Extract endpoint information: method, path, description, parameters, request/response examples 3. Look for pagination patterns, auth requirements, rate limit info 4. Follow links to sub-pages for individual endpoint docs if the main page is an index ### Path B: Active Probing 1. Check well-known paths for API specs: - `/.well-known/openapi.json`, `/.well-known/openapi.yaml` - `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml` - `/api-docs`, `/docs`, `/api/docs` - `/graphql` (with introspection query) 2. Try `OPTIONS` on the base URL and common resource paths 3. Probe common REST patterns: `/api/v1/`, `/api/v2/`, `/v1/`, `/v2/` 4. For each discovered resource, try standard CRUD: `GET /resources`, `GET /resources/:id`, `POST /resources`, etc. 5. Parse response shapes to understand data models 6. Check response headers for rate limit info (`X-RateLimit-*`, `Retry-After`) 7. Check for pagination patterns in responses (`next`, `cursor`, `page`, `offset`) See `references/discovery-strategies.md` for detailed probing patterns. ### Path C: peek-api Capture 1. Read the capture directory: `endpoints.json`, `auth.json`, `CAPTURE.md` 2. Parse endpoints into the standard catalog format 3. Extract auth headers and cookies from `auth.json` If peek-api is not installed or no capture exists, tell the user: ``` To capture endpoints from a live site, install peek-api: git clone https://github.com/alexknowshtml/peek-api cd peek-api && npm install node bin/cli.js https://example.com ``` ## Step 3: Build Endpoint Catalog Normalize all discovered endpoints into this format: ```typescript interface EndpointCatalog { service: string; // e.g., "stripe", "nexudus" baseUrl: string; auth: { type: 'api-key' | 'bearer' | 'cookies' | 'oauth' | 'none'; headerName?: string; // e.g., "Authorization", "X-API-Key" envVar: string; // e.g., "STRIPE_API_KEY" }; pagination?: { style: 'cursor' | 'offset' | 'page' | 'link-header'; paramName: string; // e.g., "starting_after", "offset", "page" responseField: string; // e.g., "has_more", "next", "next_page_url" }; rateLimit?: { requests: number; window: string; // e.g., "1m", "1h" }; resources: ResourceGroup[]; } interface ResourceGroup { name: string; // e.g., "customers", "invoices" description: string; endpoints: Endpoint[]; } interface Endpoint { method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; path: string; // e.g., "/v1/customers/:id" description: string; parameters: Parameter[]; requestBody?: object; // JSON schema or example responseExample?: object; } interface Parameter { name: string; in: 'path' | 'query' | 'header'; required: boolean; type: string; description: string; } ``` Present the catalog to the user for review before generating: ``` Found 24 endpoints across 5 resources: customers (6 endpoints): list, get, create, update, delete, search invoices (5 endpoints): list, get, create, send, void ... Ready to generate the CLI? ``` ## Step 4: Generate CLI Generate a dual-mode CLI using Commander.js. The CLI auto-detects human vs agent output via `process.stdout.isTTY`. ### File Structure **In-project scaffold:** ``` scripts/ {service}.ts # Entry point with shebang {service}/ lib/ client.ts # API client (auth, pagination, retry, caching) envelope.ts # Agent JSON envelope helpers commands/ {resource}.ts # One file per resource group ``` **Standalone project:** ``` {service}-cli/ package.json tsconfig.json bin/ {service}.ts # Entry point with shebang src/ lib/ client.ts envelope.ts commands/ {resource}.ts ``` ### Code Generation Patterns See these references for the patterns to apply during generation: - `references/api-client-template.md` -- API client class with pagination, retry, rate limiting, caching - `references/agent-first-patterns.md` -- JSON envelope, HATEOAS next_actions, context-safe output, error fix suggestions - `references/commander-patterns.md` -- Commander.js subcommands, global options, interactive prompts, colored output ### Key Generation Rules **Entry point (`{service}.ts`):** - Shebang: `#!/usr/bin/env npx tsx` - Self-documenting root command (no args → prints full command tree as JSON) - Global options: `--json` (force JSON output), `--verbose`, `--config <path>` **API client (`lib/client.ts`):** - Constructor takes base URL + auth config - Auth from env var (name based on `catalog.auth.envVar`) - Built-in pagination matching the API's pattern - Retry with exponential backoff for 5xx and 429 errors - Rate limiting based on discovered limits - Optional response caching **Envelope helpers (`lib/envelope.ts`):** ```typescript const isAgent = !process.stdout.isTTY; function respond(command: string, result: any, nextActions: Action[] = []) { if (isAgent) { console.log(JSON.stringify({ ok: true, command, result, next_actions: nextActions })); } else { return result; // caller handles human rendering } } function respondError(command: string, message: string, code: string, fix: string, nextActions: Action[] = []) { if (isAgent) { console.log(JSON.stringify({ ok: false, command, error: { message, code }, fix, next_actions: nextActions })); } else { console.error(`Error: ${message}`); console.error(`Fix: ${fix}`); } process.exit(1); } ``` **Command files (`commands/{resource}.ts`):** - One file per resource group - Each endpoint becomes a subcommand: `mycli customers list`, `mycli customers get <id>` - `list` commands: support `--limit`, `--offset`/`--cursor`, `--status` (if filterable) - `get` commands: take ID as argument - `create`/`update` commands: accept `--data <json>` or individual `--field` flags - Every command includes contextual `next_actions` for agent mode - Errors include `fix` suggestions **Standalone project extras:** - `package.json` with `commander`, `tsx` as dependencies, `bin` field pointing to entry - `tsconfig.json` for TypeScript - `.env.example` with the required env var ## Step 5: Verify After generating the CLI: 1. **Verify it runs:** Execute with no args, confirm the self-documenting root works 2. **Test one endpoint:** Pick a simple GET endpoint, run it, verify output 3. **Move on to Step 6** to wrap the CLI in a skill ## Step 6: Generate Skill Create a Claude Code skill folder that teaches Claude how to use the generated CLI. This is the final step -- it turns the CLI into something any Claude session can pick up and use without reading the code. ### Skill Structure ``` .claude/skills/{service}/ SKILL.md # Skill instructions ``` ### SKILL.md Template Generate a SKILL.md with this structure: ```markdown --- name: {service} description: Interact with the {Service} API via CLI. Use when user wants to {list of actions based on discovered resources, e.g., "list customers, create invoices, check order status"}. Commands: {service} {resource} {action}. --- # {Service} CLI CLI wrapper for the {Service} API. ## Setup Set the `{SERVICE_ENV_VAR}` environment variable: ```bash export {SERVICE_ENV_VAR}=your-api-key-here ``` ## Commands {For each resource group, list commands with examples:} ### {Resource} ```bash # List {resources} npx tsx {path/to/cli}.ts {resource} list # Get a specific {resource} npx tsx {path/to/cli}.ts {resource} get <id> # Create a {resource} npx tsx {path/to/cli}.ts {resource} create --field value ``` ## Common Workflows {Generate 2-3 practical workflows combining multiple commands:} ### Example: {Workflow name} ```bash # Step 1: Find the customer npx tsx {path/to/cli}.ts customers list --status=active # Step 2: Get their invoices npx tsx {path/to/cli}.ts invoices list --customer-id=abc123 ``` ## Agent Usage When piped, all commands return JSON with `next_actions`: ```bash npx tsx {path/to/cli}.ts {resource} list | cat ``` ``` ### Key Rules for Skill Generation 1. **Description is critical** -- include specific trigger phrases and list the actions the CLI supports. This is what Claude reads to decide when to use the skill. 2. **Include real command examples** -- use the actual CLI path and real subcommand names from the generated CLI. 3. **Generate practical workflows** -- combine multiple commands into realistic multi-step scenarios based on how the API's resources relate to each other. 4. **Keep it lean** -- the skill should be a quick reference, not a restatement of `--help`. Focus on what Claude needs to know that it can't infer. ### Tell the User After generating both the CLI and the skill: ``` CLI generated at {cli_path} Skill generated at .claude/skills/{service}/SKILL.md To use the CLI directly: npx tsx {cli_path} # See all commands npx tsx {cli_path} customers list # List customers Claude will now automatically use this skill when you ask about {service}. ``` ## Reference Files - `references/discovery-strategies.md` -- Detailed probing patterns, well-known paths, GraphQL introspection, response parsing - `references/api-client-template.md` -- Full API client class with pagination, retry, rate limiting, caching - `references/agent-first-patterns.md` -- Agent JSON envelope, HATEOAS, context-safe output, error handling - `references/commander-patterns.md` -- Commander.js subcommands, nested commands, interactive prompts, colored output, config files, testing