code-context

---
name: code-context
description: This skill should be used when the user asks to "understand a codebase", "get code context", "research a library", "explore a repository", "find code examples", "look up documentation", asks a natural-language code/technology question (e.g. "how does X work", "X vs Y", "best practice for Z"), or wants to understand how a specific project, library, or concept works before making changes.
user-invocable: false
---

# 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.