# 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은 프론트엔드 개발과 AI 보조 코딩을 위한 로컬 OpenAPI/Swagger 작업 공간입니다. 사람을 위한 Web 작업 공간과 AI Agent를 위한 CLI/MCP 인터페이스가 같은 캐시된 API 문서를 공유합니다.

- Web 앱: 사람이 API 문서를 가져오고, 탐색하고, 검색하고, 검사하고, 테스트하며 버전과 API 작업을 관리합니다.
- CLI: AI Agent와 자동화 작업이 문서 상태를 확인하고 필요한 API 컨텍스트를 조회하거나 유지 관리합니다.
- MCP 서버: 같은 API 조회 및 유지 관리 기능을 Codex 또는 다른 AI Agent 클라이언트에 제공합니다.

## Web 앱 사용

프로젝트 루트에서 시작합니다.

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

터미널에 표시되는 로컬 Vite URL을 엽니다. Web 앱은 직접 OpenAPI JSON/YAML URL 가져오기, Swagger UI / Knife4j / Redoc 페이지 크롤링, 로컬 파일 업로드, OpenAPI 문서를 반환하는 curl 명령 실행, 그리고 빈 문서를 처음부터 생성하는 흐름을 지원합니다.

가져오거나 새로 만든 뒤에는 버전 선택기로 캐시된 문서를 전환하고, 경로, 요약, 태그, method, 파라미터 텍스트로 엔드포인트를 검색할 수 있습니다. 엔드포인트 탭에서는 요청 파라미터, 요청 본문, 응답 필드, AI 친화적인 컨텍스트, 원본 JSON을 확인할 수 있습니다. 수동 API 작업을 추가, 편집, 삭제할 수도 있으며, 변경 사항은 로컬 캐시 버전으로 저장됩니다.

CLI와 MCP를 사용하기 전에 내장 검사를 먼저 실행하는 것을 권장합니다.

```bash
npm run cli -- check
```

CLI에서 처음부터 시작하려면 `npm run cli -- document create --title "My API" --doc-version 1.0.0`으로 빈 문서를 만들고 `api create`로 엔드포인트를 추가합니다. MCP 클라이언트에서는 `apiskill_check`로 캐시를 확인하고, 상위 문서가 없으면 `apiskill_create_document`로 빈 문서를 만든 뒤, `apiskill_help`로 사용 가능한 도구를 확인합니다.

## 이 도구를 개발한 이유

대형 AI 모델이 등장한 이후 몇 년 동안 개발자가 AI로 코딩하는 방식은 계속 변해 왔습니다. 처음에는 ChatGPT 웹 화면에서 코드, 오류, API 문서를 복사해 붙여 넣는 방식이 많았습니다. 이후 Cursor, Codex, Claude Code처럼 전체 프로젝트에 통합되는 데스크톱 또는 로컬 개발 도구가 등장하면서, AI 개발 방식은 단발성 질의응답에서 프로젝트 전체 컨텍스트를 함께 다루는 방식으로 이동했습니다.

API 문서를 쓰는 방식도 함께 바뀌었습니다. 초기에는 API 문서를 그대로 붙여 넣거나 문서 화면을 캡처해서 AI에게 전달했습니다. 이후 Context7 같은 도구가 등장하면서 AI 어시스턴트가 웹 기반 API 문서를 직접 읽을 수 있게 되었습니다. 이것은 큰 개선이지만, 실제 개발에서는 여전히 몇 가지 문제가 남습니다.

- AI가 웹 문서를 읽고 해석하는 과정은 추가 token을 소비하며, 큰 Swagger, Knife4j, 제품 문서에서는 낭비와 대기 시간이 커집니다.
- 내부 문서는 로그인, cookie, access key, 사내 네트워크 같은 접근 처리가 필요한 경우가 많습니다.
- AI가 문서를 읽을 수 있더라도, 문서를 새로 만들거나 수정하거나 버전 관리하는 능력은 보통 직접 제공되지 않습니다.

