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
62
72%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./researching-codebases/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has a clear 'Use when' clause that addresses both what and when, which is its strongest aspect. However, the capabilities described are somewhat abstract ('locate, analyze, and synthesize findings') rather than listing concrete actions, and the trigger terms could better match natural user language. The mention of 'parallel sub-agents' is an implementation detail that doesn't help with skill selection.
Suggestions
Replace implementation jargon like 'parallel sub-agents' with user-facing capability descriptions, e.g., 'searches across multiple files simultaneously to trace dependencies, map call chains, and explain component interactions'.
Add more natural trigger terms users would say, such as 'code architecture', 'how does X work', 'trace through the code', 'find all usages', 'understand dependencies'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (codebase analysis) and describes some actions ('locate, analyze, and synthesize findings', 'coordinates parallel sub-agents'), but the actions are somewhat abstract rather than listing multiple concrete operations like 'trace call chains, find dependencies, map component relationships'. | 2 / 3 |
Completeness | Clearly answers both what ('coordinates parallel sub-agents to locate, analyze, and synthesize findings') and when ('when answering complex questions about a codebase that require exploring multiple areas or understanding how components connect') with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'codebase', 'complex questions', 'components connect', but misses many natural user phrases like 'how does this work', 'code architecture', 'trace through', 'find where', 'code exploration', 'understand the code'. The phrase 'parallel sub-agents' is implementation jargon users wouldn't say. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'complex questions about a codebase' and 'parallel sub-agents' provides some distinctiveness, but 'exploring multiple areas' and 'understanding how components connect' could overlap with general code search, code review, or architecture documentation skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured coordination skill with clear workflow sequencing and good scoping (when to use / when not to use). Its main weakness is the lack of concrete, executable examples — the steps describe what to do conceptually but don't show specific tool invocations or example outputs. The progressive disclosure pattern is sound but unverifiable without bundle files.
Suggestions
Add a concrete example of spawning parallel agents (e.g., show an actual `task` tool invocation with a specific `subagent_type` and task description)
Include an example of a complete research question decomposition showing input question → decomposed sub-tasks → synthesized output structure
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It avoids explaining concepts Claude already knows (like what sub-agents are or how codebases work), uses terse bullet points, and every section earns its place. The 'When NOT to Use' section efficiently scopes the skill. | 3 / 3 |
Actionability | The workflow provides clear steps but lacks concrete, executable examples. References to scripts like `list-research.py`, `gather-metadata.py` are mentioned but no actual commands or invocations are shown. The agent spawning step says 'Use the task tool with appropriate subagent_type' without showing a concrete example of what that looks like. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced (steps 0-5) with explicit ordering constraints ('Read mentioned files FIRST before spawning agents', 'Wait for ALL agents to complete before synthesizing'). The bold warnings in Common Mistakes serve as validation checkpoints. The conditional steps (0 and 5) are clearly marked as optional. | 3 / 3 |
Progressive Disclosure | The skill references several external files (`research-tools.md`, `agent-selection.md`, `output-format.md`) which is good progressive disclosure structure, but no bundle files were provided to verify these exist. The references are one-level deep and clearly signaled, but without the bundle we can't confirm the structure is actually supported. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- joshuadavidthomas/agent-skills
- Commit
40067f1
- Reviewed
Table of Contents
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.