Context7 Platform -- Up-to-date docs for AI agents
refactor(skills): consolidate skills under /skills with canonical sources (#2191)
Fahreddin Özcan04130b559696
diff --git a/.changeset/refactor-skills-consolidation.md b/.changeset/refactor-skills-consolidation.mdnew file mode 100644index 00000000..03ecb803--- /dev/null+++ b/.changeset/refactor-skills-consolidation.md@@ -0,0 +1,5 @@+---+"ctx7": patch+---++Consolidate skills under /skills with canonical sources: rename docs→find-docs, ctx7-cli→context7-cli, add context7-mcp as canonical MCP skill. MCP setup now downloads skill from GitHub instead of using hardcoded content.diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdxindex 14a7835a..12f6b319 100644--- a/docs/clients/cli.mdx+++ b/docs/clients/cli.mdx@@ -154,7 +154,7 @@ Without `--api-key` or `--oauth`, setup opens a browser for OAuth login. MCP mod|------|---------|| `.mcp.json` / `.cursor/mcp.json` / `.opencode.json` | MCP server entry || Agent rules directory | Rule file — instructs the agent to use Context7 for library docs |-| Agent skills directory | `documentation-lookup` skill |+| Agent skills directory | `context7-mcp` skill |**What gets written — CLI + Skills mode:**diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.tsindex a270e7e6..5ca470bd 100644--- a/packages/cli/src/commands/setup.ts+++ b/packages/cli/src/commands/setup.ts@@ -23,7 +23,7 @@ import {getAgent,detectAgents,} from "../setup/agents.js";-import { RULE_CONTENT, SKILL_CONTENT } from "../setup/templates.js";+import { RULE_CONTENT } from "../setup/templates.js";import {readJsonConfig,mergeServerEntry,@@ -309,8 +309,11 @@ async function setupAgent(let skillStatus: string;try {- await mkdir(dirname(skillPath), { recursive: true });- await writeFile(skillPath, SKILL_CONTENT, "utf-8");+ const downloadData = await downloadSkill("/upstash/context7", agent.skill.name);+ if (downloadData.error || downloadData.files.length === 0) {+ throw new Error(downloadData.error || "no files");+ }+ await installSkillFiles(agent.skill.name, downloadData.files, skillDir);skillStatus = "installed";} catch (err) {skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;@@ -375,20 +378,20 @@ async function setupCli(options: SetupOptions): Promise<void> {log.blank();const spinner = ora("Downloading docs skill...").start();- const downloadData = await downloadSkill("/upstash/context7", "docs");+ const downloadData = await downloadSkill("/upstash/context7", "find-docs");if (downloadData.error || downloadData.files.length === 0) {- spinner.fail(`Failed to download docs skill: ${downloadData.error || "no files"}`);+ spinner.fail(`Failed to download find-docs skill: ${downloadData.error || "no files"}`);return;}- spinner.succeed("Downloaded docs skill");+ spinner.succeed("Downloaded find-docs skill");const targetDirs = getTargetDirs(targets);- const installSpinner = ora("Installing docs skill...").start();+ const installSpinner = ora("Installing find-docs skill...").start();for (const dir of targetDirs) {installSpinner.text = `Installing to ${dir}...`;- await installSkillFiles("docs", downloadData.files, dir);+ await installSkillFiles("find-docs", downloadData.files, dir);}installSpinner.stop();diff --git a/packages/cli/src/setup/agents.ts b/packages/cli/src/setup/agents.tsindex 8818c7d1..bfcd4d31 100644--- a/packages/cli/src/setup/agents.ts+++ b/packages/cli/src/setup/agents.ts@@ -75,7 +75,7 @@ const agents: Record<SetupAgent, AgentConfig> = {filename: "context7.md",},skill: {- name: "documentation-lookup",+ name: "context7-mcp",dir: (scope) =>scope === "global" ? join(homedir(), ".claude", "skills") : join(".claude", "skills"),},@@ -100,7 +100,7 @@ const agents: Record<SetupAgent, AgentConfig> = {filename: "context7.mdc",},skill: {- name: "documentation-lookup",+ name: "context7-mcp",dir: (scope) =>scope === "global" ? join(homedir(), ".cursor", "skills") : join(".cursor", "skills"),},@@ -131,7 +131,7 @@ const agents: Record<SetupAgent, AgentConfig> = {: ".opencode/rules/*.md",},skill: {- name: "documentation-lookup",+ name: "context7-mcp",dir: (scope) =>scope === "global" ? join(homedir(), ".agents", "skills") : join(".agents", "skills"),},diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.tsindex 11211966..819fa570 100644--- a/packages/cli/src/setup/templates.ts+++ b/packages/cli/src/setup/templates.ts@@ -1,58 +1,3 @@-export const SKILL_CONTENT = `----name: documentation-lookup-description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.------When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.--## When to Use This Skill--Activate this skill when the user:--- Asks setup or configuration questions ("How do I configure Next.js middleware?")-- Requests code involving libraries ("Write a Prisma query for...")-- Needs API references ("What are the Supabase auth methods?")-- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)--## How to Fetch Documentation--### Step 1: Resolve the Library ID--Call \`resolve-library-id\` with:--- \`libraryName\`: The library name extracted from the user's question-- \`query\`: The user's full question (improves relevance ranking)--### Step 2: Select the Best Match--From the resolution results, choose based on:--- Exact or closest name match to what the user asked for-- Higher benchmark scores indicate better documentation quality-- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs--### Step 3: Fetch the Documentation--Call \`query-docs\` with:--- \`libraryId\`: The selected Context7 library ID (e.g., \`/vercel/next.js\`)-- \`query\`: The user's specific question--### Step 4: Use the Documentation--Incorporate the fetched documentation into your response:--- Answer the user's question using current, accurate information-- Include relevant code examples from the docs-- Cite the library version when relevant--## Guidelines--- **Be specific**: Pass the user's full question as the query for better results-- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step-- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks-`;-export const RULE_CONTENT = `---alwaysApply: true---diff --git a/plugins/claude/context7/skills/documentation-lookup/SKILL.md b/plugins/claude/context7/skills/context7-mcp/SKILL.mdsimilarity index 98%rename from plugins/claude/context7/skills/documentation-lookup/SKILL.mdrename to plugins/claude/context7/skills/context7-mcp/SKILL.mdindex 8b7f3996..234659d9 100644--- a/plugins/claude/context7/skills/documentation-lookup/SKILL.md+++ b/plugins/claude/context7/skills/context7-mcp/SKILL.md@@ -1,5 +1,5 @@----name: documentation-lookup+name: context7-mcpdescription: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.---diff --git a/plugins/cursor/context7/skills/context7-docs-lookup/SKILL.md b/plugins/cursor/context7/skills/context7-mcp/SKILL.mdsimilarity index 84%rename from plugins/cursor/context7/skills/context7-docs-lookup/SKILL.mdrename to plugins/cursor/context7/skills/context7-mcp/SKILL.mdindex 4affc10d..234659d9 100644--- a/plugins/cursor/context7/skills/context7-docs-lookup/SKILL.md+++ b/plugins/cursor/context7/skills/context7-mcp/SKILL.md@@ -1,6 +1,6 @@----name: context7-docs-lookup-description: Use Context7 to fetch up-to-date library documentation. Activates when the user asks about libraries, frameworks, API references, or needs code examples — especially for setup questions, code generation, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.+name: context7-mcp+description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.---When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.diff --git a/skills/ctx7-cli/SKILL.md b/skills/context7-cli/SKILL.mdsimilarity index 99%rename from skills/ctx7-cli/SKILL.mdrename to skills/context7-cli/SKILL.mdindex 7aa5fae5..531aa8af 100644--- a/skills/ctx7-cli/SKILL.md+++ b/skills/context7-cli/SKILL.md@@ -1,5 +1,5 @@----name: ctx7-cli+name: context7-clidescription: Use the ctx7 CLI to fetch library documentation, manage AI coding skills, and configure Context7 MCP. Activate when the user mentions "ctx7" or "context7", needs current docs for any library, wants to install/search/generate skills, or needs to set up Context7 for their AI coding agent.---diff --git a/skills/ctx7-cli/references/docs.md b/skills/context7-cli/references/docs.mdsimilarity index 100%rename from skills/ctx7-cli/references/docs.mdrename to skills/context7-cli/references/docs.mddiff --git a/skills/ctx7-cli/references/setup.md b/skills/context7-cli/references/setup.mdsimilarity index 85%rename from skills/ctx7-cli/references/setup.mdrename to skills/context7-cli/references/setup.mdindex 37a7e95b..59f1e790 100644--- a/skills/ctx7-cli/references/setup.md+++ b/skills/context7-cli/references/setup.md@@ -4,7 +4,7 @@One-time command to configure Context7 for your AI coding agent. Prompts for mode on first run:- **MCP server** — registers the Context7 MCP server so the agent can call tools natively-- **CLI + Skills** — installs a `docs` skill that guides the agent to use `ctx7` CLI commands (no MCP required)+- **CLI + Skills** — installs a `find-docs` skill that guides the agent to use `ctx7` CLI commands (no MCP required)```bashctx7 setup # Interactive — prompts for mode, then agent/install target@@ -37,7 +37,7 @@ Without `--api-key` or `--oauth`, setup opens a browser for OAuth login. MCP mod**What gets written — MCP mode:**- MCP server entry in the agent's config file (`.mcp.json` for Claude, `.cursor/mcp.json` for Cursor, `.opencode.json` for OpenCode)- A Context7 rule file instructing the agent to use Context7 for library docs-- A `documentation-lookup` skill in the agent's skills directory+- A `context7-mcp` skill in the agent's skills directory**What gets written — CLI + Skills mode:**-- A `docs` skill in the chosen agent's skills directory, guiding the agent to use `ctx7 library` and `ctx7 docs` commands+- A `find-docs` skill in the chosen agent's skills directory, guiding the agent to use `ctx7 library` and `ctx7 docs` commandsdiff --git a/skills/ctx7-cli/references/skills.md b/skills/context7-cli/references/skills.mdsimilarity index 100%rename from skills/ctx7-cli/references/skills.mdrename to skills/context7-cli/references/skills.mddiff --git a/skills/context7-mcp/SKILL.md b/skills/context7-mcp/SKILL.mdnew file mode 100644index 00000000..234659d9--- /dev/null+++ b/skills/context7-mcp/SKILL.md@@ -0,0 +1,53 @@+---+name: context7-mcp+description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.+---++When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.++## When to Use This Skill++Activate this skill when the user:++- Asks setup or configuration questions ("How do I configure Next.js middleware?")+- Requests code involving libraries ("Write a Prisma query for...")+- Needs API references ("What are the Supabase auth methods?")+- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)++## How to Fetch Documentation++### Step 1: Resolve the Library ID++Call `resolve-library-id` with:++- `libraryName`: The library name extracted from the user's question+- `query`: The user's full question (improves relevance ranking)++### Step 2: Select the Best Match++From the resolution results, choose based on:++- Exact or closest name match to what the user asked for+- Higher benchmark scores indicate better documentation quality+- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs++### Step 3: Fetch the Documentation++Call `query-docs` with:++- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)+- `query`: The user's specific question++### Step 4: Use the Documentation++Incorporate the fetched documentation into your response:++- Answer the user's question using current, accurate information+- Include relevant code examples from the docs+- Cite the library version when relevant++## Guidelines++- **Be specific**: Pass the user's full question as the query for better results+- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step+- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forksdiff --git a/skills/docs/SKILL.md b/skills/find-docs/SKILL.mdsimilarity index 92%rename from skills/docs/SKILL.mdrename to skills/find-docs/SKILL.mdindex fb2788ae..04a97914 100644--- a/skills/docs/SKILL.md+++ b/skills/find-docs/SKILL.md@@ -1,5 +1,5 @@----name: docs+name: find-docsdescription: 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.---@@ -123,6 +123,15 @@ export CONTEXT7_API_KEY=your_keyctx7 login```+## Error Handling++If a command fails with a quota error ("Monthly quota reached" or "quota exceeded"):+1. Inform the user their Context7 quota is exhausted+2. Suggest they authenticate for higher limits: `ctx7 login`+3. If they cannot or choose not to authenticate, answer from training knowledge and clearly note it may be outdated++Do not silently fall back to training data — always tell the user why Context7 was not used.+## Common Mistakes- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`