skills/skills/using-context7/SKILL.md

name, author, version, description

name	author	version	description
using-context7	ours	2.0.0	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 CLI

Overview

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

• 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

Use when the user asks about any of these in the context of a specific library:

• Install / setup / init commands
• Config file shape (nuxt.config.ts, next.config.mjs, tsconfig.json extends, vite.config, etc.)
• API / component / hook / composable syntax
• Migration between versions (v3 → v4, v14 → v15)
• Library-specific errors / warnings
• CLI flags
• Feature availability ("does X support Y?")
• Plugin / module ecosystem questions

Common triggers: "how do I …", "what's the right way to … in ", "is there a way to …", any error message containing a library's name, any config file snippet.

Prefer context7 over WebSearch / WebFetch for library docs — it returns curated snippets, not rendered marketing pages.

When NOT to use

• General programming concepts (closures, concurrency, algorithms)
• 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 instead)

Workflow

1. Identify the library (and version, if the user mentioned one)
2. ctx7 library <name> [query]  → pick best match (official casing, most snippets)
3. ctx7 docs <libraryId> "<specific question>"
4. Cite what you found; fall back only if context7 returned nothing useful

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 ctx7 docs.

CLI quick reference

Command	Example	Purpose
ctx7 library <name> [query]	ctx7 library express	Name → /org/project ID. Use official casing ("Next.js", not "nextjs").
ctx7 docs <libraryId> <query>	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

library — pick official names:

ctx7 library Nuxt "Nuxt 4 config and route rules"   ✅
ctx7 library nuxt4 "nuxt"                            ❌ (wrong casing, vague query)

docs — be specific:

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.

Example

User: "How do routeRules work in Nuxt 4?"

1. npx -y ctx7 library Nuxt "Nuxt 4 routeRules hybrid rendering"
   → /nuxt/nuxt  (or /nuxt/nuxt/v4.x.x if version known)

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.

Common mistakes

Mistake	Fix
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	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 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.