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

* feat(docs): add dedicated docs skill and restructure CLI documentation

- Add new `docs` skill as a single-file skill for documentation retrieval
- Align skill prompts with MCP tool descriptions (selection process, query guidance, 3-call limit)
- Enrich CLI docs page with result fields, query tips, and version-specific IDs
- Move CLI page to Overview section in docs nav
- Make `query` required for `ctx7 library` across all skills and docs
- Update trust score display label in skills.mdx

* feat(cli): align library output format with MCP labels

Use labeled fields and categorical Source Reputation labels
(High/Medium/Low/Unknown) instead of numeric trust scores to match
the MCP transport format.

* refactor: move skills from .agents/skills to skills/ at repo root

Source-control location for skills — users install them into
.agents/, .claude/, etc. via the CLI. Also updates install
instructions to use `npm install -g ctx7@latest` or `npx ctx7@latest`.

* docs: use natural-language query examples across skills and CLI docs

Replace keyword-style queries ("useEffect cleanup") with full
question-style queries ("How to clean up useEffect with async
operations") to better demonstrate how the query parameter works.

* docs: fix trust score description to show numeric range

Author: fahreddinozcan

.agents/skills/ctx7-cli/references/docs.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

.changeset/align-cli-mcp-labels.md

@@ -176,8 +176,7 @@ dist
 !plugins/cursor/context7/.cursor
 .opencode
 .claude
-.agents/*
-!.agents/skills/
+.agents
 
 # Finder (MacOS) folder config
 .DS_Store

.gitignore

@@ -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"
 ```
 
 ---

docs/clients/cli.mdx

@@ -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"
         ]
       },
       {

docs/docs.json

@@ -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");

packages/cli/src/commands/docs.ts

@@ -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