How do I install the Yapi skill?

Run npx skillmds add modbender/yapi in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Yapi?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Yapi by modbender — Agent Skill

Name: Yapi
Rating: 4.2 (5 reviews)
Author: modbender

Yapi

Query and sync YApi interface documentation. Use when user mentions "yapi 接口文档", YAPI docs, asks for request/response details, or needs docs sync. Also triggers when user pastes a YApi URL that matches the configured base_url.

modbender 08f7be4 2.7 KB Updated Sep 9, 2026 12 repo stars

File contents

YApi interface docs

Command policy

Prefer yapi command. If missing, fallback to one-shot npx without forcing global install:

yapi -h
# fallback:
npx -y @leeguoo/yapi-mcp -h

In command examples below, yapi can be replaced by npx -y @leeguoo/yapi-mcp.

Quick workflow

If user gives a YApi URL, verify it belongs to configured base_url.
Confirm auth (yapi whoami), then run yapi login only when needed.
Resolve target by api_id / keyword / category.
Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples.
For docs sync tasks, do --dry-run first, then real sync.

URL detection

Read configured base_url from ~/.yapi/config.toml.

rg -n "^base_url\\s*=" ~/.yapi/config.toml

If URL origin matches base_url, extract IDs from path:
- /project/123/... -> project_id=123
- .../api/456 -> api_id=456
- .../api/cat_789 -> catid=789
Prefer direct lookup when api_id exists:

yapi --path /api/interface/get --query id=<api_id>

Common commands

# version/help
yapi --version
yapi -h

# auth
yapi whoami
yapi login

# search / fetch
yapi search --q keyword --project-id 310
yapi --path /api/interface/get --query id=123
yapi --path /api/interface/list_cat --query catid=123

Config cache locations:

Config: ~/.yapi/config.toml
Auth cache: ~/.yapi-mcp/auth-*.json

Docs sync

Binding mode (recommended):

yapi docs-sync bind add --name projectA --dir docs/release-notes --project-id 267 --catid 3667
yapi docs-sync --binding projectA --dry-run
yapi docs-sync --binding projectA

Notes:

Binding file: .yapi/docs-sync.json
Mapping outputs: .yapi/docs-sync.links.json, .yapi/docs-sync.projects.json, .yapi/docs-sync.deployments.json
Default behavior syncs changed files only; use --force for full sync.
Compatible with directory .yapi.json config as fallback (without binding).
Mermaid/PlantUML/Graphviz/D2 rendering depends on local tool availability; missing tools do not block basic sync.

Interface creation guardrails

Always set req_body_type (use json if unsure) and provide res_body (prefer JSON Schema) when creating/updating interfaces.
Put structured request/response fields in req_* / res_body, not only in free-text desc/markdown.

---name: yapidescription: Query and sync YApi interface documentation. Use when user mentions "yapi 接口文档", YAPI docs, asks for request/response details, or needs docs sync. Also triggers when user pastes a YApi URL that matches the configured base_url.--- # YApi interface docs ## Command policy Prefer `yapi` command. If missing, fallback to one-shot npx without forcing global install: ```bash yapi -h # fallback: npx -y @leeguoo/yapi-mcp -h ``` In command examples below, `yapi` can be replaced by `npx -y @leeguoo/yapi-mcp`. ## Quick workflow 1. If user gives a YApi URL, verify it belongs to configured `base_url`. 2. Confirm auth (`yapi whoami`), then run `yapi login` only when needed. 3. Resolve target by `api_id` / keyword / category. 4. Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples. 5. For docs sync tasks, do `--dry-run` first, then real sync. ## URL detection 1. Read configured `base_url` from `~/.yapi/config.toml`. ```bash rg -n "^base_url\\s*=" ~/.yapi/config.toml ``` 2. If URL origin matches `base_url`, extract IDs from path: - `/project/123/...` -> `project_id=123` - `.../api/456` -> `api_id=456` - `.../api/cat_789` -> `catid=789` 3. Prefer direct lookup when `api_id` exists: ```bash yapi --path /api/interface/get --query id=<api_id> ``` ## Common commands ```bash # version/help yapi --version yapi -h # auth yapi whoami yapi login # search / fetch yapi search --q keyword --project-id 310 yapi --path /api/interface/get --query id=123 yapi --path /api/interface/list_cat --query catid=123 ``` Config cache locations: - Config: `~/.yapi/config.toml` - Auth cache: `~/.yapi-mcp/auth-*.json` ## Docs sync Binding mode (recommended): ```bash yapi docs-sync bind add --name projectA --dir docs/release-notes --project-id 267 --catid 3667 yapi docs-sync --binding projectA --dry-run yapi docs-sync --binding projectA ``` Notes: - Binding file: `.yapi/docs-sync.json` - Mapping outputs: `.yapi/docs-sync.links.json`, `.yapi/docs-sync.projects.json`, `.yapi/docs-sync.deployments.json` - Default behavior syncs changed files only; use `--force` for full sync. - Compatible with directory `.yapi.json` config as fallback (without binding). - Mermaid/PlantUML/Graphviz/D2 rendering depends on local tool availability; missing tools do not block basic sync. ## Interface creation guardrails - Always set `req_body_type` (use `json` if unsure) and provide `res_body` (prefer JSON Schema) when creating/updating interfaces. - Put structured request/response fields in `req_*` / `res_body`, not only in free-text `desc`/`markdown`.

Frequently asked questions