researching-codebases
/researching-codebases
Use when answering complex questions about a codebase that require exploring multiple areas or understanding how components connect - coordinates parallel sub-agents to locate, analyze, and synthesize findings
- Author
- joshuadavidthomas ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 20.07.2026
Assessment and security
- Files in this package
- 14
- Scripts
- 5
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 20.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 5 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/gather-metadata.py, scripts/list-research.py, scripts/promote-research.py, scripts/read-research.py, scripts/search-research.py
What it does and when to use it
Use when answering complex questions about a codebase that require exploring multiple areas or understanding how components connect - coordinates parallel sub-agents to locate, analyze, and synthesize findings
Original author description
Use when answering complex questions about a codebase that require exploring multiple areas or understanding how components connect - coordinates parallel sub-agents to locate, analyze, and synthesize findings
How it works
- When to Use
- When NOT to Use
- Workflow
- Agent Reference
- Common Mistakes
SKILL.md preview
---
name: researching-codebases
description: Use when answering complex questions about a codebase that require exploring multiple areas or understanding how components connect - coordinates parallel sub-agents to locate, analyze, and synthesize findings
---
# Researching Codebases
Coordinate parallel sub-agents to answer complex codebase questions.
## When to Use
- Questions spanning multiple files or components
- "How does X work?" requiring tracing through code
- Finding patterns or examples across the codebase
- Understanding architectural decisions or data flow
## When NOT to Use
- Simple "where is X?" - use `code-locator` directly
- Single file questions - just read the file
- External/web research only - use `web-searcher` directly
## Workflow
### 0. Check past research (optional)
Before decomposing a new research question, consider checking for related past research:
1. Run `list-research.py` script to see recent research docs
2. Run `search-research.py` script with relevant keywords
3. If related research exists, run `read-research.py` script to load it
4. Build on previous findings instead of starting fresh
See `research-tools.md` for script usage.
### 1. Read mentioned files first
If the user references specific files, read them FULLY before spawning agents. This gives you context for decomposition.
### 2. Decompose the question
Break the query into parallel research tasks. Consider:
- Which areas of the codebase are relevant?
- Do I need locations, analysis, or examples?
- See `agent-selection.md` for agent capabilities
### 3. Spawn parallel agents
Launch multiple agents concurrently for independent tasks. Use the `task` tool with appropriate `subagent_type`.
**Wait for ALL agents to complete before synthesizing.**
### 4. Synthesize and respond
Combine findings into a coherent answer:
- Direct answer to the question
- Key `file:line` references
- Connections between components
- Open questions if any areas need more investigation
### 5. Offer to save (optional)
For substantial research, ask:
> Want me to save this to a research doc? (project: `.research/` or global: `~/.research/`)
Skip this for quick answers.
When saving:
1. Run `gather-metadata.py` script to get date, repo, branch, commit, cwd.
2. Add query (from user's question) and tags (from content)
3. Format YAML frontmatter per `output-format.md`
4. Create directory if it doesn't exist
5. Use filename: `{filename_date}_topic-slug.md`
## Agent Reference
See `agent-selection.md` for when to use each agent.
## Common Mistakes
**Spawning agents before reading context:** Read any files the user mentions first.
**Not waiting for all agents:** Synthesize only after ALL agents complete.
**Over-documenting simple answers:** Not every question needs a saved research doc.
**Sequential when parallel works:** If tasks are independent, spawn them together.
Files in this package (14)
- SKILL.md 3 KB
- agent-selection.md 1 KB
- output-format.md 2 KB
- research-tools.md 2 KB
- agents/README.md 1 KB
- agents/code-analyzer.md 4 KB
- agents/code-locator.md 4 KB
- agents/code-pattern-finder.md 6 KB
- agents/web-searcher.md 5 KB
- scripts/gather-metadata.py 2 KB
- scripts/list-research.py 5 KB
- scripts/promote-research.py 1 KB
- scripts/read-research.py 1 KB
- scripts/search-research.py 5 KB
Versions
The database has no other skills named researching-codebases.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version e58135280592 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90ring:exploring-codebases
Exploring a codebase across phases: scopes the target, detects architecture, components, and layers, deep-dives each discovered perspective, then synthesizes findings into actionable guidance with file:line evidence. Use to understand how a feature or system works before… - 100researching-with-deepwiki
Research GitHub, GitLab, and Bitbucket repositories using DeepWiki MCP server. Use when exploring unfamiliar codebases, understanding project architecture, or asking questions about how a specific open-source project works. Provides AI-powered repo analysis and RAG-based Q&A… - 100researching-code
Use this skill when the user asks an architectural or semantic question about a codebase — phrases like "how does X work?", "what's the architecture?", "help me understand this codebase", "find all components that use Y", "trace the data flow from A to B", "where is feature Z… - 100plan-update
Use when you need to update a plan document with deep research across all compiler passes. Launches parallel subagents to analyze how a topic affects every compiler phase, then consolidates findings into the plan doc. - 90codebase-exploration
Use when exploring, understanding, or answering questions about a Repowise-indexed codebase, including architecture, where code is implemented, how a module works, or which files are relevant before reading source. - 100parallel-exploring
Explore a large codebase in parallel by launching multiple explore subagents that each investigate a different area simultaneously. Use when onboarding onto a new project, understanding architecture, or investigating a cross-cutting concern.