Skip to content

Context7 Platform -- Up-to-date docs for AI agents

feat(cli): add docs skill and align CLI output with MCP format (#2176)

Fahreddin Özcan31b4fb843577
diff --git a/.agents/skills/ctx7-cli/references/docs.md b/.agents/skills/ctx7-cli/references/docs.md
deleted file mode 100644
index 473cf407..00000000
--- a/.agents/skills/ctx7-cli/references/docs.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Documentation Commands
-
-Fetch current library documentation from Context7. Two-step workflow: resolve the library name to get its ID, then query docs using that ID. If the user already provided a library ID in `/org/project` or `/org/project/version` format, pass it directly to `ctx7 docs`.
-
-## Step 1: Resolve a Library
-
-```bash
-ctx7 library react
-ctx7 library nextjs "app router setup"
-ctx7 library prisma "database relations"
-```
-
-Always pass a `query` argument that reflects what the user is trying to do — it ranks results by relevance and helps disambiguate when multiple libraries share a similar name.
-
-### Picking the right result
-
-When multiple results are returned, select based on this priority order:
-
-1. **Name match** — exact or closest match to what the user asked for
-2. **Description relevance** — does the description match the user's intent?
-3. **Snippet count** — more snippets means more indexed documentation; prefer higher counts
-4. **Source reputation** — prefer High or Medium reputation over Unknown
-5. **Benchmark score** — higher is better (100 is the maximum)
-
-If multiple results look equally good, pick the most relevant one and proceed — don't call `ctx7 library` repeatedly trying to find a perfect match. Use the best result you have.
-
-### Version-specific IDs
-
-If the user mentions a specific version, use a version-specific library ID:
-
-```bash
-# General (latest indexed)
-ctx7 docs /vercel/next.js "app router"
-
-# Version-specific
-ctx7 docs /vercel/next.js/v14.3.0-canary.87 "app router"
-```
-
-The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
-
-```bash
-# Output as JSON for scripting
-ctx7 library react --json | jq '.[0].id'
-```
-
-## Step 2: Query Documentation
-
-```bash
-ctx7 docs /facebook/react "useEffect cleanup"
-ctx7 docs /vercel/next.js "middleware authentication"
-ctx7 docs /prisma/prisma "one-to-many relations"
-```
-
-### Writing good queries
-
-The query directly affects the quality of results. Be specific and include context:
-
-| Quality | Example |
-|---------|---------|
-| Good | `"How to set up authentication with JWT in Express.js"` |
-| Good | `"React useEffect cleanup function with async operations"` |
-| Bad | `"auth"` |
-| Bad | `"hooks"` |
-
-Use the user's full question as the query when possible — vague one-word queries return generic results.
-
-The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
-
-```bash
-# Output as structured JSON
-ctx7 docs /facebook/react "hooks" --json
-
-# Pipe to other tools — output is clean when not in a TTY (no spinners or colors)
-ctx7 docs /facebook/react "hooks" | head -50
-ctx7 docs /vercel/next.js "routing" | grep -A5 "middleware"
-```
-
-## Authentication
-
-Works without authentication. For higher rate limits:
-
-```bash
-# Option A: environment variable
-export CONTEXT7_API_KEY=your_key
-
-# Option B: OAuth login
-ctx7 login
-```
diff --git a/.changeset/align-cli-mcp-labels.md b/.changeset/align-cli-mcp-labels.md
new file mode 100644
index 00000000..dfb10799
--- /dev/null
+++ b/.changeset/align-cli-mcp-labels.md
@@ -0,0 +1,5 @@
+---
+"ctx7": patch
+---
+
+Align CLI library output format with MCP: use labeled fields (Title, Context7-compatible library ID, Description, Code Snippets, Source Reputation, Benchmark Score, Versions) and categorical reputation labels (High/Medium/Low/Unknown) instead of numeric trust scores
diff --git a/.gitignore b/.gitignore
index be47e877..da1bf49c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -176,8 +176,7 @@ dist
!plugins/cursor/context7/.cursor
.opencode
.claude
-.agents/*
-!.agents/skills/
+.agents
# Finder (MacOS) folder config
.DS_Store
diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdx
index db632e6c..d2da9182 100644
--- a/docs/clients/cli.mdx
+++ b/docs/clients/cli.mdx
@@ -40,58 +40,63 @@ Requires Node.js 18 or later.
## Query Library Documentation
-Fetching docs is a two-step process: first resolve the library name to get its Context7 ID, then use that ID to query documentation. The ID is stable and scoped to a specific library — it's what Context7 uses to know exactly which library and version to pull docs from.
+Fetching docs is a two-step process: first resolve the library name to get its Context7 ID, then use that ID to query documentation.
### Step 1 — ctx7 library
-Searches the Context7 index by name and returns matching libraries. Pass an optional `query` to rank results by relevance to your specific task — this helps when a library name is ambiguous or has multiple versions indexed.
+Searches the Context7 index by name and returns matching libraries. Pass a `query` describing what you're trying to do — this ranks results by relevance and helps when a library name is ambiguous or shared across multiple packages.
```bash
-ctx7 library react
-ctx7 library nextjs "app router setup"
-ctx7 library prisma "database relations"
+ctx7 library react "How to clean up useEffect with async operations"
+ctx7 library nextjs "How to set up app router with middleware"
+ctx7 library prisma "How to define one-to-many relations with cascade delete"
```
-Each result shows:
+Each result includes:
| Field | Description |
|-------|-------------|
-| **ID** | The library ID to pass to `ctx7 docs` (e.g., `/facebook/react`) |
-| **Snippets** | Number of indexed documentation snippets |
-| **Stars** | GitHub stars — a signal of library popularity |
-| **Trust score** | Documentation quality indicator (0–10) |
-| **Versions** | Indexed versions, if version-specific docs exist |
+| **Library ID** | The identifier to pass to `ctx7 docs` (format: `/org/project`) |
+| **Code Snippets** | Number of indexed code examples — higher means more documentation coverage |
+| **Source Reputation** | Authority indicator: High, Medium, Low, or Unknown |
+| **Benchmark Score** | Quality score from 0 to 100 |
+| **Versions** | Version-specific IDs when available (format: `/org/project/version`) |
-Pick the top result's ID, or a version-specific one if the user mentioned a version (e.g., `/vercel/next.js@canary`).
+When multiple results come back, the best match is usually the one with the closest name, highest snippet count, and strongest reputation. If you need docs for a specific version, pick the matching version ID from the list.
```bash
-# Output as JSON — useful for scripting or piping into other tools
-ctx7 library react --json | jq '.[0].id'
+# Fetch docs for a specific version
+ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
+
+# Output as JSON for scripting
+ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'
```
### Step 2 — ctx7 docs
-Pass the library ID and a natural-language question to fetch relevant code snippets and explanations from the indexed documentation.
+Takes a library ID and a natural-language question, and returns relevant code snippets and explanations from the indexed documentation.
```bash
-ctx7 docs /facebook/react "useEffect cleanup"
-ctx7 docs /vercel/next.js "middleware authentication"
-ctx7 docs /prisma/prisma "one-to-many relations"
+ctx7 docs /facebook/react "How to clean up useEffect with async operations"
+ctx7 docs /vercel/next.js "How to add middleware that redirects unauthenticated users"
+ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
```
<Note>
Library IDs always start with `/`. Running `ctx7 docs react "hooks"` will fail — always use the full ID returned by `ctx7 library` in Step 1.
</Note>
+Queries work best when they're specific. Describe what you're trying to accomplish rather than using single keywords — `"How to set up authentication with JWT in Express.js"` returns much better results than `"auth"`.
+
The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). Both are formatted for readability in the terminal.
```bash
# Output as structured JSON
-ctx7 docs /facebook/react "hooks" --json
+ctx7 docs /facebook/react "How to use hooks for state management" --json
# Pipe to other tools — output is clean when not in a TTY (no spinners or colors)
-ctx7 docs /facebook/react "hooks" | head -50
-ctx7 docs /vercel/next.js "routing" | grep -A 10 "middleware"
+ctx7 docs /facebook/react "How to use hooks for state management" | head -50
+ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A 10 "middleware"
```
---
diff --git a/docs/docs.json b/docs/docs.json
index 2b4d3143..2b198286 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -24,6 +24,7 @@
"overview",
"installation",
"plans-pricing",
+ "clients/cli",
"adding-libraries",
"api-guide",
"skills",
@@ -62,8 +63,7 @@
"clients/claude-code",
"clients/cursor",
"clients/opencode",
- "resources/all-clients",
- "clients/cli"
+ "resources/all-clients"
]
},
{
diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.ts
index 1547e14f..4fdccf4a 100644
--- a/packages/cli/src/commands/docs.ts
+++ b/packages/cli/src/commands/docs.ts
@@ -10,6 +10,13 @@ import type { LibrarySearchResult, ContextResponse } from "../types.js";
const isTTY = process.stdout.isTTY;
+function getReputationLabel(score: number | undefined): "High" | "Medium" | "Low" | "Unknown" {
+ if (score === undefined || score < 0) return "Unknown";
+ if (score >= 7) return "High";
+ if (score >= 4) return "Medium";
+ return "Low";
+}
+
function getAccessToken(): string | undefined {
const tokens = loadTokens();
if (!tokens || isTokenExpired(tokens)) return undefined;
@@ -18,31 +25,24 @@ function getAccessToken(): string | undefined {
function formatLibraryResult(lib: LibrarySearchResult, index: number): string {
const lines: string[] = [];
- lines.push(`${pc.dim(`${index + 1}.`)} ${pc.bold(lib.title)} ${pc.cyan(lib.id)}`);
+ lines.push(`${pc.dim(`${index + 1}.`)} ${pc.bold(`Title: ${lib.title}`)}`);
+ lines.push(` ${pc.cyan(`Context7-compatible library ID: ${lib.id}`)}`);
if (lib.description) {
- lines.push(` ${pc.dim(lib.description)}`);
+ lines.push(` ${pc.dim(`Description: ${lib.description}`)}`);
}
- const meta: string[] = [];
if (lib.totalSnippets) {
- meta.push(`${lib.totalSnippets} snippets`);
- }
- if (lib.stars && lib.stars > 0) {
- meta.push(`${lib.stars.toLocaleString()} stars`);
+ lines.push(` ${pc.dim(`Code Snippets: ${lib.totalSnippets}`)}`);
}
if (lib.trustScore !== undefined) {
- meta.push(`trust: ${lib.trustScore}/10`);
+ lines.push(` ${pc.dim(`Source Reputation: ${getReputationLabel(lib.trustScore)}`)}`);
}
if (lib.benchmarkScore !== undefined && lib.benchmarkScore > 0) {
- meta.push(`benchmark: ${lib.benchmarkScore}`);
+ lines.push(` ${pc.dim(`Benchmark Score: ${lib.benchmarkScore}`)}`);
}
- if (meta.length > 0) {
- lines.push(` ${pc.dim(meta.join(" · "))}`);
- }
-
if (lib.versions && lib.versions.length > 0) {
- lines.push(` ${pc.dim(`versions: ${lib.versions.join(", ")}`)}`);
+ lines.push(` ${pc.dim(`Versions: ${lib.versions.join(", ")}`)}`);
}
return lines.join("\n");
diff --git a/.agents/skills/ctx7-cli/SKILL.md b/skills/ctx7-cli/SKILL.md
similarity index 91%
rename from .agents/skills/ctx7-cli/SKILL.md
rename to skills/ctx7-cli/SKILL.md
index 94a8e41f..7aa5fae5 100644
--- a/.agents/skills/ctx7-cli/SKILL.md
+++ b/skills/ctx7-cli/SKILL.md
@@ -7,7 +7,17 @@ description: Use the ctx7 CLI to fetch library documentation, manage AI coding s
The Context7 CLI does three things: fetches up-to-date library documentation, manages AI coding skills, and sets up Context7 MCP for your editor.
-Run with `npx ctx7` (no install needed) or install globally with `npm install -g ctx7`.
+Make sure the CLI is up to date before running commands:
+
+```bash
+npm install -g ctx7@latest
+```
+
+Or run directly without installing:
+
+```bash
+npx ctx7@latest <command>
+```
## What this skill covers
@@ -19,7 +29,7 @@ Run with `npx ctx7` (no install needed) or install globally with `npm install -g
```bash
# Documentation
-ctx7 library <name> [query] # Step 1: resolve library ID
+ctx7 library <name> <query> # Step 1: resolve library ID
ctx7 docs <libraryId> <query> # Step 2: fetch docs
# Skills
diff --git a/skills/ctx7-cli/references/docs.md b/skills/ctx7-cli/references/docs.md
new file mode 100644
index 00000000..ef5cae9b
--- /dev/null
+++ b/skills/ctx7-cli/references/docs.md
@@ -0,0 +1,113 @@
+# Documentation Commands
+
+Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. Two-step workflow: resolve the library name to get its ID, then query docs using that ID.
+
+If the user already provided a library ID in `/org/project` or `/org/project/version` format, pass it directly to `ctx7 docs`.
+
+## Step 1: Resolve a Library
+
+Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
+
+```bash
+ctx7 library react "How to clean up useEffect with async operations"
+ctx7 library nextjs "How to set up app router with middleware"
+ctx7 library prisma "How to define one-to-many relations with cascade delete"
+```
+
+Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+### Result fields
+
+Each result includes:
+
+- **Library ID** — Context7-compatible identifier (format: `/org/project`)
+- **Name** — Library or package name
+- **Description** — Short summary
+- **Code Snippets** — Number of available code examples
+- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
+- **Benchmark Score** — Quality indicator (100 is the highest score)
+- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
+
+### Selection process
+
+1. Analyze the query to understand what library/package the user is looking for
+2. Select the most relevant match based on:
+ - Name similarity to the query (exact matches prioritized)
+ - Description relevance to the query's intent
+ - Documentation coverage (prioritize libraries with higher Code Snippet counts)
+ - Source reputation (consider libraries with High or Medium reputation more authoritative)
+ - Benchmark score (higher is better, 100 is the maximum)
+3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
+4. If no good matches exist, clearly state this and suggest query refinements
+5. For ambiguous queries, request clarification before proceeding with a best-guess match
+
+IMPORTANT: Do not call `ctx7 library` more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.
+
+### Version-specific IDs
+
+If the user mentions a specific version, use a version-specific library ID:
+
+```bash
+# General (latest indexed)
+ctx7 docs /vercel/next.js "How to set up app router"
+
+# Version-specific
+ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
+```
+
+The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
+
+```bash
+# Output as JSON for scripting
+ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'
+```
+
+## Step 2: Query Documentation
+
+Retrieves up-to-date documentation and code examples for the resolved library.
+
+You must call `ctx7 library` first to obtain the exact Context7-compatible library ID required to use this command, UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
+
+```bash
+ctx7 docs /facebook/react "How to clean up useEffect with async operations"
+ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
+ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
+```
+
+IMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.
+
+### Writing good queries
+
+The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+| Quality | Example |
+|---------|---------|
+| Good | `"How to set up authentication with JWT in Express.js"` |
+| Good | `"React useEffect cleanup function with async operations"` |
+| Bad | `"auth"` |
+| Bad | `"hooks"` |
+
+Use the user's full question as the query when possible — vague one-word queries return generic results.
+
+The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
+
+```bash
+# Output as structured JSON
+ctx7 docs /facebook/react "How to use hooks for state management" --json
+
+# Pipe to other tools — output is clean when not in a TTY (no spinners or colors)
+ctx7 docs /facebook/react "How to use hooks for state management" | head -50
+ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A5 "middleware"
+```
+
+## Authentication
+
+Works without authentication. For higher rate limits:
+
+```bash
+# Option A: environment variable
+export CONTEXT7_API_KEY=your_key
+
+# Option B: OAuth login
+ctx7 login
+```
diff --git a/.agents/skills/ctx7-cli/references/setup.md b/skills/ctx7-cli/references/setup.md
similarity index 100%
rename from .agents/skills/ctx7-cli/references/setup.md
rename to skills/ctx7-cli/references/setup.md
diff --git a/.agents/skills/ctx7-cli/references/skills.md b/skills/ctx7-cli/references/skills.md
similarity index 100%
rename from .agents/skills/ctx7-cli/references/skills.md
rename to skills/ctx7-cli/references/skills.md
diff --git a/skills/docs/SKILL.md b/skills/docs/SKILL.md
new file mode 100644
index 00000000..fb2788ae
--- /dev/null
+++ b/skills/docs/SKILL.md
@@ -0,0 +1,131 @@
+---
+name: docs
+description: Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. Use when writing code that depends on external packages, verifying API signatures, looking up usage patterns, generating code with specific libraries, or when training data may be outdated. Covers setup questions, migration guides, and version-specific docs.
+---
+
+# Documentation Lookup
+
+Retrieve current documentation and code examples for any library using the Context7 CLI.
+
+Make sure the CLI is up to date before running commands:
+
+```bash
+npm install -g ctx7@latest
+```
+
+Or run directly without installing:
+
+```bash
+npx ctx7@latest <command>
+```
+
+## Workflow
+
+Two-step process: resolve the library name to an ID, then query docs with that ID.
+
+```bash
+# Step 1: Resolve library ID
+ctx7 library <name> <query>
+
+# Step 2: Query documentation
+ctx7 docs <libraryId> <query>
+```
+
+You MUST call `ctx7 library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
+
+IMPORTANT: Do not run these commands more than 3 times per question. If you cannot find what you need after 3 attempts, use the best result you have.
+
+## Step 1: Resolve a Library
+
+Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
+
+```bash
+ctx7 library react "How to clean up useEffect with async operations"
+ctx7 library nextjs "How to set up app router with middleware"
+ctx7 library prisma "How to define one-to-many relations with cascade delete"
+```
+
+Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+### Result fields
+
+Each result includes:
+
+- **Library ID** — Context7-compatible identifier (format: `/org/project`)
+- **Name** — Library or package name
+- **Description** — Short summary
+- **Code Snippets** — Number of available code examples
+- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
+- **Benchmark Score** — Quality indicator (100 is the highest score)
+- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
+
+### Selection process
+
+1. Analyze the query to understand what library/package the user is looking for
+2. Select the most relevant match based on:
+ - Name similarity to the query (exact matches prioritized)
+ - Description relevance to the query's intent
+ - Documentation coverage (prioritize libraries with higher Code Snippet counts)
+ - Source reputation (consider libraries with High or Medium reputation more authoritative)
+ - Benchmark score (higher is better, 100 is the maximum)
+3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
+4. If no good matches exist, clearly state this and suggest query refinements
+5. For ambiguous queries, request clarification before proceeding with a best-guess match
+
+### Version-specific IDs
+
+If the user mentions a specific version, use a version-specific library ID:
+
+```bash
+# General (latest indexed)
+ctx7 docs /vercel/next.js "How to set up app router"
+
+# Version-specific
+ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
+```
+
+The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
+
+## Step 2: Query Documentation
+
+Retrieves up-to-date documentation and code examples for the resolved library.
+
+```bash
+ctx7 docs /facebook/react "How to clean up useEffect with async operations"
+ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
+ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
+```
+
+### Writing good queries
+
+The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+| Quality | Example |
+|---------|---------|
+| Good | `"How to set up authentication with JWT in Express.js"` |
+| Good | `"React useEffect cleanup function with async operations"` |
+| Bad | `"auth"` |
+| Bad | `"hooks"` |
+
+Use the user's full question as the query when possible, vague one-word queries return generic results.
+
+The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
+
+## Authentication
+
+Works without authentication. For higher rate limits:
+
+```bash
+# Option A: environment variable
+export CONTEXT7_API_KEY=your_key
+
+# Option B: OAuth login
+ctx7 login
+```
+
+## Common Mistakes
+
+- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
+- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID
+- Use descriptive queries, not single words — `"React useEffect cleanup function"` not `"hooks"`
+- Do not include sensitive information (API keys, passwords, credentials) in queries