# API Skill

[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)

API Skill is a local OpenAPI/Swagger workspace for frontend and agent-assisted development. It has one human-facing workspace and two agent-facing interfaces that share the same cached API documents:

- Web app, for people: import, browse, search, inspect, test, version, and manually maintain API operations.
- CLI, for AI agents and automation: check document availability, retrieve focused API context, maintain documents, and start local services with predictable commands.
- MCP server, for AI agents: expose the same query and maintenance actions directly to Codex or other MCP clients.

## Web App Usage

After installing from npm, start the web app from any project directory:

```bash
npm install -g apiskill
apiskill run web
```

Web, CLI, and MCP all use the same user-writable `~/.apiskill/cache` directory by default. `--cwd` only changes the Web process working directory and never changes this shared cache. For an isolated cache, set the same absolute `APISKILL_CACHE_DIR` for every Web, CLI, and MCP process. When developing this repository, you can also start it from the project root:

```bash
npm install
npm run dev
```

Open the local URL shown in the terminal. The New Document dialog can import a direct OpenAPI JSON/YAML URL, crawl a Swagger UI / Knife4j / Redoc page, upload a local file, execute a curl command that returns an OpenAPI document, or create a blank document from scratch.

Cache Settings in the upper-right corner shows the active session cache and changes the saved default. The setting is stored in `~/.apiskill/config.json`; changing it never moves or deletes existing files. Restart Web to use the new location, or use Update Cache Location in version management to copy selected versions there. CLI uses the same setting:

```bash
apiskill cache show
apiskill cache set /absolute/path/to/apiskill-cache
apiskill cache reset
```

`APISKILL_CACHE_DIR` remains the highest-priority temporary override for automation and isolated runs.

After importing or creating a blank document, use the version selector to switch cached documents, search endpoints by path, summary, tag, method, or parameter text, and open endpoint tabs to inspect request parameters, request bodies, response fields, AI-ready context, and raw JSON. You can also add, edit, or delete manual API operations; those changes are saved as local cached versions.

After API document data exists, click Start MOCK Service in the web app or run `apiskill mock` in CLI to start a local random-data MOCK API server from the current interface definitions.

### AI Agent Quick Start

```bash
# 1. Check whether API documentation is ready
apiskill check

# 2. Initialize the cache when no document exists
apiskill import https://example.com/openapi.json
apiskill crawl https://example.com/swagger
apiskill import-file ./openapi.yaml
apiskill document create --title "My API" --doc-version 1.0.0

# 3. Retrieve only the API context needed for the current coding task
apiskill versions
apiskill query /api/v1/users --method GET

# 4. Start a local random-data API from the active document
apiskill mock
```

CLI and MCP are primarily designed for AI coding agents. Agents should check the cache first, initialize it only when needed, and query a focused endpoint instead of reading the entire OpenAPI document. Run `apiskill --help` for all CLI commands. In MCP clients, start with `apiskill_check`, use `apiskill_search_endpoints` or `apiskill_query_api` to locate an API, and call `apiskill_help` for the complete tool list.

### AI Agent CLI CRUD Protocol

Use `--json` on commands that support it and parse the response instead of scraping human-readable output. For an isolated project cache, set `APISKILL_CACHE_DIR` to an absolute writable directory before every CLI call. Without it, the global installation uses `~/.apiskill/cache`.

1. Check the cache, then create a blank document when no upstream document exists:

```bash
apiskill check --json
apiskill document create --title "My API" --doc-version 1.0.0 --description "Local API contract" --json
```

Read `meta.versionId` from the create response and reuse that exact value for every write. `api create` now defaults to the latest version when `--version` is omitted, but agents should still pass it explicitly so every write targets the intended project document.

2. Save an API configuration as `api-config.json`:

```json
{
  "api": {
    "method": "post",
    "path": "/api/v1/users/{id}",
    "summary": "Create user",
    "operationId": "createUser",
    "tags": ["Users"],
    "parameters": [
      { "name": "id", "location": "path", "required": true, "type": "string" }
    ],
    "requestBody": {
      "required": true,
      "contentType": "application/json",
      "fields": [
        { "name": "name", "type": "string", "required": true },
        { "name": "email", "type": "string", "format": "email" }
      ]
    },
    "responses": [
      {
        "status": "200",
        "description": "User created",
        "contentType": "application/json",
        "fields": [
          { "name": "success", "type": "boolean", "required": true },
          { "name": "userId", "type": "string" }
        ]
      }
    ]
  }
}
```

