Context7

Context7

Fetches current library/framework/API documentation from the Context7 API, so responses cite authoritative docs rather than potentially outdated training data. Standalone Node CLI only (no MCP dependency).

Architecture: Two-Skill Split

Skill	Role	Context	Token Cost
context7 (this file)	Intent detection, library selection, response integration	Full conversation	Higher
context7-fetcher	Pure API calls (search / context)	context: fork (isolated)	Lower

The main skill never calls the API directly. It delegates each HTTP call to context7-fetcher via the Task tool so the forked subagent executes without carrying conversation history. The fetcher's contract is defined in context7-fetcher.md.

Call Flow

User Query → context7 (detect trigger + extract library)
    ↓ Task(context7-fetcher) → search <library> <query>   → JSON libraries[]
context7 (select best match: name / trustScore / version)
    ↓ Task(context7-fetcher) → context <libraryId> <query> → JSON results[]
context7 (integrate relevant snippets into answer)

Implementation Layout

• context7-api.cjs - Node CLI entrypoint (HTTPS client, .env + env-var API key, MSYS path fix)
• context7-fetcher.md - Sub-skill definition (forked context, API executor)
• .env.example - API key template (copy to .env)

Execution Method

# Prerequisites: Node.js 18+ (no npm install needed; stdlib only)
# Environment: CONTEXT7_API_KEY (optional; public rate limits apply if unset)

# All examples assume cwd == skills/context7/. Relative path also works from repo root.
node context7-api.cjs search "<library-name>" "<user-query>"
node context7-api.cjs context "<library-id>" "<specific-query>"

In practice, invoke these through the Task tool pointing at context7-fetcher (see Call Flow), not via direct Bash — that keeps API calls in a forked context and minimizes token use.

Tool Capability Matrix

Command	Required Args	Optional Args	Output
search	<libraryName>, <query>	–	{libraries:[{id,name,description,trustScore,versions[]}]}
context	<libraryId>, <query>	–	{results:[{title,content,source,relevance}]}

Library IDs are Context7 slugs (e.g., /facebook/react, /vercel/next.js). For version-specific docs, append the version: /vercel/next.js/v15.1.8.

Research Workflow

Step 1: Extract Library Information

From the user query, identify:

• Library name (e.g., "react", "next.js", "prisma")
• Version if specified (e.g., "React 19", "Next.js 15")
• Specific feature/API (e.g., "useEffect cleanup", "middleware")

Step 2: Search for Library → delegate to fetcher

Task:
- subagent_type: Bash
- description: "Search Context7 for <library>"
- prompt: node skills/context7/context7-api.cjs search "<library>" "<full user question>"

Step 3: Select Best Match

From search results, choose by:

1. Exact name match to the user's query
2. Highest trustScore (quality/popularity signal)
3. Version match if the user specified one
4. Official packages over community forks

Step 4: Fetch Documentation → delegate to fetcher

Task:
- subagent_type: Bash
- description: "Fetch Context7 docs for <library>"
- prompt: node skills/context7/context7-api.cjs context "<libraryId>" "<feature query>"

Step 5: Integrate into Response

1. Answer accurately with the fetched, current information
2. Include code examples drawn from the docs
3. Cite version when relevant
4. Quote only the relevant snippet — do not dump entire documentation

Environment Setup

The context7-api.cjs script loads the API key in priority order:

1. CONTEXT7_API_KEY environment variable
2. .env file in the skill directory (.claude/skills/context7/.env or skills/context7/.env)

cp .env.example .env
# Edit .env: CONTEXT7_API_KEY=<your-key>

Get a key at context7.com/dashboard. Without a key, the API falls back to public rate limits (lower quota).

Error Handling

Error	Recovery
search returns no libraries	Broaden the name; suggest alternatives to the user
API 429 (rate limit)	Retry once after a short delay; switch to public endpoint if key unset
API 5xx / network failure	Retry once; if still failing, fall back to training data and state it may be outdated
Library ID path mangled (Windows Git Bash)	context7-api.cjs auto-fixes MSYS path conversion; verify the ID slug

Best Practices

• Pass the full user question as the query for better relevance ranking
• Prefer version-pinned IDs (/vercel/next.js/v15.1.8) when the user names a version
• For multiple libraries, fire parallel Task calls (each forked independently)
• Set a reasonable timeout (5–10s) and always have a training-data fallback with a disclaimer

Anti-Patterns

Prohibited	Correct
Direct node context7-api.cjs from main context	Delegate via Task → context7-fetcher (forked)
Dump entire fetched documentation	Extract only the relevant snippet
Silently use training data when API fails	Tell the user the data may be outdated
Hardcode library IDs across versions	Re-run search if version uncertainty exists

Example Workflows

Example 1: React Hook (version-specific)

User: "How do I use useEffect to fetch data in React 19?"

1. Detect: "How do I use" + "useEffect" + "React 19"
2. search "react" "useEffect fetch data" → select /facebook/react/v19.0.0
3. context "/facebook/react/v19.0.0" "useEffect data fetching"
4. Respond with current React 19 patterns

Example 2: Next.js Configuration

User: "配置 Next.js 15 的中间件"

1. Detect: "配置" + "Next.js 15" + "中间件"
2. search "next.js" "middleware configuration" → select /vercel/next.js/v15.1.8
3. context "/vercel/next.js/v15.1.8" "middleware"
4. Respond with Next.js 15 middleware setup

Limitations

• Requires internet connection
• Subject to Context7 API rate limits
• May lack documentation for very new or obscure libraries
• Documentation quality depends on the source repository structure