Skip to content

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

fix(cli): align find-docs skill with context7-cli rule guidance (#2863)

石岳峰84620bd48380
diff --git a/packages/cli/src/__tests__/find-docs-skill-alignment.test.ts b/packages/cli/src/__tests__/find-docs-skill-alignment.test.ts
new file mode 100644
index 00000000..5bd725df
--- /dev/null
+++ b/packages/cli/src/__tests__/find-docs-skill-alignment.test.ts
@@ -0,0 +1,35 @@
+import { describe, test, expect } from "vitest";
+import { readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "../../../..");
+const skillPath = join(repoRoot, "skills/find-docs/SKILL.md");
+const rulePath = join(repoRoot, "rules/context7-cli.md");
+
+describe("find-docs skill aligns with context7-cli rule", () => {
+ test("uses npx ctx7@latest as the canonical invocation style", async () => {
+ const skill = await readFile(skillPath, "utf-8");
+ expect(skill).toContain("npx ctx7@latest library");
+ expect(skill).toContain("npx ctx7@latest docs");
+ expect(skill).not.toMatch(/^ctx7 library/m);
+ expect(skill).not.toContain("ctx7 library nextjs");
+ });
+
+ test("documents official library naming guidance", async () => {
+ const skill = await readFile(skillPath, "utf-8");
+ const rule = await readFile(rulePath, "utf-8");
+
+ expect(skill).toContain('"Next.js" not "nextjs"');
+ expect(rule).toContain('"Next.js" not "nextjs"');
+ expect(skill).toContain('library "Next.js"');
+ });
+
+ test("does not recommend global install as the primary workflow", async () => {
+ const skill = await readFile(skillPath, "utf-8");
+ const npxIndex = skill.indexOf("npx ctx7@latest");
+ const globalInstallIndex = skill.indexOf("npm install -g ctx7@latest");
+ expect(npxIndex).toBeGreaterThanOrEqual(0);
+ expect(globalInstallIndex).toBeGreaterThan(npxIndex);
+ });
+});
diff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.md
index 99e5c6e1..9125d077 100644
--- a/skills/find-docs/SKILL.md
+++ b/skills/find-docs/SKILL.md
@@ -21,16 +21,17 @@ description: >-
Retrieve current documentation and code examples for any library using the Context7 CLI.
-Make sure the CLI is up to date before running commands:
+Run commands with `npx ctx7@latest` so setup always uses the latest CLI without a global install:
```bash
-npm install -g ctx7@latest
+npx ctx7@latest library <name> "<query>"
+npx ctx7@latest docs <libraryId> "<query>"
```
-Or run directly without installing:
+Optionally install globally if you prefer a bare `ctx7` command:
```bash
-npx ctx7@latest <command>
+npm install -g ctx7@latest
```
## Workflow
@@ -39,13 +40,13 @@ Two-step process: resolve the library name to an ID, then query docs with that I
```bash
# Step 1: Resolve library ID
-ctx7 library <name> <query>
+npx ctx7@latest library <name> "<query>"
# Step 2: Query documentation
-ctx7 docs <libraryId> <query>
+npx ctx7@latest docs <libraryId> "<query>"
```
-You MUST call `ctx7 library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
+You MUST call `library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
IMPORTANT: Do not run these commands more than 3 times per question. If you cannot find what you need after 3 attempts, use the best result you have.
@@ -54,11 +55,13 @@ IMPORTANT: Do not run these commands more than 3 times per question. If you cann
Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
```bash
-ctx7 library react "How to clean up useEffect with async operations"
-ctx7 library nextjs "How to set up app router with middleware"
-ctx7 library prisma "How to define one-to-many relations with cascade delete"
+npx ctx7@latest library React "How to clean up useEffect with async operations"
+npx ctx7@latest library "Next.js" "How to set up app router with middleware"
+npx ctx7@latest library Prisma "How to define one-to-many relations with cascade delete"
```
+Use the official library name with proper punctuation (e.g., "Next.js" not "nextjs", "Customer.io" not "customerio", "Three.js" not "threejs"). If results look wrong, try alternate spellings such as `next.js` before changing the query.
+
Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
### Result fields
@@ -92,22 +95,22 @@ If the user mentions a specific version, use a version-specific library ID:
```bash
# General (latest indexed)
-ctx7 docs /vercel/next.js "How to set up app router"
+npx ctx7@latest docs /vercel/next.js "How to set up app router"
# Version-specific
-ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
+npx ctx7@latest docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
```
-The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
+The available versions are listed in the `library` command output. Use the closest match to what the user specified.
## Step 2: Query Documentation
Retrieves up-to-date documentation and code examples for the resolved library.
```bash
-ctx7 docs /facebook/react "How to clean up useEffect with async operations"
-ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
-ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
+npx ctx7@latest docs /facebook/react "How to clean up useEffect with async operations"
+npx ctx7@latest docs /vercel/next.js "How to add authentication middleware to app router"
+npx ctx7@latest docs /prisma/prisma "How to define one-to-many relations with cascade delete"
```
### Writing good queries
@@ -134,14 +137,14 @@ Works without authentication. For higher rate limits:
export CONTEXT7_API_KEY=your_key
# Option B: OAuth login
-ctx7 login
+npx ctx7@latest 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`
+2. Suggest they authenticate for higher limits: `npx ctx7@latest 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.
@@ -149,6 +152,6 @@ Do not silently fall back to training data — always tell the user why Context7
## Common Mistakes
- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
-- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID
+- 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"`
- Do not include sensitive information (API keys, passwords, credentials) in queries