3. Create, inspect, edit, and delete the operation:

```bash
APISKILL_VERSION_ID="value-from-meta.versionId"

apiskill api create --version "$APISKILL_VERSION_ID" --file ./api-config.json --json
apiskill api list --version "$APISKILL_VERSION_ID" --query user --method POST --json
apiskill api query POST '/api/v1/users/{id}' --version "$APISKILL_VERSION_ID" --format cli

# Edit the returned CLI config and save it as api-config.updated.json.
# POST and the path below identify the original operation; the file contains its replacement.
apiskill api edit POST '/api/v1/users/{id}' --version "$APISKILL_VERSION_ID" --file ./api-config.updated.json --json

# Use the replacement method/path if the edit changed either value.
apiskill api delete PATCH '/api/v1/users/{id}' --version "$APISKILL_VERSION_ID" --json
```

For a batch of operations, pass the same `APISKILL_VERSION_ID` to every command. For compatibility with older CLI releases, an agent should wait for each write to finish before starting the next one, then verify the final set:

```bash
apiskill api create --version "$APISKILL_VERSION_ID" --file ./users.get.json --json
apiskill api create --version "$APISKILL_VERSION_ID" --file ./users.create.json --json
apiskill api create --version "$APISKILL_VERSION_ID" --file ./users.delete.json --json
apiskill api list --version "$APISKILL_VERSION_ID" --json
```

The current CLI also serializes writes to the same cache across processes, so an AI tool that accidentally launches these commands in parallel will not lose earlier operations.

Agent rules:

- `api query` defaults to JSON and does not accept `--json`; use `--format cli` for a normalized configuration that can be edited and written back.
- `api edit ORIGINAL_METHOD ORIGINAL_PATH` locates the old operation. The replacement config may change its method or path.
- Quote paths containing `{id}` or other shell-sensitive characters.
- `api list --query` searches operation metadata and parameters, not response field names. Use exact `api query METHOD PATH` when method and path are known.
- A blank document with zero paths makes `check --json` return `ok: false` until at least one API is added. The document still exists; inspect `versionsCount` and `latestVersion`.
- Missing operations and invalid commands return a nonzero process exit code. Agents should treat that as failure and inspect stderr.
- `--config '<json-or-yaml>'` is equivalent to `--file`; files are safer for large or nested configurations.
- After a batch write, run `api list --version ... --json` and verify that every expected method/path exists before reporting success.
- OpenAPI identifies an operation by its method/path pair. Creating the same pair again intentionally replaces it; `meta.paths` counts distinct paths, not the total number of operations.

## Why This Tool Exists

Since large AI models became available, the way developers use AI for coding has changed quickly. At first, many of us worked in the ChatGPT web UI by copying code, errors, and API documentation back and forth. Later, tools such as Cursor, Codex, and Claude Code made it possible for AI assistants to work inside an entire project, so the workflow moved from isolated prompts toward project-aware development.

API documentation workflows changed along the way too. The earliest pattern was to paste API docs or upload screenshots. Then tools such as Context7 made it possible for AI assistants to read web-based API documentation directly. That is a big improvement, but it still leaves several practical problems:

- Reading and parsing web documentation consumes extra tokens and often adds noticeable waiting time, especially for large Swagger, Knife4j, or product docs.
- Internal documentation often requires authentication, cookies, network access, or other access-key handling before an AI tool can read it.
- Even when the AI can read the documentation, it usually cannot edit the API documentation itself or maintain a local versioned contract for the project.

API Skill was created to close that gap. It imports, crawls, creates, queries, edits, and versions API documentation locally, then exposes the same structured contract through the web app, CLI, and MCP server. The goal is to make API docs a project-level tool that AI assistants can reliably use and maintain, rather than a blob of pasted text or a screenshot.

### Token Efficiency

The exact saving depends on document size, schema depth, and how much surrounding conversation the task needs, but the practical pattern is consistent:

| Workflow | Typical context sent to the model | Reuse | Expected token impact |
| --- | --- | --- | --- |
| Screenshot of docs | Image tokens plus visual parsing of the whole visible page | Low | High cost, harder to quote exact fields |
| Pasted docs text | Full page text, navigation, examples, and often many unrelated endpoints | Low to medium | Often thousands to tens of thousands of tokens per task |
| Web-doc readers such as Context7 | AI reads and summarizes web documentation at request time | Medium | Better than manual paste, but still pays for page retrieval, parsing, and often broad documentation context |
| CLI/MCP targeted query | One endpoint or schema in structured JSON/Markdown | High | Commonly reduces API-document context by about 70-95% |
| MCP search then endpoint lookup | Small candidate list, then exact endpoint details | High | Best for large API sets; often avoids sending more than a few hundred to a few thousand tokens |

