code-context

Code Context Retrieval

This skill provides 5 methods for retrieving code context. Select methods based on the target: public GitHub repos, library docs, code search, direct inspection, or post-clone web enrichment.

Token Isolation (Critical)

Never run any external lookup in the main context. Always spawn Task agents:

• DeepWiki: Agent calls read_wiki_structure / read_wiki_contents / ask_question, extracts architecture summary and key relationships, returns concise overview.
• Context7: Agent calls resolve-library-id then query-docs, extracts the minimum viable API surface and usage examples, returns copyable snippets with version notes.
• Exa: Agent calls get_code_context_exa, extracts minimum viable snippets, deduplicates near-identical results (mirrors, forks, repeated StackOverflow answers), returns copyable snippets + brief explanation.
• Git clone: Agent clones to /tmp/, reads entry points and core modules, runs rm -rf cleanup, returns file structure summary and key patterns.
• Web Search+Fetch: Agent runs WebSearch with version-anchored queries derived from clone findings, calls WebFetch on high-signal URLs, returns only validated insights cross-referenced against cloned code.

Main context stays clean regardless of search volume. Only final summaries return to the caller.

Method 1: DeepWiki (AI-powered repo documentation)

Best for: Well-known public GitHub repositories where you need architecture overview, component explanations, or high-level understanding fast.

Tools: read_wiki_structure, read_wiki_contents, ask_question

Process:

1. Call read_wiki_structure with the owner/repo (e.g., "facebook/react") to get topic list
2. Call read_wiki_contents for relevant topics, or ask_question for targeted queries
3. Use when you need: architecture diagrams, component relationships, design decisions

Strengths: Zero setup, instant AI-summarized documentation, good for onboarding to unfamiliar repos.

Limitations: Only works for public GitHub repos; coverage varies by project popularity.

Method 2: Context7 (library documentation)

Best for: Getting up-to-date API docs, usage examples, and version-specific documentation for npm/pip packages and frameworks.

Tools: resolve-library-id, query-docs

Process:

1. Call resolve-library-id with the library name (e.g., "react", "fastapi") to get the canonical ID
2. When the user specifies a version (e.g., "react@18"), select the matching version from the versions list returned by resolve-library-id and append it to the library ID path (e.g., /facebook/react/18.3.1)
3. Call query-docs with libraryId and query — these are the only two parameters

Query tips: Be specific -- "useCallback dependency array" beats "react hooks". Include the framework version when known.

Version pinning: Encode version into the library ID path (e.g., /vercel/next.js/v14.3.0-canary.87), not as a separate parameter. Use the versions list from resolve-library-id to pick the correct slug.

Strengths: Always current docs, supports version pinning, covers thousands of libraries, excellent for API reference.

Limitations: Requires the library to be indexed; less useful for internal/private packages.

Method 3: Exa Code Search (web-wide code examples)

Best for: Finding real-world usage patterns, StackOverflow-style answers, GitHub Gist examples, and code snippets from across the web.

Tool: get_code_context_exa

Setup: Works without an API key (free tier with rate limits). For higher limits, set the EXA_API_KEY environment variable.

Process:

1. Call get_code_context_exa with a precise query
2. Set tokensNum based on need: 3000 for quick examples, 8000 for comprehensive patterns
3. Verify publication dates on results; prefer recent sources

Query writing guidance:

• Include the language or framework: "TypeScript React" not just "React"
• Include the version when relevant: "Next.js 14 app router"
• Use exact identifiers: "useServerAction" not "server action hook"
• Add the pattern type: "example", "error handling", "migration guide"
• Example: "TypeScript Next.js 14 app router server action error handling example"

Strengths: Finds diverse real-world examples, not limited to official docs, surfaces community solutions.

Limitations: Results may be outdated; always check publication dates and verify against official docs.

Method 4: Git Clone (direct code inspection)

Best for: Private repositories, detailed implementation review, running local analysis, or when other methods lack depth.

Process:

1. Run git clone <repo-url> /tmp/<repo-name> --depth=1 to fetch the code
2. Read key files: entry points, configuration, core modules
3. Map the file structure and search for patterns across the codebase
4. Clean up when done: rm -rf /tmp/<repo-name>

Strengths: Full code access, works with private repos (with credentials), enables static analysis tools.

Limitations: Requires network access and disk space; slow for large repos; credentials needed for private repos.

Method 5: Web Search + Fetch

Best for: Concepts, rationale, "best practice" questions, changelogs, issue discussions, blog posts, and migration guides that live outside source code. Two modes:

• Standalone — primary method for natural-language targets that ask "why" / "best practice for Z" / "compare X vs Y" without needing a clone.
• Post-clone enrichment — secondary, after Method 4: the clone gives the code, this gives the why and what changed.

Tools: WebSearch, WebFetch

When to apply: Standalone for concept / rationale / best-practice queries; post-clone when enriching a repo inspection with context not in the source.

Process:

1. Derive targeted queries — from clone findings (use exact identifiers, error strings, or design patterns found in the source) for post-clone mode, or directly from the natural-language target for standalone mode
2. Call WebSearch with query set to a precise, version-anchored string (e.g., "<library> <version> breaking change <symbol>")
3. For each high-signal result, call WebFetch with url (from search results) and a focused prompt to extract only the relevant section
4. Cross-reference fetched content against cloned code when available; against official docs otherwise
5. Discard results older than 2 years unless the topic is stable/foundational

Query patterns:

• Changelogs: "<repo-name> CHANGELOG v<version>" or "<repo-name> release notes"
• Design rationale: "<repo-name> <concept> why OR rationale site:github.com"
• Known issues: "<repo-name> <symbol or pattern> issue OR bug site:github.com"
• Migration: "<repo-name> migrate from <old-version> to <new-version>"

Strengths: Surfaces context that never appears in source code — deprecation notices, upstream issue threads, author blog posts, community migration experiences.

Limitations: Results may be stale or inaccurate; always validate fetched claims against the actual cloned code. Rate-limited without API key.

Target Classification

Each input target falls into one of three kinds. Classify before selecting a method:

• Repo target — owner/repo slug or git URL. Use DeepWiki (public) or Git Clone (private / deeper detail).
• Library target — bare package/framework name, optionally name@version. Use Context7; encode version into the libraryId path.
• Natural-language target — a question, comparison, or concept ("how does X work", "X vs Y", "best practice for Z"). Use Exa for code patterns; Web Search+Fetch for rationale, changelogs, and "why" questions. If the query names a specific library, also run Context7 for the canonical API surface.

When the caller passes --method=, only use the intersection of allowed methods and applicable methods. If the intersection is empty for a target, skip external lookups for that target and report that no allowed method applies.

Method Selection Guide

Scenario	Primary Method	Fallback
"How does X library work?"	Context7	DeepWiki
"Understand the architecture of Y repo"	DeepWiki	Git Clone
"Find examples of Z pattern"	Exa	Context7
"Inspect private/internal repo"	Git Clone	-
"What changed in v3 of library?"	Context7	Exa
"How are modules connected?"	DeepWiki	Git Clone
"Why was this design decision made?"	Git Clone → Web Search+Fetch	DeepWiki
"What broke between versions?"	Web Search+Fetch	Context7
"Compare X vs Y" (natural-language)	Exa + Context7	Web Search+Fetch
"Best practice for Z" (natural-language)	Web Search+Fetch	Exa

Combining Methods

For comprehensive context, combine methods:

1. DeepWiki for architecture overview
2. Context7 for specific API details
3. Exa for community usage patterns
4. Git Clone for implementation details when needed

Always prefer non-destructive read-only operations. When cloning, use /tmp and clean up after.