Skip to content
Skills Library
Programming · Research

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

Licence
MIT
Last repository change
20.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
14
Scripts
5
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. When to Use
  2. When NOT to Use
  3. Workflow
  4. Agent Reference
  5. Common Mistakes
Original SKILL.md headings · 88 lines, 387 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.