From 850b3099ddc1cc62eaa89a16227d24897d58c78f Mon Sep 17 00:00:00 2001 From: vitya Date: Wed, 12 Aug 2026 13:21:27 +0300 Subject: [PATCH] =?UTF-8?q?feat(using-context7):=20v1.0.0=20=E2=86=92=20v2?= =?UTF-8?q?.0.0=20=E2=80=94=20CLI-first=20(ctx7),=20agent-neutral=20(pi/cl?= =?UTF-8?q?aude/codex/hermes),=20MCP-bound=20deprecated?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/using-context7/SKILL.md | 67 ++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/skills/using-context7/SKILL.md b/skills/using-context7/SKILL.md index 280c2c5..bf58df6 100644 --- a/skills/using-context7/SKILL.md +++ b/skills/using-context7/SKILL.md @@ -1,20 +1,22 @@ --- name: using-context7 -version: 1.0.0 +version: 2.0.0 description: Use when answering questions about a specific library, framework, SDK, API, or CLI tool — including setup/install, config, API syntax, version-specific behavior, migration between versions, or library-specific errors. Training data is often stale; context7 returns current docs. Skip for general programming concepts, refactoring, business-logic debugging, or when the codebase already answers the question. --- -# Using the context7 MCP server +# Using the context7 CLI ## Overview -`context7` is an MCP server that fetches **current** documentation for named libraries and frameworks. Two tools: `mcp__context7__resolve-library-id` (name → library ID) and `mcp__context7__query-docs` (library ID + question → doc snippets). +`context7` fetches **current** documentation for named libraries and frameworks. Agent-neutral via the **`ctx7` CLI** (npm) — any agent runs it in bash; no MCP registration, no harness-specific tools. Your training data has a cutoff. Library APIs change. If a question names a library, **reach for context7 before answering from memory**, even for libraries you "know" — your recall may be one or two majors behind. ## Prerequisites -This skill assumes `mcp__context7__resolve-library-id` and `mcp__context7__query-docs` are available. If they aren't (the tools are missing from the session, or calls fail with a connection error), the context7 MCP server isn't running for this session. Trigger the **`setup-context7`** skill to install/configure the official plugin (`context7@claude-plugins-official`) and inject the user's API key. It's a one-time procedure with confirmation gates. +- Node/npx available. Run via `npx -y ctx7 ...` (no install needed) or `npm i -g ctx7`. +- Works **anonymously** for basic queries (no API key). For higher rate limits: `ctx7 login` (interactive, one-time, human). +- **Git Bash / Windows gotcha:** library IDs start with `/` which Git Bash path-converts — prefix with an extra slash: `ctx7 docs "//facebook/react" "..."`. ## When to use @@ -39,46 +41,48 @@ Common triggers: "how do I …", "what's the right way to … in ", "is the - Refactoring / code review / business-logic debugging - Writing new code from scratch where the stack isn't named - Questions the current codebase answers (read the repo first) -- Your own prior-conversation context (use wiki / memory instead) +- Your own prior-conversation context (use wiki instead) ## Workflow ``` 1. Identify the library (and version, if the user mentioned one) -2. resolve-library-id → pick best match by name + reputation + snippet count -3. query-docs with the ID + a specific question +2. ctx7 library [query] → pick best match (official casing, most snippets) +3. ctx7 docs "" 4. Cite what you found; fall back only if context7 returned nothing useful ``` -**Budget: 3 calls per question, max.** After 3, use what you have — don't loop. +**Budget: 2 CLI calls per question, max.** After that, use what you have — don't loop. -If the user already gave a library ID in `/org/project` or `/org/project/version` form, skip step 2 and go straight to `query-docs`. +If the user already gave a library ID in `/org/project` or `/org/project/version` form, skip step 2 and go straight to `ctx7 docs`. -## Tool quick reference +## CLI quick reference -| Tool | Required args | Purpose | +| Command | Example | Purpose | |---|---|---| -| `mcp__context7__resolve-library-id` | `libraryName`, `query` | Name → `/org/project` ID. Use official casing ("Next.js", not "nextjs"). | -| `mcp__context7__query-docs` | `libraryId`, `query` | ID → doc snippets. `query` must be specific. | +| `ctx7 library [query]` | `ctx7 library express` | Name → `/org/project` ID. Use official casing ("Next.js", not "nextjs"). | +| `ctx7 docs ` | `ctx7 docs "/nuxt/nuxt" "routeRules hybrid rendering"` | ID → doc snippets. `query` must be specific. Git Bash: `//owner/repo`. | +| `ctx7 setup [--claude\|--cursor\|--opencode]` | `ctx7 setup` | (Optional) wire context7 MCP into an agent — NOT needed for CLI use. | +| `ctx7 login / whoami` | `ctx7 whoami` | (Optional) auth for higher rate limits. | Library ID format: `/org/project` (e.g. `/vercel/next.js`) or `/org/project/version` (e.g. `/vercel/next.js/v14.3.0`). ## Good vs bad queries -**`resolve-library-id` — pick official names:** +**`library` — pick official names:** ``` -libraryName: "Nuxt" query: "Nuxt 4 config and route rules" ✅ -libraryName: "nuxt4" query: "nuxt" ❌ (wrong casing, vague query) +ctx7 library Nuxt "Nuxt 4 config and route rules" ✅ +ctx7 library nuxt4 "nuxt" ❌ (wrong casing, vague query) ``` -**`query-docs` — be specific:** +**`docs` — be specific:** ``` -query: "How to set up @nuxtjs/i18n with prefix_except_default and ru default locale in Nuxt 4" ✅ -query: "i18n" ❌ -query: "How to configure YooKassa payment provider in Medusa v2 core flows" ✅ -query: "payments" ❌ +ctx7 docs "/nuxt/nuxt" "How to set up @nuxtjs/i18n with prefix_except_default and ru default locale in Nuxt 4" ✅ +ctx7 docs "/nuxt/nuxt" "i18n" ❌ +ctx7 docs "//medusajs/medusa" "How to configure YooKassa payment provider in Medusa v2 core flows" ✅ +ctx7 docs "/medusajs/medusa" "payments" ❌ ``` A specific query returns targeted snippets; a vague one returns a grab bag you'll ignore. @@ -88,14 +92,10 @@ A specific query returns targeted snippets; a vague one returns a grab bag you'l User: "How do `routeRules` work in Nuxt 4?" ``` -1. mcp__context7__resolve-library-id - libraryName: "Nuxt" - query: "Nuxt 4 routeRules hybrid rendering" +1. npx -y ctx7 library Nuxt "Nuxt 4 routeRules hybrid rendering" → /nuxt/nuxt (or /nuxt/nuxt/v4.x.x if version known) -2. mcp__context7__query-docs - libraryId: "/nuxt/nuxt" - query: "routeRules for hybrid rendering: ssr, prerender, isr, swr — syntax and examples" +2. npx -y ctx7 docs "/nuxt/nuxt" "routeRules for hybrid rendering: ssr, prerender, isr, swr — syntax and examples" → doc snippets 3. Answer using the snippets. Cite the library + version. @@ -105,15 +105,20 @@ User: "How do `routeRules` work in Nuxt 4?" | Mistake | Fix | |---|---| -| Answering from memory on a library question | Run `resolve-library-id` first. Your training data is stale. | -| Calling `query-docs` without resolving first | Required unless user already gave `/org/project` ID. | +| Answering from memory on a library question | Run `ctx7 library` first. Your training data is stale. | +| Calling `docs` without resolving first | Required unless user already gave `/org/project` ID. | +| Git Bash path-conversion mangles the ID | Use `//owner/repo` (extra leading slash). | | Vague queries ("auth", "hooks", "config") | Include the specific task, version, and constraints. | -| Looping until you find the "perfect" answer | 3-call hard cap. Take the best result and move on. | +| Looping until you find the "perfect" answer | 2-call hard cap. Take the best result and move on. | | Using context7 for codebase questions | Read the code. context7 doesn't know your repo. | | Using context7 for general concepts | Answer from training data. context7 is for libraries. | ## Red flags - "I already know this library" → your recall may be one major behind. Resolve anyway if the user is about to act on your answer. -- "This will take too many calls" → you have 3. Use them. +- "This will take too many calls" → you have 2. Use them. - "The error message looks obvious" → error messages that include a library name are a strong context7 signal. + +## Migration note (v1 → v2) + +v1 was MCP-bound (`mcp__context7__resolve-library-id` / `query-docs`), visible only to harnesses with the context7 MCP registered (claude plugin / settings.json). v2 is CLI-first: any agent (pi, claude, codex, hermes) runs `ctx7` in bash. The MCP route still exists for agents that prefer it (`ctx7 setup` / `@upstash/context7-mcp`), but the CLI is the canonical, agent-neutral path.