agent-researcher

Agent skill for researcher - invoke with $agent-researcher

1.88x

Quality

Does it follow best practices?

Impact

98%

1.88x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-researcher/SKILL.md

Quality

Discovery

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

This description is critically underspecified. It fails on every dimension: it names no concrete actions, includes no natural trigger terms, provides no guidance on when to use the skill, and is so generic it would conflict with many other skills. It essentially communicates nothing beyond a label and an invocation command.

Suggestions

Add specific concrete actions the skill performs, e.g., 'Searches academic papers, summarizes findings, compiles literature reviews, and extracts citations from research databases.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks for literature reviews, academic research, paper summaries, citation searches, or scholarly source gathering.'

Narrow the domain to distinguish from other skills, e.g., specify whether this is for academic research, market research, web research, or another specific type of investigation.

Dimension	Reasoning	Score
Specificity	The description provides no concrete actions whatsoever. 'Agent skill for researcher' is entirely vague and does not describe what the skill actually does.	1 / 3
Completeness	Neither 'what does this do' nor 'when should Claude use it' is answered. There is no explanation of capabilities and no 'Use when...' clause or equivalent trigger guidance.	1 / 3
Trigger Term Quality	The only potentially useful term is 'researcher,' which is overly generic. There are no natural keywords a user would say when needing this skill, aside from the invocation command '$agent-researcher.'	1 / 3
Distinctiveness Conflict Risk	'Researcher' is extremely generic and could overlap with any skill involving research, analysis, data gathering, or information retrieval. There are no distinct triggers to differentiate it.	1 / 3
	Total	4 / 12 Passed

Implementation

14%

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

This skill is a verbose, generic description of a research agent role that explains many concepts Claude already understands (code analysis, pattern recognition, dependency tracking). It lacks a clear executable workflow with validation checkpoints and instead provides abstract best practices and lengthy output templates. The MCP tool integration section provides some concrete value but is buried in excessive surrounding content.

Suggestions

Cut the content by 60-70%: remove Core Responsibilities (Claude knows what research is), Best Practices (generic advice), and Collaboration Guidelines (obvious coordination patterns). Focus on the specific MCP tool calls and search patterns unique to this system.

Add a clear sequential workflow with validation: e.g., '1. Search broadly → 2. Narrow findings → 3. Validate with cross-references → 4. Store verified findings in memory → 5. If gaps found, return to step 1'

Move the detailed YAML output format and MCP tool examples into separate reference files (e.g., OUTPUT_FORMAT.md, MCP_TOOLS.md) and link to them from a concise overview

Replace pseudocode bash comments (e.g., '# Example search patterns') with actual executable commands that Claude can copy-paste directly

Dimension	Reasoning	Score
Conciseness	Extremely verbose with extensive explanations of concepts Claude already knows (what code analysis is, what pattern recognition means, basic grep/glob usage). The research methodology, collaboration guidelines, and best practices sections are largely generic advice that doesn't add actionable value. The YAML output format template and multiple code blocks inflate token usage significantly.	1 / 3
Actionability	Contains some concrete code examples (grep patterns, MCP tool calls, search strategies) but much of the content is descriptive rather than instructive. The MCP tool integration examples show specific function signatures which is useful, but the research methodology and collaboration guidelines are abstract directives ('Be Thorough', 'Think Critically') rather than executable guidance.	2 / 3
Workflow Clarity	While numbered sections exist (Information Gathering, Pattern Analysis, etc.), there is no clear sequential workflow with validation checkpoints. The 'Broad to Narrow' search strategy hints at a sequence but lacks explicit validation or decision points. For a research agent that could make incorrect conclusions, there are no feedback loops or verification steps.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files. All content is inline including detailed YAML templates, multiple code blocks, and extensive guidelines that could be split into separate reference files. No bundle files are provided to support the content, and no navigation structure exists.	1 / 3
	Total	5 / 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/claude-flow
Commit: 2b9e2de

Reviewed: 3 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.