API Skill은 이 빈틈을 메우기 위해 만들어졌습니다. API 문서를 로컬로 가져오고, 크롤링하고, 처음부터 만들고, 조회하고, 편집하고, 버전 관리하며, 같은 구조화된 계약을 Web 앱, CLI, MCP 서버로 제공합니다. 목표는 API 문서를 반복해서 붙여 넣는 텍스트나 스크린샷이 아니라, AI 어시스턴트가 안정적으로 사용하고 지속적으로 관리할 수 있는 프로젝트 수준 도구로 만드는 것입니다.

### Token 효율

정확한 절감량은 문서 크기, schema 깊이, 작업에 필요한 주변 컨텍스트에 따라 달라지지만 실무 패턴은 일관적입니다.

| Workflow | 모델에 전달되는 일반적인 컨텍스트 | 재사용성 | 예상 token 영향 |
| --- | --- | --- | --- |
| 문서 스크린샷 | 이미지 token과 보이는 페이지 전체의 시각적 해석 | 낮음 | 비용이 크고 필드를 정확히 인용하기 어렵습니다 |
| 문서 텍스트 복사 | 전체 페이지 텍스트, 네비게이션, 예제, 관련 없는 엔드포인트 | 낮음-보통 | 작업당 수천에서 수만 token이 되기 쉽습니다 |
| Context7 같은 웹 문서 읽기 도구 | AI가 요청 시점에 웹 문서를 읽고 요약합니다 | 보통 | 수동 붙여넣기보다 편하지만, 페이지 가져오기, 파싱, 넓은 문서 컨텍스트 비용은 여전히 발생합니다 |
| CLI/MCP 정밀 조회 | 하나의 엔드포인트 또는 schema를 구조화된 JSON/Markdown으로 반환 | 높음 | API 문서 컨텍스트를 보통 약 70-95% 줄입니다 |
| MCP 검색 후 상세 조회 | 작은 후보 목록 뒤 정확한 엔드포인트 상세 정보 조회 | 높음 | 큰 API 세트에 가장 효율적이며 수백-수천 token으로 끝나는 경우가 많습니다 |

보수적인 예로, Knife4j/Swagger 모듈 문서를 복사하면 10,000-30,000 token이 필요할 수 있지만, 단일 엔드포인트에 대한 `apiskill_get_endpoint` 또는 `apiskill_query_api` 응답은 보통 500-2,000 token 정도입니다. 문서 컨텍스트만 놓고 보면 약 5배에서 60배까지 줄어들 수 있습니다. 프론트엔드, 백엔드, 테스트 작업에서 같은 문서를 반복 사용할수록 절감 효과는 누적됩니다.

Context7 같은 웹 문서 읽기 도구는 문서가 공개되어 있고 최신 상위 자료를 참고해야 할 때 유용합니다. 하지만 내부 API 문서나 반복적인 제품 개발에서는 API Skill이 더 예측 가능합니다. 문서가 이미 로컬에 가져와져 있고, 접근 처리는 한 번만 하면 되며, AI가 큰 웹 페이지를 반복해서 읽는 대신 좁은 로컬 계약을 조회하거나 편집할 수 있기 때문입니다.

더 큰 이점은 단순히 token 비용이 낮아지는 것만이 아닙니다. 구조화된 조회는 관련 없는 컨텍스트를 줄이고, 필드명, 필수 여부, 타입, 응답 구조를 더 안정적으로 보존하며, 실제로 필요할 때만 더 깊은 schema를 가져올 수 있게 합니다.

### 종합적인 비용 대비 효과

API Skill의 비용은 주로 한 번의 설정입니다. 의존성을 설치하고, 문서를 가져오거나 크롤링하고, CLI 또는 MCP 접근을 구성하면 됩니다. 그 이후에는 같은 캐시가 일상적인 개발 작업을 지원합니다. 엔드포인트가 많거나, schema가 깊거나, 여러 개발자가 협업하거나, AI 보조 작업이 반복되는 프로젝트라면 보통 빠르게 비용을 회수합니다.

가장 큰 수익은 다음에서 나옵니다.

- 큰 문서나 스크린샷을 반복해서 프롬프트에 넣는 일을 줄입니다.
- agent에게 기억이나 시각적 추출 대신 결정적인 API 탐색 도구를 제공합니다.
- 상위 문서가 구현보다 늦을 때 로컬 수정본을 유지할 수 있습니다.
- 원본 문서 소스를 바꾸지 않고도 터미널, 에디터, MCP 클라이언트, Web 앱에서 API 컨텍스트를 사용할 수 있습니다.

