code-research

name	code-research
description	Conducts in-depth code research using a tiered tool strategy. Use when investigating codebases, researching libraries/APIs, debugging errors, or understanding unfamiliar code patterns.

Perform comprehensive code research by intelligently selecting from built-in tools, lightweight scripts, and MCP servers. The skill prioritizes context-efficient approaches—using the simplest tool that gets the job done before escalating to heavier solutions.

<quick_start> Before any Bash command that uses ${AGENT_ROOT}, run:

source ./scripts/agent-env.sh

This resolves AGENT_ROOT to ./.agents in the current working directory.

When researching code, follow the tool escalation ladder:

1. Local first - For pure code lookup, invoke code-search skill first; otherwise use Grep/Glob/Read
2. Terminal research - Use fast CLI tools (w3m/lynx, curl, jq, rg, fd, gh) and DDG bangs
3. Built-in web - Use WebSearch/WebFetch for documentation and articles
4. Skills & Scripts - Use gh-cli skill for GitHub, scripts for Stack Overflow
5. MCP servers - Use Exa/Deepwiki/Chrome for complex research needs

Start simple. Escalate only when simpler tools fail. </quick_start>

<tool_hierarchy> Local codebase exploration:

• Grep - Search for patterns, function names, error messages in code
• Glob - Find files by pattern (e.g., **/*.ts, **/config.*)
• Read - Read specific files once you know what to look at

**Prefer Rust utils when available (speed/ergonomics):** - `rg` (ripgrep), `fd`, `bat`, `sd`, `xsv`, `hyperfine` **Code search routing (`code-search`)** - Use for dedicated local code finding tasks: - semantic search, structural/AST search, repo layout discovery, literal text matches - invoke first when the user intent is "find code in this repo" **Contextplus MCP** - Local code intelligence for large repos - Use for: structure trees, file skeletons, semantic symbol search, blast-radius checks - Always pass **repo-root-relative** paths (not cwd-relative paths) - Path normalization workflow: ```bash REPO_ROOT="$(git rev-parse --show-toplevel)" CWD="$(pwd)" TARGET="$CWD/src/lib.rs" # or any absolute target discovered from current task RELATIVE_PATH="$(python3 -c 'import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))' "$TARGET" "$REPO_ROOT")" # Use RELATIVE_PATH with contextplus tools ``` For any codebase question, explore locally first: ``` # If the primary intent is local code finding, route to code-search skill first Skill: code-search For complex research needs: ``` # Local code intelligence (Contextplus) # 1) compute repo-root-relative path before calling contextplus # 2) call contextplus with RELATIVE_PATH (for example: extensions/swe_distiller/src/lib.rs) Combine findings from all sources: - Cross-reference information across sources - Identify consensus patterns vs. edge cases - Note version-specific information (library versions matter!) - Cite sources when presenting findings Don't pass cwd-relative paths to contextplus when cwd is not repo root. Always normalize to repo-root-relative paths first. Don't skip local codebase exploration. The answer might already be in the code you're working with. Don't rely on one source. Cross-reference findings from multiple tools for accuracy. Don't ignore version information. Library APIs change—verify findings match the version in use. Don't spam endpoints with aggressive scraping. Use retries, backoff, and caching headers to avoid rate limits.