claude-skills/skills/using-context7/SKILL.md

---
name: using-context7
version: 1.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

## 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).

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.

## 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 <lib>", "is there a <lib> 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 / memory 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
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.

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`.

## Tool quick reference

| Tool | Required args | 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. |

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:**

```
libraryName: "Nuxt"           query: "Nuxt 4 config and route rules"   ✅
libraryName: "nuxt4"          query: "nuxt"                              ❌ (wrong casing, vague query)
```

**`query-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"                                                                                ❌
```

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. mcp__context7__resolve-library-id
   libraryName: "Nuxt"
   query: "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"
   → doc snippets

3. Answer using the snippets. Cite the library + version.
```

## Common mistakes

| 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. |
| 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. |
| 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.
- "The error message looks obvious" → error messages that include a library name are a strong context7 signal.