agent-researcher

Agent skill for researcher - invoke with $agent-researcher

1.88x

Quality

25%

Does it follow best practices?

Impact

98%

1.88x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-researcher/SKILL.md

Quality

Content

42%Weight 40%Scale 1-5

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

The body is a serviceable outline of a research agent's responsibilities but is padded with generic best-practice advice, and its code examples are non-executable pseudo-syntax. It also carries a structural defect: a second YAML frontmatter block sits in the body where the overview should begin.

Suggestions

Fix the code fences: move the bullet-list 'search patterns' out of the ```bash block into prose, and rewrite the MCP examples as actual tool-call syntax or short descriptions instead of invalid pseudo-JavaScript.

Trim the Best Practices and 'Remember:' closing paragraph — 'Be Thorough', 'Think Critically', 'Document Everything' are generic guidance Claude already applies; keep only instructions specific to this agent's coordination protocol.

Remove the duplicated '---' YAML block from the body (or reduce it to a one-line agent identity note), and consider moving the research-output schema and MCP memory examples into a references/ file so SKILL.md stays a lean overview.

Dimension	Reasoning	Score
Conciseness	The body spends significant tokens on padded exhortation ('Remember: Good research is the foundation of successful implementation', 'Be Thorough: Check multiple sources') and explains search techniques Claude already knows, matching 'noticeably verbose; several unnecessary explanations or padded sections'.	2 / 5
Actionability	Concrete grep/glob patterns are embedded, but the 'Pattern Analysis' bash block contains a bullet list inside a shell fence (not executable) and the 'javascript' MCP blocks use pseudo-syntax like 'mcp__claude-flow__memory_usage { ... }' that is neither valid JS nor a real tool invocation — matching 'pseudocode instead of executable code; missing key details'.	3 / 5
Workflow Clarity	The four methodology phases (Information Gathering, Pattern Analysis, Dependency Analysis, Documentation Mining) read as topical sections rather than a sequenced workflow; there is no ordering between phases and no validation checkpoints, matching 'steps listed but validation gaps; checkpoints missing or implicit'.	3 / 5
Progressive Disclosure	Section headers give real structure, but this ~170-line single file inlines an agent-definition YAML block (with a stray duplicated '---' fence), a full research-output schema, and MCP integration examples that would belong in separate reference files; no bundle files exist at all.	3 / 5
	Total	11 / 20 Passed

Description

8%Weight 40%Scale 1-5

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 is effectively a placeholder: it describes how to invoke the skill rather than what the skill does or when to use it. A user reading it could not decide whether to trigger this skill over any other research-related skill.

Suggestions

Rewrite the description to state concrete capabilities, e.g. 'Performs deep codebase research: analyzes code structure, maps dependencies, identifies patterns and anti-patterns, and synthesizes findings into actionable recommendations.'

Add an explicit 'Use when...' trigger clause, e.g. 'Use when investigating an unfamiliar codebase, mapping dependencies, or gathering context before planning or implementing changes.'

Remove the '$agent-researcher' invocation token from the description — it is launcher syntax, not capability or trigger information, and it crowds out useful terms users would actually say.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Agent skill for researcher') but lists zero concrete actions; the remainder ('invoke with $agent-researcher') is pure invocation mechanics, matching the 'names the domain but actions are minimal or generic' anchor.	2 / 5
Completeness	Neither 'what does this do' (no capabilities stated) nor 'when to use it' (no trigger guidance) is present, matching the 'missing both what and when' anchor.	1 / 5
Trigger Term Quality	No natural keywords a user would say appear; '$agent-researcher' is an internal invocation token, matching 'no natural keywords; only technical jargon or entirely generic language'.	1 / 5
Distinctiveness Conflict Risk	'Agent skill for researcher' is broad and would overlap with any research or analysis skill; the '$agent-researcher' token adds slight identity but overlap risk stays high.	2 / 5
	Total	6 / 20 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: ruvnet/ruflo
Path: .agents/skills/agent-researcher/SKILL.md
Commit: b14c79e

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.