Context7 Platform -- Up-to-date docs for AI agents
docs: enhance query descriptions for clarity and specificity (#2868)
Enes Gules33229cb3323b
diff --git a/.changeset/plenty-wasps-retire.md b/.changeset/plenty-wasps-retire.mdnew file mode 100644index 00000000..ec779e0a--- /dev/null+++ b/.changeset/plenty-wasps-retire.md@@ -0,0 +1,8 @@+---+"@upstash/context7-tools-ai-sdk": patch+"ctx7": patch+"@upstash/context7-mcp": patch+"@upstash/context7-pi": patch+---++Clarify the `query-docs` query description so it asks for a single concept per query. When a question spans multiple distinct topics, callers are now told to make a separate query per concept instead of combining them (unless the question is about how the concepts interact), which avoids diluted, shallow results. Applied consistently across the MCP server, CLI, pi, and AI SDK tools.diff --git a/docs/agentic-tools/ai-sdk/tools/query-docs.mdx b/docs/agentic-tools/ai-sdk/tools/query-docs.mdxindex 84525a4f..046315ee 100644--- a/docs/agentic-tools/ai-sdk/tools/query-docs.mdx+++ b/docs/agentic-tools/ai-sdk/tools/query-docs.mdx@@ -63,7 +63,7 @@ The tool accepts the following inputs from the AI model:</ParamField><ParamField path="query" type="string" required>- The question or task you need help with. Be specific and include relevant details. Good: "How to set up authentication with JWT in Express.js" or "React useEffect cleanup function examples". Bad: "auth" or "hooks".+ The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: "How to set up authentication with JWT in Express.js" or "React useEffect cleanup function examples". Bad (too vague): "auth" or "hooks". Bad (too broad): "routing and auth and caching in Next.js".</ParamField>### Output Formatdiff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.tsindex a7f6d4c3..28ee67a6 100644--- a/packages/cli/src/commands/docs.ts+++ b/packages/cli/src/commands/docs.ts@@ -229,7 +229,10 @@ export function registerDocsCommands(program: Command): void {program.command("docs").argument("<libraryId>", "Context7 library ID (e.g., /facebook/react)")- .argument("<query>", "Question or task to get docs for")+ .argument(+ "<query>",+ "Single-topic question to get docs for (run a separate query per distinct concept, unless asking how they interact)"+ ).option("--json", "Output as JSON").description("Query documentation for a library").action(async (libraryId: string, query: string, options: { json?: boolean }) => {diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.tsindex 26b96140..b8ddb04e 100644--- a/packages/cli/src/setup/templates.ts+++ b/packages/cli/src/setup/templates.ts@@ -3,7 +3,7 @@ const GITHUB_RAW_URLS = ["https://raw.githubusercontent.com/upstash/context7/main/rules",];-const FALLBACK_MCP = `Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.+const FALLBACK_MCP = `Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.@@ -11,11 +11,11 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. \`resolve-library-id\` with the library name and the user's question. Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs")2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). Use version-specific IDs when the user mentions a version-3. \`query-docs\` with the selected library ID and the user's full question (not single words)+3. \`query-docs\` with the selected library ID and the user's full question (not single words), scoped to a single concept. If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate \`query-docs\` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic4. Answer using the fetched docs`;-const FALLBACK_CLI = `Use the \`ctx7\` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.+const FALLBACK_CLI = `Use the \`ctx7\` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.@@ -23,10 +23,10 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. Resolve library: \`npx ctx7@latest library <name> "<user's question>"\`2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try the full name with punctuation (e.g., "next.js" not "nextjs")-3. Fetch docs: \`npx ctx7@latest docs <libraryId> "<user's question>"\`+3. Fetch docs: \`npx ctx7@latest docs <libraryId> "<user's question>"\` — run a separate \`docs\` command per distinct concept if the question spans multiple topics, unless it's about how they interact4. Answer using the fetched documentation-You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Use the user's full question as the query -- specific and detailed queries return better results than vague single words. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.+You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Use the user's full question as the query — specific and detailed queries return better results than vague single words, but keep each query to a single concept unless the question is about how concepts interact; combined multi-topic queries dilute ranking and return shallow results for each topic. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.For version-specific docs, use \`/org/project/version\` from the \`library\` output (e.g., \`/vercel/next.js/v14.3.0\`).diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex 17098155..566bb38e 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -125,7 +125,7 @@ function createMcpServer() {],},{- instructions: `Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.+ instructions: `Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.`,}@@ -236,7 +236,7 @@ Do not call this tool more than 3 times per question.`,query: z.string().describe(- "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."+ "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query."),},annotations: {diff --git a/packages/pi/lib/prompts.ts b/packages/pi/lib/prompts.tsindex e6b5525f..a4d1ba33 100644--- a/packages/pi/lib/prompts.ts+++ b/packages/pi/lib/prompts.ts@@ -57,4 +57,4 @@ export const QUERY_DOCS_LIBRARY_ID_DESCRIPTION ="Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'.";export const QUERY_DOCS_QUERY_DESCRIPTION =- "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.";+ "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. The query is sent to the Context7 API for processing. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.";diff --git a/packages/pi/skills/context7-docs/SKILL.md b/packages/pi/skills/context7-docs/SKILL.mdindex bacbd905..1556e311 100644--- a/packages/pi/skills/context7-docs/SKILL.md+++ b/packages/pi/skills/context7-docs/SKILL.md@@ -33,7 +33,7 @@ Reach for these tools whenever a question involves a specific library, framework## Workflow1. **Resolve the library ID.** Call `resolve-library-id` with the library name and the user's question. The tool returns matching libraries with their Context7 IDs (`/org/project` format), descriptions, snippet counts, and quality scores. Pick the best match — prioritize official sources, name match, and high benchmark scores.-2. **Query the docs.** Call `query-docs` with the chosen library ID and the user's question. The tool returns documentation snippets and code examples.+2. **Query the docs.** Call `query-docs` with the chosen library ID and the user's question, scoped to a single concept — if the question spans multiple distinct concepts, make a separate call per concept with the same library ID, unless the question is about how the concepts interact. The tool returns documentation snippets and code examples.3. **Answer.** Cite the library ID you used and quote code examples verbatim when relevant.If the user supplies a library ID in `/org/project` or `/org/project/version` format directly, skip step 1 and call `query-docs` immediately.diff --git a/packages/tools-ai-sdk/src/tools/query-docs.ts b/packages/tools-ai-sdk/src/tools/query-docs.tsindex 8427c1bf..d07de22b 100644--- a/packages/tools-ai-sdk/src/tools/query-docs.ts+++ b/packages/tools-ai-sdk/src/tools/query-docs.ts@@ -45,7 +45,7 @@ export function queryDocs(config: Context7ToolsConfig = {}) {query: z.string().describe(- "The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."+ "The question or task you need help with, scoped to a single concept. Be specific and include relevant details, but keep each query to one topic — if the user's question spans multiple distinct concepts, make a separate call per concept instead of combining them, unless the question is about how the concepts interact. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad (too vague): 'auth' or 'hooks'. Bad (too broad): 'routing and auth and caching in Next.js'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."),}),execute: async ({ libraryId, query }: { libraryId: string; query: string }) => {diff --git a/plugins/claude/context7/agents/docs-researcher.md b/plugins/claude/context7/agents/docs-researcher.mdindex ec7e8aa0..ebd408a6 100644--- a/plugins/claude/context7/agents/docs-researcher.md+++ b/plugins/claude/context7/agents/docs-researcher.md@@ -25,7 +25,7 @@ When given a question about a library or framework, fetch the relevant documenta4. **Fetch documentation**: Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)- - `query`: The user's specific question for targeted results+ - `query`: The user's specific question for targeted results, scoped to a single concept5. **Return a focused answer**: Summarize the relevant documentation with:- Direct answer to the question@@ -34,7 +34,8 @@ When given a question about a library or framework, fetch the relevant documenta## Guidelines-- Pass the user's full question as the query parameter for better relevance+- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept+- If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic- When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available- If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks- Keep responses concise - the goal is to answer the question, not dump entire documentationdiff --git a/plugins/claude/context7/commands/docs.md b/plugins/claude/context7/commands/docs.mdindex 8a2df781..1e6415d1 100644--- a/plugins/claude/context7/commands/docs.md+++ b/plugins/claude/context7/commands/docs.md@@ -14,7 +14,7 @@ Fetches up-to-date documentation and code examples for a library.```- **library**: The library name, or a Context7 ID starting with `/`-- **query**: What you're looking for (optional but recommended)+- **query**: What you're looking for (optional but recommended; run the command once per distinct concept, unless asking how they interact)## Examplesdiff --git a/plugins/claude/context7/skills/context7-mcp/SKILL.md b/plugins/claude/context7/skills/context7-mcp/SKILL.mdindex 234659d9..245b0800 100644--- a/plugins/claude/context7/skills/context7-mcp/SKILL.md+++ b/plugins/claude/context7/skills/context7-mcp/SKILL.md@@ -36,7 +36,9 @@ From the resolution results, choose based on:Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)-- `query`: The user's specific question+- `query`: The user's specific question, scoped to a single concept++If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.### Step 4: Use the Documentation@@ -48,6 +50,7 @@ Incorporate the fetched documentation into your response:## Guidelines-- **Be specific**: Pass the user's full question as the query for better results+- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept+- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact- **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/plugins/codex/context7/skills/context7-mcp/SKILL.md b/plugins/codex/context7/skills/context7-mcp/SKILL.mdindex 234659d9..245b0800 100644--- a/plugins/codex/context7/skills/context7-mcp/SKILL.md+++ b/plugins/codex/context7/skills/context7-mcp/SKILL.md@@ -36,7 +36,9 @@ From the resolution results, choose based on:Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)-- `query`: The user's specific question+- `query`: The user's specific question, scoped to a single concept++If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.### Step 4: Use the Documentation@@ -48,6 +50,7 @@ Incorporate the fetched documentation into your response:## Guidelines-- **Be specific**: Pass the user's full question as the query for better results+- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept+- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact- **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/plugins/context7-power/POWER.md b/plugins/context7-power/POWER.mdindex 184aa477..b6759e40 100644--- a/plugins/context7-power/POWER.md+++ b/plugins/context7-power/POWER.md@@ -49,7 +49,9 @@ From the resolution results, choose based on:Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., /vercel/next.js)-- `query`: The user's full, specific question rather than a single word+- `query`: The user's full, specific question rather than a single word, scoped to a single concept++If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.### Step 4: Use the Documentation@@ -61,11 +63,12 @@ Incorporate the fetched documentation into your response:## Best Practices-- Pass the user's full question as the query for better results+- Pass the user's full question as the query for better results, but keep each query to a single concept+- Keep each query to one topic; split multi-topic questions into separate `query-docs` calls, unless the question is about how the concepts interact- When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step- When multiple matches exist, prefer official/primary packages over community forks- Use this Power for API syntax, configuration, setup instructions, version migration, library-specific debugging, and CLI tool usage-- Use Context7 even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.+- Use Context7 even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.- Do not use Context7 for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.## License and Supportdiff --git a/plugins/copilot/context7/agents/docs-researcher.agent.md b/plugins/copilot/context7/agents/docs-researcher.agent.mdindex 424de063..de3309ba 100644--- a/plugins/copilot/context7/agents/docs-researcher.agent.md+++ b/plugins/copilot/context7/agents/docs-researcher.agent.md@@ -24,7 +24,7 @@ When given a question about a library or framework, fetch the relevant documenta4. **Fetch documentation**: Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)- - `query`: The user's specific question for targeted results+ - `query`: The user's specific question for targeted results, scoped to a single concept5. **Return a focused answer**: Summarize the relevant documentation with:- Direct answer to the question@@ -33,7 +33,8 @@ When given a question about a library or framework, fetch the relevant documenta## Guidelines-- Pass the user's full question as the query parameter for better relevance+- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept+- If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic- When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available- If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks- Keep responses concise - the goal is to answer the question, not dump entire documentationdiff --git a/plugins/copilot/context7/commands/docs.md b/plugins/copilot/context7/commands/docs.mdindex a4cefa3a..e3494ddf 100644--- a/plugins/copilot/context7/commands/docs.md+++ b/plugins/copilot/context7/commands/docs.md@@ -13,7 +13,7 @@ Fetches up-to-date documentation and code examples for a library.```- **library**: The library name, or a Context7 ID starting with `/`-- **query**: What you're looking for (optional but recommended)+- **query**: What you're looking for (optional but recommended; run the command once per distinct concept, unless asking how they interact)## Examplesdiff --git a/plugins/copilot/context7/skills/context7-mcp/SKILL.md b/plugins/copilot/context7/skills/context7-mcp/SKILL.mdindex 234659d9..245b0800 100644--- a/plugins/copilot/context7/skills/context7-mcp/SKILL.md+++ b/plugins/copilot/context7/skills/context7-mcp/SKILL.md@@ -36,7 +36,9 @@ From the resolution results, choose based on:Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)-- `query`: The user's specific question+- `query`: The user's specific question, scoped to a single concept++If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.### Step 4: Use the Documentation@@ -48,6 +50,7 @@ Incorporate the fetched documentation into your response:## Guidelines-- **Be specific**: Pass the user's full question as the query for better results+- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept+- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact- **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/plugins/cursor/context7/agents/docs-researcher.md b/plugins/cursor/context7/agents/docs-researcher.mdindex 424de063..de3309ba 100644--- a/plugins/cursor/context7/agents/docs-researcher.md+++ b/plugins/cursor/context7/agents/docs-researcher.md@@ -24,7 +24,7 @@ When given a question about a library or framework, fetch the relevant documenta4. **Fetch documentation**: Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)- - `query`: The user's specific question for targeted results+ - `query`: The user's specific question for targeted results, scoped to a single concept5. **Return a focused answer**: Summarize the relevant documentation with:- Direct answer to the question@@ -33,7 +33,8 @@ When given a question about a library or framework, fetch the relevant documenta## Guidelines-- Pass the user's full question as the query parameter for better relevance+- Pass the user's full question as the query parameter for better relevance, but keep each query to a single concept+- If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic- When the user mentions a version (e.g., "Next.js 15"), use version-specific library IDs if available- If `resolve-library-id` returns multiple matches, prefer official/primary packages over community forks- Keep responses concise - the goal is to answer the question, not dump entire documentationdiff --git a/plugins/cursor/context7/skills/context7-mcp/SKILL.md b/plugins/cursor/context7/skills/context7-mcp/SKILL.mdindex 234659d9..245b0800 100644--- a/plugins/cursor/context7/skills/context7-mcp/SKILL.md+++ b/plugins/cursor/context7/skills/context7-mcp/SKILL.md@@ -36,7 +36,9 @@ From the resolution results, choose based on:Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)-- `query`: The user's specific question+- `query`: The user's specific question, scoped to a single concept++If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.### Step 4: Use the Documentation@@ -48,6 +50,7 @@ Incorporate the fetched documentation into your response:## Guidelines-- **Be specific**: Pass the user's full question as the query for better results+- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept+- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact- **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/rules/context7-cli.md b/rules/context7-cli.mdindex f723bde1..def26cb9 100644--- a/rules/context7-cli.md+++ b/rules/context7-cli.md@@ -1,4 +1,4 @@-Use the `ctx7` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.+Use the `ctx7` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.@@ -6,10 +6,10 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. Resolve library: `npx ctx7@latest library <name> "<user's question>"` — use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs")2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question)-3. Fetch docs: `npx ctx7@latest docs <libraryId> "<user's question>"`+3. Fetch docs: `npx ctx7@latest docs <libraryId> "<user's question>"` — run a separate `docs` command per distinct concept if the question spans multiple topics, unless it's about how they interact4. Answer using the fetched documentation-You MUST call `library` first to get a valid ID unless the user provides one directly in `/org/project` format. Use the user's full question as the query -- specific and detailed queries return better results than vague single words. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.+You MUST call `library` first to get a valid ID unless the user provides one directly in `/org/project` format. Use the user's full question as the query — specific and detailed queries return better results than vague single words, but keep each query to a single concept unless the question is about how concepts interact; combined multi-topic queries dilute ranking and return shallow results for each topic. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.For version-specific docs, use `/org/project/version` from the `library` output (e.g., `/vercel/next.js/v14.3.0`).diff --git a/rules/context7-mcp.md b/rules/context7-mcp.mdindex fe994d41..bc6ccb3e 100644--- a/rules/context7-mcp.md+++ b/rules/context7-mcp.md@@ -1,4 +1,4 @@-Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.+Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.@@ -6,5 +6,5 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version-3. `query-docs` with the selected library ID and the user's full question (not single words)+3. `query-docs` with the selected library ID and the user's full question (not single words), scoped to a single concept. If the question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic4. Answer using the fetched docsdiff --git a/skills/context7-cli/references/docs.md b/skills/context7-cli/references/docs.mdindex ef5cae9b..6c06cb72 100644--- a/skills/context7-cli/references/docs.md+++ b/skills/context7-cli/references/docs.md@@ -78,16 +78,17 @@ IMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot### 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.+The query directly affects the quality of results. Be specific and include relevant details, but keep each query to one topic — if the question spans multiple distinct concepts, run a separate `ctx7 docs` command per concept instead of combining them, unless the question is about how the concepts interact. 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"` |+| Bad (too vague) | `"auth"` |+| Bad (too vague) | `"hooks"` |+| Bad (too broad) | `"routing and auth and caching in Next.js"` |-Use the user's full question as the query when possible — vague one-word queries return generic results.+Use the user's full question as the query when possible — vague one-word queries return generic results, and multi-topic queries dilute ranking and return shallow results for each topic.The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).diff --git a/skills/context7-mcp/SKILL.md b/skills/context7-mcp/SKILL.mdindex 234659d9..245b0800 100644--- a/skills/context7-mcp/SKILL.md+++ b/skills/context7-mcp/SKILL.md@@ -36,7 +36,9 @@ From the resolution results, choose based on:Call `query-docs` with:- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)-- `query`: The user's specific question+- `query`: The user's specific question, scoped to a single concept++If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact — combined queries dilute ranking and return shallow results for each topic.### Step 4: Use the Documentation@@ -48,6 +50,7 @@ Incorporate the fetched documentation into your response:## Guidelines-- **Be specific**: Pass the user's full question as the query for better results+- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept+- **One topic per query**: Split multi-topic questions into separate `query-docs` calls — resolve the library ID once, then query per concept, unless the question is about how the concepts interact- **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/find-docs/SKILL.md b/skills/find-docs/SKILL.mdindex 9125d077..da5f683c 100644--- a/skills/find-docs/SKILL.md+++ b/skills/find-docs/SKILL.md@@ -3,7 +3,7 @@ name: find-docsdescription: >-Retrieves up-to-date documentation, API references, and code examples for anydeveloper technology. Use this skill whenever the user asks about a specific- library, framework, SDK, CLI tool, or cloud service -- even for well-known ones+ library, framework, SDK, CLI tool, or cloud service — even for well-known oneslike React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. Yourtraining data may not reflect recent API changes or version updates.@@ -11,7 +11,7 @@ description: >-issues, "how do I" questions mentioning a library name, debugging that involveslibrary-specific behavior, setup instructions, and CLI tool usage.- Use even when you think you know the answer -- do not rely on training data+ Use even when you think you know the answer — do not rely on training datafor API details, signatures, or configuration options as they are frequentlyoutdated. Always verify against current docs. Prefer this over web search forlibrary documentation and API details.@@ -115,16 +115,17 @@ npx ctx7@latest docs /prisma/prisma "How to define one-to-many relations with ca### 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.+The query directly affects the quality of results. Be specific and include relevant details, but keep each query to one topic — if the question spans multiple distinct concepts, run a separate `docs` command per concept instead of combining them, unless the question is about how the concepts interact. 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"` |+| Bad (too vague) | `"auth"` |+| Bad (too vague) | `"hooks"` |+| Bad (too broad) | `"routing and auth and caching in Next.js"` |-Use the user's full question as the query when possible, vague one-word queries return generic results.+Use the user's full question as the query when possible — vague one-word queries return generic results, and multi-topic queries dilute ranking and return shallow results for each topic.The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).@@ -154,4 +155,5 @@ Do not silently fall back to training data — always tell the user why Context7- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`- Always run `npx ctx7@latest library` first — `npx ctx7@latest docs react "hooks"` will fail without a valid ID- Use descriptive queries, not single words — `"React useEffect cleanup function"` not `"hooks"`+- One topic per query — split `"routing and auth and caching"` into a separate `docs` command per concept, unless the question is about how they interact- Do not include sensitive information (API keys, passwords, credentials) in queries