Context7 Rules and Skills
Overview
This area is the repository-level prompt surface for teaching agents when and how to use Context7. It is split between plain rule files under rules/** and installable skill packages under skills/**.
rules/context7-mcp.md is the MCP-oriented rule. It tells an agent to use Context7 MCP instead of web search or training data for current documentation about libraries, frameworks, SDKs, APIs, CLIs, and cloud services. Its workflow is resolve-library-id first, unless the user already gave an exact /org/project ID, then query-docs with a single-concept query. It also documents optional source-code lookup through query-code: use source-backed library IDs, start with grep or definition, follow the result's Next: instructions, pass git tags through version, retry temporary indexing for up to three minutes, and cite file/line evidence.
rules/context7-cli.md is the CLI-oriented rule for environments without MCP tools. It gives the same trigger conditions and non-goals, but maps the workflow to npx ctx7@latest library <name> "<what to look up>" followed by npx ctx7@latest docs <libraryId> "<what to look up>". It caps usage at three commands per question, requires the library command unless the user provides a /org/project ID, describes version-specific IDs as /org/project/version, and tells the agent to report quota failures with npx ctx7@latest login or CONTEXT7_API_KEY instead of silently falling back to stale knowledge.
skills/…/SKILL.md packages the MCP guidance as a skill named context7-mcp. Its front matter activates on library/framework/API questions, setup questions, code generation involving libraries, and framework mentions. The body mirrors the MCP rule but expands the activation examples and selection criteria, including version-aware library IDs and the query-code path for exact facts not present in docs.
skills/…/SKILL.md is a standalone CLI documentation lookup skill named find-docs. It is intended for CLI + Skills installs and uses npx ctx7@latest throughout so the agent does not need a global ctx7 install. It describes the two-step library then docs workflow, result fields returned by library resolution, selection heuristics, version-specific IDs, --language ranking for docs examples, authentication through CONTEXT7_API_KEY or npx ctx7@latest login, quota handling, and common mistakes such as missing the leading / in library IDs.
skills/…/SKILL.md is the broader CLI skill named context7-cli. It covers both documentation lookup and Context7 MCP setup. The skill points readers to skills/…/docs.md for command details and skills/…/setup.md for setup details, then gives a quick reference for ctx7 search, ctx7 library, ctx7 docs, ctx7 setup, ctx7 login, and ctx7 whoami. It also explains that most commands work without login, while ctx7 setup needs login unless --api-key or --oauth is provided.
skills/…/docs.md is the detailed CLI command reference. It documents ctx7 library for resolving IDs, ctx7 docs for querying a resolved ID, and ctx7 search for one-step search across all libraries. It defines the library result fields, the best-match selection process, version-specific IDs, JSON output flags, --language ranking, pipe-friendly output, library narrowing for search, and authentication for higher limits.
skills/…/setup.md is the setup reference. It documents ctx7 setup modes: MCP server mode registers the Context7 MCP server and writes a Context7 rule plus context7-mcp skill, while CLI + Skills mode installs the find-docs skill and a CLI-oriented Context7 rule. It lists agent targets for Claude Code, Cursor, OpenCode, Antigravity, Pi, project-scoped setup, confirmation skipping, --api-key, and MCP-only --oauth.
Coupling
- If the core Context7 documentation workflow changes, update both rules and both documentation skills together: rules/context7-mcp.md, rules/context7-cli.md, skills/…/SKILL.md, skills/…/SKILL.md, and skills/…/docs.md all encode the same resolve-then-query contract. A mismatch changes agent behavior depending on whether the user installed rules, MCP skills, or CLI skills.
- If CLI command names, flags, auth behavior, or rate-limit handling change, verify every CLI-facing file: rules/context7-cli.md, skills/…/SKILL.md, skills/…/SKILL.md, skills/…/docs.md, and skills/…/setup.md. These files mix
npx ctx7@latest ...examples with barectx7 ...examples, so a command rename or flag change can leave one install path stale. - If setup install outputs change, keep skills/…/setup.md and skills/…/SKILL.md aligned with the packaged skill names under skills/…/SKILL.md and skills/…/SKILL.md. The setup reference promises that MCP mode writes the
context7-mcpskill and CLI + Skills mode writes thefind-docsskill. - If source-code lookup behavior changes, update both MCP-facing files: rules/context7-mcp.md and skills/…/SKILL.md. They are the only files in this area that document
query-code, source-backed library IDs, indexing retries, version tags, and file/line citations.
Risks
- rules/context7-cli.md, skills/…/SKILL.md, and skills/…/docs.md currently differ in how much CLI surface they expose: the rule and
find-docsskill focus onlibrary/docs, while the context7 CLI reference also documentssearch. If only one path is updated whensearchor the command-attempt limits change, agents installed through different setup modes may give conflicting instructions. - skills/…/setup.md is the only file that states exactly what
ctx7 setupwrites for MCP mode and CLI + Skills mode. If skill names or install targets change without updating this reference, users may look for the wrong installed skill paths or assume a rule file was written when setup no longer creates it.