엔드포인트가 아주 적고 안정적인 작은 프로젝트라면 복사-붙여넣기도 충분할 수 있습니다. 하지만 페이지, 서비스, mock, 테스트를 변경되는 API 계약에 맞춰 반복 구현하는 팀이라면 CLI/MCP 접근은 컨텍스트 비용과 통합 실수를 함께 줄여 줍니다.

### CLI와 MCP 선택 기준

CLI는 가장 이식성이 높고 결정적인 진입점입니다. 어떤 shell, CI 작업, 에디터 task, 명령을 실행할 수 있는 AI 도구에서도 사용할 수 있습니다. 스크립트 기반 대량 업데이트, import/export 검증, 재현 가능한 자동화에서는 CLI가 보통 더 디버깅하기 쉽고 공유하기도 쉽습니다. 사용자나 자동화가 정확한 명령만 실행하고 요약 결과만 대화에 가져오면 CLI도 token 효율이 좋습니다.

MCP는 agent 워크플로에 더 적합합니다. MCP를 지원하는 AI 클라이언트는 도구를 발견하고 `apiskill_search_endpoints`, `apiskill_create_document`, `apiskill_create_api`, `apiskill_get_endpoint`를 직접 호출하며 구조화된 결과만 받을 수 있습니다. 사용자가 명령 출력이나 전체 API 문서를 직접 붙여 넣지 않아도 되므로 prompt token을 줄이는 경우가 많습니다. 단점은 호환성입니다. AI 도구가 stdio MCP server와 tool schema를 지원해야 하며, 클라이언트마다 timeout 처리, 작업 디렉터리 설정, 승인 UX, 도구 결과 표시 방식이 다를 수 있습니다.

CLI와 MCP가 같은 shared core에 같은 payload를 전달하면 생성되는 API 문서 내용은 동일해야 합니다. 범용 자동화와 CI 재현성이 중요하면 CLI를, AI agent가 코딩 중 API 문서를 직접 검색, 생성, 편집, 조회해야 하면 MCP를 선택하세요.

### 프로젝트 통합 효과

프론트엔드 팀은 페이지, hooks, 요청 client, 폼, 테이블, 검증 로직을 작성할 때 정확한 엔드포인트 계약을 조회할 수 있습니다. 응답 필드 조회는 전체 문서 페이지를 프롬프트에 붙여 넣지 않고도 API 데이터를 UI 상태로 매핑하는 데 도움을 줍니다.

백엔드 팀은 같은 캐시로 기존 계약을 확인하고, 수동 변경을 비교하며, 상위 OpenAPI 문서가 업데이트되기 전 임시 또는 수정된 로컬 작업을 노출할 수 있습니다. 구현과 문서가 약간 어긋난 상황에 특히 유용합니다.

테스트 자동화는 같은 엔드포인트 상세 정보를 기반으로 mock, fixture payload, contract assertion, end-to-end 준비 데이터를 생성하거나 검토할 수 있습니다. CLI와 MCP가 캐시를 공유하므로 테스트는 원격 문서 사이트의 현재 상태 대신 알려진 버전에 고정할 수 있습니다.

Agent 워크플로는 MCP에서 가장 큰 이점을 얻습니다. 코딩 agent는 `apiskill_search_endpoints`로 검색하고, `apiskill_get_endpoint`로 정확한 엔드포인트를 확인하고, 필요하면 `apiskill_get_schema`로 schema 컨텍스트를 가져온 뒤 코드를 구현하거나 수정할 수 있습니다. API 문서가 거대한 텍스트 덩어리가 아니라 프로젝트 수준 도구가 됩니다.

## 문서

- Web 앱: [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 구성 및 사용법: [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 구성 및 사용법: [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)

## 데이터 모델

모든 진입점은 같은 캐시를 읽고 씁니다.

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

Web 앱과 CLI는 원격 또는 로컬 OpenAPI 문서를 가져올 수 있습니다. MCP 서버는 캐시를 조회할 수 있으며, 명시적으로 쓰기 도구를 호출하면 문서를 가져오거나 수동 API 작업을 생성, 편집, 삭제할 수 있습니다.