A conservative example: if a copied Knife4j/Swagger page or exported text for a module is 10,000-30,000 tokens, a targeted `apiskill_get_endpoint` or `apiskill_query_api` response for one endpoint is often 500-2,000 tokens. That is roughly a 5x to 60x reduction for the documentation portion of the prompt. The saving compounds across repeated frontend, backend, and test tasks because the imported document stays local and does not need to be pasted again.

Web-doc readers such as Context7 are useful when the documentation is public and the task needs fresh upstream reference material. For internal API docs or repeated product work, API Skill is more predictable because the document is already imported, access handling happens once, and the AI can query or edit a narrow local contract instead of re-reading broad web pages.

The bigger gain is not only lower token usage. Structured lookups reduce irrelevant context, make field names and required flags easier to preserve, and let the assistant fetch more detail only when the current task actually needs it.

### Overall Cost Effectiveness

API Skill has a small setup cost: install dependencies, import or crawl the document, and configure CLI or MCP access. After that, the same cache serves daily development work. The break-even point is usually reached quickly when a project has many endpoints, nested schemas, multiple developers, or repeated AI-assisted tasks.

The strongest return comes from:

- Reducing repeated prompt stuffing and screenshot interpretation.
- Giving agents deterministic tools for API discovery instead of relying on memory or visual extraction.
- Keeping local corrections when upstream docs lag behind implementation.
- Making API context available inside terminals, editors, MCP clients, and the web app without changing the source document.

For very small projects with only a few stable endpoints, copy-paste may be acceptable. For teams that repeatedly implement pages, services, mocks, or tests against changing API contracts, CLI/MCP access usually pays for itself through lower context cost and fewer integration mistakes.

### CLI vs MCP

CLI is the most portable and deterministic surface. It works in any shell, CI job, editor task, or AI tool that can run commands. For scripted bulk updates, import/export checks, and reproducible automation, CLI is usually faster to debug and easier to share. It can also be token-efficient when the user or automation calls exact commands and only pastes back concise results.

MCP is usually better for agent workflows. A compatible AI client can discover tools, call `apiskill_search_endpoints`, `apiskill_create_document`, `apiskill_create_api`, or `apiskill_get_endpoint` directly, and only receive structured results. This often saves prompt tokens because the user does not need to paste command output or full API documents into the conversation. The tradeoff is compatibility: MCP requires the AI tool to support stdio MCP servers and tool schemas, and different clients may vary in timeout handling, working-directory setup, approval UX, and how tool results are displayed.

Generated API content should be the same when CLI and MCP call the same shared core with the same payload. Choose CLI for universal automation and CI-friendly repeatability; choose MCP when an AI agent should autonomously search, create, edit, and query API documentation during coding.

### Project Integration Benefits

Frontend teams can query exact endpoint contracts while building pages, hooks, request clients, forms, tables, and validation logic. Response-field lookups make it easier to map API data into UI state without pasting an entire doc page into the prompt.

Backend teams can use the same cache to inspect existing contracts, compare manual changes, and expose temporary or corrected local operations before the upstream OpenAPI source is updated. This is useful when implementation and documentation are slightly out of sync.

Test automation can generate or review mocks, fixture payloads, contract assertions, and end-to-end setup from the same endpoint details used by frontend and backend work. Because CLI and MCP share the cache, tests can run against a known version instead of whatever a remote documentation site currently returns.

Agent workflows benefit most from MCP. A coding agent can call `apiskill_search_endpoints`, inspect the exact endpoint with `apiskill_get_endpoint`, fetch schema context with `apiskill_get_schema`, and then implement or update code with less manual prompting. That turns API documentation from a blob of text into a project-level tool.

## Documentation

- Web app: [English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
- CLI configuration and usage: [English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
- MCP configuration and usage: [English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

## Data Model

All surfaces read and write the same cache:

```text
cache/latest-import.json
cache/versions/
```

The web app and CLI can import remote or local OpenAPI documents. The MCP server can query the cache and, when explicitly called through write tools, import documents or create/edit/delete manual API operations.