diff --git a/.changeset/giant-numbers-divide.md b/.changeset/giant-numbers-divide.md new file mode 100644 index 000000000..f5d62daa8 --- /dev/null +++ b/.changeset/giant-numbers-divide.md @@ -0,0 +1,8 @@ +--- +"@upstash/context7-tools-ai-sdk": patch +"ctx7": patch +"@upstash/context7-mcp": patch +"@upstash/context7-pi": patch +--- + +Improve query prompts so agents request relevant library documentation instead of passing the task to complete. diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.ts index 28ee67a60..59a343bea 100644 --- a/packages/cli/src/commands/docs.ts +++ b/packages/cli/src/commands/docs.ts @@ -219,7 +219,7 @@ export function registerDocsCommands(program: Command): void { program .command("library") .argument("", "Library name to search for") - .argument("[query]", "Question or task for relevance ranking") + .argument("[query]", "What to look up in the library's documentation") .option("--json", "Output as JSON") .description("Resolve a library name to a Context7 library ID") .action(async (name: string, query: string | undefined, options: { json?: boolean }) => { diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.ts index b8ddb04ef..5a37da5b4 100644 --- a/packages/cli/src/setup/templates.ts +++ b/packages/cli/src/setup/templates.ts @@ -9,9 +9,9 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo ## Steps -1. \`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") +1. \`resolve-library-id\` with the library name and what to look up in the library's documentation. 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), 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 topic +3. \`query-docs\` with the selected library ID and what to look up in the library's documentation (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 topic 4. Answer using the fetched docs `; @@ -21,12 +21,12 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo ## Steps -1. Resolve library: \`npx ctx7@latest library ""\` +1. Resolve library: \`npx ctx7@latest library ""\` 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 ""\` — run a separate \`docs\` command per distinct concept if the question spans multiple topics, unless it's about how they interact +3. Fetch docs: \`npx ctx7@latest docs ""\` — run a separate \`docs\` command per distinct concept if the question spans multiple topics, unless it's about how they interact 4. 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, 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. +You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Be specific about what to look up in the library's documentation — 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.ts index 566bb38ed..78cc7c978 100644 --- a/packages/mcp/src/index.ts +++ b/packages/mcp/src/index.ts @@ -172,7 +172,7 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f query: z .string() .describe( - "The question or task you need help with. This is used to rank library results by relevance to what the user is trying to accomplish. 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." + "What to look up in the library's documentation. This is used to rank library results by relevance to what the user is trying to accomplish. 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." ), libraryName: z .string() @@ -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, 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." + "What to look up in the library's documentation, 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/__tests__/extension.test.ts b/packages/pi/__tests__/extension.test.ts index bd0b54d56..544809164 100644 --- a/packages/pi/__tests__/extension.test.ts +++ b/packages/pi/__tests__/extension.test.ts @@ -52,5 +52,5 @@ describe("live Context7 API", () => { ); expect(result.content[0].type).toBe("text"); expect((result.content[0] as { text: string }).text).toMatch(/react/i); - }); + }, 15_000); }); diff --git a/packages/pi/lib/prompts.ts b/packages/pi/lib/prompts.ts index a4d1ba33a..56d7663de 100644 --- a/packages/pi/lib/prompts.ts +++ b/packages/pi/lib/prompts.ts @@ -40,7 +40,7 @@ For ambiguous queries, request clarification before proceeding with a best-guess IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`; export const RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION = - "The question or task you need help with. This is used to rank library results by relevance to what the user is trying to accomplish. 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."; + "What to look up in the library's documentation. This is used to rank library results by relevance to what the user is trying to accomplish. 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."; export const RESOLVE_LIBRARY_ID_LIBRARY_NAME_DESCRIPTION = "Library name to search for and retrieve a Context7-compatible library ID. Use the official library name with proper punctuation — e.g., 'Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio', 'Three.js' instead of 'threejs'."; @@ -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, 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."; + "What to look up in the library's documentation, 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/prompts/c7-docs.md b/packages/pi/prompts/c7-docs.md index ba96e08b0..c8a26f876 100644 --- a/packages/pi/prompts/c7-docs.md +++ b/packages/pi/prompts/c7-docs.md @@ -5,8 +5,9 @@ argument-hint: Look up documentation for `$1` using Context7. -1. Call the `resolve-library-id` tool with `libraryName="$1"` and `query="${@:2}"` to find the best matching library. -2. Call the `query-docs` tool with the selected library ID and `query="${@:2}"`. -3. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used. +1. Determine what to look up in the library's documentation from `${@:2}`. +2. Call the `resolve-library-id` tool with `libraryName="$1"` and what to look up as `query` to find the best matching library. +3. Call the `query-docs` tool with the selected library ID and what to look up as `query`. +4. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used. -If `$1` is already in `/org/project` or `/org/project/version` format, skip step 1 and call `query-docs` directly. +If `$1` is already in `/org/project` or `/org/project/version` format, skip library resolution and call `query-docs` directly. diff --git a/packages/pi/skills/context7-docs/SKILL.md b/packages/pi/skills/context7-docs/SKILL.md index 1556e3118..4e5b6008f 100644 --- a/packages/pi/skills/context7-docs/SKILL.md +++ b/packages/pi/skills/context7-docs/SKILL.md @@ -32,8 +32,8 @@ Reach for these tools whenever a question involves a specific library, framework ## Workflow -1. **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, 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. +1. **Resolve the library ID.** Call `resolve-library-id` with the library name and what to look up in the library's documentation. 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 what to look up in the library's documentation, 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/prompts/system.ts b/packages/tools-ai-sdk/src/prompts/system.ts index bd0458c54..474664c7e 100644 --- a/packages/tools-ai-sdk/src/prompts/system.ts +++ b/packages/tools-ai-sdk/src/prompts/system.ts @@ -34,9 +34,9 @@ Step 2: Analyze the results from resolveLibraryId and select the BEST library ID - Code snippet coverage (higher is better) - Benchmark score (higher is better) -Step 3: Call 'queryDocs' with the selected library ID and the user's query +Step 3: Call 'queryDocs' with the selected library ID and what to look up in the library's documentation - Use the exact library ID from the resolveLibraryId results - - Include the user's original question as the query parameter + - Pass what to look up in the library's documentation as the query parameter Step 4: Provide a clear answer with code examples from the documentation diff --git a/packages/tools-ai-sdk/src/tools/query-docs.ts b/packages/tools-ai-sdk/src/tools/query-docs.ts index d07de22b8..8a5afe34a 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, 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." + "What to look up in the library's documentation, 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/packages/tools-ai-sdk/src/tools/resolve-library-id.ts b/packages/tools-ai-sdk/src/tools/resolve-library-id.ts index 4cdc11204..7f3edb7ca 100644 --- a/packages/tools-ai-sdk/src/tools/resolve-library-id.ts +++ b/packages/tools-ai-sdk/src/tools/resolve-library-id.ts @@ -40,7 +40,7 @@ export function resolveLibraryId(config: Context7ToolsConfig = {}) { query: z .string() .describe( - "The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query." + "What to look up in the library's documentation. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query." ), libraryName: z .string() diff --git a/plugins/claude/context7/agents/docs-researcher.md b/plugins/claude/context7/agents/docs-researcher.md index ebd408a61..9653aa7e7 100644 --- a/plugins/claude/context7/agents/docs-researcher.md +++ b/plugins/claude/context7/agents/docs-researcher.md @@ -16,7 +16,7 @@ When given a question about a library or framework, fetch the relevant documenta 2. **Resolve the library ID**: Call `resolve-library-id` with: - `libraryName`: The library name (e.g., "react", "next.js", "prisma") - - `query`: The user's full question for relevance ranking + - `query`: What to look up in the library's documentation for relevance ranking 3. **Select the best match**: From the results, pick the library with: - Exact or closest name match @@ -25,7 +25,7 @@ When given a question about a library or framework, fetch the relevant documenta 4. **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, scoped to a single concept + - `query`: What to look up in the library's documentation for targeted results, scoped to a single concept 5. **Return a focused answer**: Summarize the relevant documentation with: - Direct answer to the question @@ -34,7 +34,7 @@ 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, but keep each query to a single concept +- Describe what to look up in the library's documentation in the query parameter, 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 diff --git a/plugins/claude/context7/skills/context7-mcp/SKILL.md b/plugins/claude/context7/skills/context7-mcp/SKILL.md index 245b08005..90542d4ef 100644 --- a/plugins/claude/context7/skills/context7-mcp/SKILL.md +++ b/plugins/claude/context7/skills/context7-mcp/SKILL.md @@ -21,7 +21,7 @@ Activate this skill when the user: Call `resolve-library-id` with: - `libraryName`: The library name extracted from the user's question -- `query`: The user's full question (improves relevance ranking) +- `query`: What to look up in the library's documentation (improves relevance ranking) ### Step 2: Select the Best Match @@ -36,7 +36,7 @@ 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, scoped to a single concept +- `query`: What to look up in the library's documentation, 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. @@ -50,7 +50,7 @@ Incorporate the fetched documentation into your response: ## Guidelines -- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **Be specific**: Describe what to look up in the library's documentation, 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 forks diff --git a/plugins/codex/context7/skills/context7-mcp/SKILL.md b/plugins/codex/context7/skills/context7-mcp/SKILL.md index 245b08005..90542d4ef 100644 --- a/plugins/codex/context7/skills/context7-mcp/SKILL.md +++ b/plugins/codex/context7/skills/context7-mcp/SKILL.md @@ -21,7 +21,7 @@ Activate this skill when the user: Call `resolve-library-id` with: - `libraryName`: The library name extracted from the user's question -- `query`: The user's full question (improves relevance ranking) +- `query`: What to look up in the library's documentation (improves relevance ranking) ### Step 2: Select the Best Match @@ -36,7 +36,7 @@ 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, scoped to a single concept +- `query`: What to look up in the library's documentation, 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. @@ -50,7 +50,7 @@ Incorporate the fetched documentation into your response: ## Guidelines -- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **Be specific**: Describe what to look up in the library's documentation, 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 forks diff --git a/plugins/context7-power/POWER.md b/plugins/context7-power/POWER.md index b6759e400..13740fb9d 100644 --- a/plugins/context7-power/POWER.md +++ b/plugins/context7-power/POWER.md @@ -31,9 +31,9 @@ Do not use this Power for refactoring, writing scripts from scratch, debugging b Call `resolve-library-id` with: - `libraryName`: The library name extracted from the user's question -- `query`: The user's full question (improves relevance ranking) +- `query`: What to look up in the library's documentation (improves relevance ranking) -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` format +Always start with `resolve-library-id` using the library name and what to look up in the library's documentation, unless the user provides an exact library ID in `/org/project` format ### Step 2: Select the Best Match @@ -49,7 +49,7 @@ 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, scoped to a single concept +- `query`: What to look up in the library's documentation, scoped to a single concept and using more than a single word 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. @@ -63,7 +63,7 @@ Incorporate the fetched documentation into your response: ## Best Practices -- Pass the user's full question as the query for better results, but keep each query to a single concept +- Describe what to look up in the library's documentation, 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 @@ -75,4 +75,4 @@ Incorporate the fetched documentation into your response: This power integrates with the Context7 MCP Server (MIT License). - [Privacy Policy](https://upstash.com/trust/context7addendum.pdf) -- [Support](mailto:context7@upstash.com) \ No newline at end of file +- [Support](mailto:context7@upstash.com) diff --git a/plugins/copilot/context7/agents/docs-researcher.agent.md b/plugins/copilot/context7/agents/docs-researcher.agent.md index de3309ba2..90433d49d 100644 --- a/plugins/copilot/context7/agents/docs-researcher.agent.md +++ b/plugins/copilot/context7/agents/docs-researcher.agent.md @@ -15,7 +15,7 @@ When given a question about a library or framework, fetch the relevant documenta 2. **Resolve the library ID**: Call `resolve-library-id` with: - `libraryName`: The library name (e.g., "react", "next.js", "prisma") - - `query`: The user's full question for relevance ranking + - `query`: What to look up in the library's documentation for relevance ranking 3. **Select the best match**: From the results, pick the library with: - Exact or closest name match @@ -24,7 +24,7 @@ When given a question about a library or framework, fetch the relevant documenta 4. **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, scoped to a single concept + - `query`: What to look up in the library's documentation for targeted results, scoped to a single concept 5. **Return a focused answer**: Summarize the relevant documentation with: - Direct answer to the question @@ -33,7 +33,7 @@ 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, but keep each query to a single concept +- Describe what to look up in the library's documentation in the query parameter, 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 diff --git a/plugins/copilot/context7/skills/context7-mcp/SKILL.md b/plugins/copilot/context7/skills/context7-mcp/SKILL.md index 245b08005..90542d4ef 100644 --- a/plugins/copilot/context7/skills/context7-mcp/SKILL.md +++ b/plugins/copilot/context7/skills/context7-mcp/SKILL.md @@ -21,7 +21,7 @@ Activate this skill when the user: Call `resolve-library-id` with: - `libraryName`: The library name extracted from the user's question -- `query`: The user's full question (improves relevance ranking) +- `query`: What to look up in the library's documentation (improves relevance ranking) ### Step 2: Select the Best Match @@ -36,7 +36,7 @@ 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, scoped to a single concept +- `query`: What to look up in the library's documentation, 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. @@ -50,7 +50,7 @@ Incorporate the fetched documentation into your response: ## Guidelines -- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **Be specific**: Describe what to look up in the library's documentation, 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 forks diff --git a/plugins/cursor/context7/agents/docs-researcher.md b/plugins/cursor/context7/agents/docs-researcher.md index de3309ba2..90433d49d 100644 --- a/plugins/cursor/context7/agents/docs-researcher.md +++ b/plugins/cursor/context7/agents/docs-researcher.md @@ -15,7 +15,7 @@ When given a question about a library or framework, fetch the relevant documenta 2. **Resolve the library ID**: Call `resolve-library-id` with: - `libraryName`: The library name (e.g., "react", "next.js", "prisma") - - `query`: The user's full question for relevance ranking + - `query`: What to look up in the library's documentation for relevance ranking 3. **Select the best match**: From the results, pick the library with: - Exact or closest name match @@ -24,7 +24,7 @@ When given a question about a library or framework, fetch the relevant documenta 4. **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, scoped to a single concept + - `query`: What to look up in the library's documentation for targeted results, scoped to a single concept 5. **Return a focused answer**: Summarize the relevant documentation with: - Direct answer to the question @@ -33,7 +33,7 @@ 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, but keep each query to a single concept +- Describe what to look up in the library's documentation in the query parameter, 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 diff --git a/plugins/cursor/context7/skills/context7-mcp/SKILL.md b/plugins/cursor/context7/skills/context7-mcp/SKILL.md index 245b08005..90542d4ef 100644 --- a/plugins/cursor/context7/skills/context7-mcp/SKILL.md +++ b/plugins/cursor/context7/skills/context7-mcp/SKILL.md @@ -21,7 +21,7 @@ Activate this skill when the user: Call `resolve-library-id` with: - `libraryName`: The library name extracted from the user's question -- `query`: The user's full question (improves relevance ranking) +- `query`: What to look up in the library's documentation (improves relevance ranking) ### Step 2: Select the Best Match @@ -36,7 +36,7 @@ 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, scoped to a single concept +- `query`: What to look up in the library's documentation, 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. @@ -50,7 +50,7 @@ Incorporate the fetched documentation into your response: ## Guidelines -- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **Be specific**: Describe what to look up in the library's documentation, 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 forks diff --git a/rules/context7-cli.md b/rules/context7-cli.md index def26cb9a..d0f72ae31 100644 --- a/rules/context7-cli.md +++ b/rules/context7-cli.md @@ -4,12 +4,12 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo ## Steps -1. Resolve library: `npx ctx7@latest library ""` — use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs") +1. Resolve library: `npx ctx7@latest library ""` — 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 ""` — run a separate `docs` command per distinct concept if the question spans multiple topics, unless it's about how they interact +3. Fetch docs: `npx ctx7@latest docs ""` — run a separate `docs` command per distinct concept if the question spans multiple topics, unless it's about how they interact 4. 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, 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. +You MUST call `library` first to get a valid ID unless the user provides one directly in `/org/project` format. Be specific about what to look up in the library's documentation — 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.md index bc6ccb3e6..089345244 100644 --- a/rules/context7-mcp.md +++ b/rules/context7-mcp.md @@ -4,7 +4,7 @@ Do not use for: refactoring, writing scripts from scratch, debugging business lo ## Steps -1. 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` format +1. Always start with `resolve-library-id` using the library name and what to look up in the library's documentation, unless the user provides an exact library ID in `/org/project` format 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). 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), 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 topic +3. `query-docs` with the selected library ID and what to look up in the library's documentation (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 topic 4. Answer using the fetched docs diff --git a/skills/context7-cli/references/docs.md b/skills/context7-cli/references/docs.md index 6c06cb72b..c2bbde475 100644 --- a/skills/context7-cli/references/docs.md +++ b/skills/context7-cli/references/docs.md @@ -88,7 +88,7 @@ The query directly affects the quality of results. Be specific and include relev | 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, and multi-topic queries dilute ranking and return shallow results for each topic. +Describe what to look up in the library's documentation in 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.md index 245b08005..90542d4ef 100644 --- a/skills/context7-mcp/SKILL.md +++ b/skills/context7-mcp/SKILL.md @@ -21,7 +21,7 @@ Activate this skill when the user: Call `resolve-library-id` with: - `libraryName`: The library name extracted from the user's question -- `query`: The user's full question (improves relevance ranking) +- `query`: What to look up in the library's documentation (improves relevance ranking) ### Step 2: Select the Best Match @@ -36,7 +36,7 @@ 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, scoped to a single concept +- `query`: What to look up in the library's documentation, 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. @@ -50,7 +50,7 @@ Incorporate the fetched documentation into your response: ## Guidelines -- **Be specific**: Pass the user's full question as the query for better results, but keep each query to a single concept +- **Be specific**: Describe what to look up in the library's documentation, 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 forks diff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.md index da5f683cd..314f57899 100644 --- a/skills/find-docs/SKILL.md +++ b/skills/find-docs/SKILL.md @@ -125,7 +125,7 @@ The query directly affects the quality of results. Be specific and include relev | 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, and multi-topic queries dilute ranking and return shallow results for each topic. +Describe what to look up in the library's documentation, rather than the task to complete — 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).