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

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./researching-codebases/SKILL.md

Quality

Content

77%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A concise, well-sequenced workflow with a real validation checkpoint, weakened by abstract decomposition/synthesis steps and by referencing .md bundle files that are not actually present.

Suggestions

Add a concrete decomposition example (e.g. a sample question split into 2-3 parallel agent prompts with their subagent_type) to make steps 2-3 executable.

Create the referenced research-tools.md, agent-selection.md, and output-format.md in ./references (or inline their content) so navigation links resolve.

Provide a brief synthesis template or output skeleton for step 4 so the response format is concrete rather than implied.

Dimension	Reasoning	Score
Conciseness	The body is lean and directive with no concept padding, no explanation of what sub-agents or research are, and every token earns its place.	3 / 3
Actionability	Concrete scripts are named and steps are sequenced, but the core decomposition and synthesis steps ('Break the query into parallel research tasks', 'Launch multiple agents concurrently') stay abstract without executable examples or copy-paste-ready guidance.	2 / 3
Workflow Clarity	A clear numbered 0-5 sequence is present with an explicit validation checkpoint ('Wait for ALL agents to complete before synthesizing') plus a Common Mistakes feedback section.	3 / 3
Progressive Disclosure	Structure is organized and referenced scripts (list-research.py, etc.) exist in ./scripts, but the referenced .md files (research-tools.md, agent-selection.md, output-format.md) do not exist in ./references, leaving navigation partly broken.	2 / 3
	Total	10 / 12 Passed

Description

77%Weight 40%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A solid description with an explicit trigger clause and concrete actions, but its trigger terms lean abstract and its scope is broad enough to risk overlap with neighboring skills.

Suggestions

Add the colloquial phrasings users actually say (e.g. 'how does X work?', 'trace data flow', 'find examples across the codebase') to broaden trigger coverage.

Sharpen distinctiveness by contrasting with related skills in the description itself (e.g. 'for multi-area questions that need parallel sub-agents, not single-file lookups').

Dimension	Reasoning	Score
Specificity	Names concrete actions ('locate, analyze, and synthesize findings', 'coordinates parallel sub-agents') in a specific domain (codebase research), matching the multiple-specific-actions anchor.	3 / 3
Completeness	Explicit 'Use when...' clause answers when, while 'coordinates parallel sub-agents to locate, analyze, and synthesize findings' answers what, satisfying both halves.	3 / 3
Trigger Term Quality	Phrases like 'complex questions about a codebase' and 'how components connect' are natural, but they are paraphrased concepts rather than the varied colloquial keywords users would say, so coverage is partial.	2 / 3
Distinctiveness Conflict Risk	The parallel-sub-agent niche is fairly distinct, but 'complex questions about a codebase' is broad enough to overlap with general code-locator/Explore skills.	2 / 3
	Total	10 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: joshuadavidthomas/agent-skills
Path: researching-codebases/SKILL.md
Commit: 516dee7

Reviewed: 11 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.