CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

best-practices-researcher

Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards.

55

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/03-plan/best-practices-researcher/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

60%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 presents a clearly sequenced, well-structured research workflow with explicit validation gates and some notably concrete artifacts (glob patterns, search-query templates). Its main weaknesses are redundancy across the research and synthesis phases, generic abstract direction in Phase 3, and stale-prone inline details (skill-mapping list, dated API anecdote) that inflate token cost without adding proportional guidance.

Suggestions

Merge Phase 2's two overlapping subsections into a single list and trim Phase 3's generic bullets to remove the duplicated online-research instructions.

Move the environment-specific skill-mapping list (Rails → dhh-rails-style, etc.) to a reference file so it can be maintained without loading into the core workflow.

Replace Phase 3's abstract directives with a concrete output template, e.g., a findings-report structure showing the "From skill / From official docs / Community" attribution labels and a Must Have / Recommended / Optional table.

DimensionReasoningScore

Conciseness

The phased structure avoids explaining concepts Claude already knows, but there is real redundancy: Phase 2's "Leverage External Sources" and "Online Research Methodology" subsections repeat the same instructions, Phase 3's subsections overlap, the environment-specific skill-mapping list (10 lines) will go stale, and a dated anecdote ("Google Photos Library API scopes were deprecated March 2025") is embedded as rationale rather than placed in a deprecated/old-patterns section. This is more than the "minor instances" of the 4 anchor but not the heavy concept-padding of the 2 anchor.

3 / 5

Actionability

There are genuinely concrete elements — exact glob patterns ("**/**/SKILL.md"), exact search-query templates ("[API name] deprecated [current year] sunset shutdown"), and a named tool (Context7 MCP) — but a significant portion of the body, especially Phase 3 ("Organize into clear categories", "Provide specific examples", "Deliver Actionable Guidance") and the Special Cases section, is abstract direction Claude would follow anyway. Concrete guidance is present but incomplete relative to the 4 anchor.

3 / 5

Workflow Clarity

The sequence is explicit and enforced ("Follow This Order": Phase 1 → 1.5 → 2 → 3) with decision branching based on skill coverage and a mandatory validation gate in Phase 1.5 ("Report findings before proceeding - do not recommend deprecated APIs"). No destructive or batch operations apply, so no cap. It falls short of the 5 anchor because there are no error-recovery feedback loops or checklists.

4 / 5

Progressive Disclosure

The body is well-sectioned with clear headers, entirely one level deep, with no nested or buried references (no bundle files exist). The skill is over 50 lines, so the simple-skill exception to score 5 does not apply, and the inline environment-specific skill-mapping list is minor content that could live in a separately updatable reference file — a minor organization gap matching the 4 anchor.

4 / 5

Total

14

/

20

Passed

Description

66%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 clearly communicates a best-practices research capability with an explicit use-when clause and good natural keywords. Its weaknesses are second-person voice (triggering the specificity penalty), a when-clause that mirrors the what instead of naming concrete trigger scenarios, and an overly broad scope that raises conflict risk with general research skills.

Suggestions

Rewrite in third person or bare imperative voice (e.g., "Researches and synthesizes external best practices, official documentation, and open source examples. Use when the user asks how to implement a feature according to industry standards or wants conventions from respected projects.") to avoid the second-person penalty and sharpen triggers.

Narrow the scope qualifier "for any technology, framework, or development practice" to concrete trigger situations to reduce overlap with general research and documentation-lookup skills.

Add distinct when-triggers that do not simply restate the what, such as "Use when the user asks for conventions, standards, or how well-regarded projects handle a problem."

DimensionReasoningScore

Specificity

The description lists several actions ("research and gather external best practices, documentation, and examples", "finding official documentation, community standards", "synthesizing information from multiple sources") which would fit the 4 anchor, but it uses second person voice ("Use this agent when you need to research..."), which the judging guidelines penalize by reducing the specificity score by 1. The actions are also somewhat abstract (research/gather/synthesize) compared to concrete operations.

3 / 5

Completeness

Both what ("research and gather external best practices... synthesize") and when ("Use this agent when you need to research and gather external best practices...") are explicitly stated. However, the when-clause largely restates the capability rather than providing distinct concrete trigger scenarios, so it falls short of the 5 anchor's "concrete trigger phrases".

4 / 5

Trigger Term Quality

Natural terms users would say are present — "best practices", "documentation", "examples", "research", "community standards" — giving good keyword coverage. A few natural variations are missing (e.g., "conventions", "how to implement X properly", "industry standards" as a trigger rather than an outcome), so it does not reach comprehensive coverage.

4 / 5

Distinctiveness Conflict Risk

The niche (best-practices research and synthesis) is somewhat specific, but the scope claim "for any technology, framework, or development practice" is broad and would overlap with general web-research, documentation-lookup, and code-review skills. It is more specific than the 2 anchor's generic breadth, but not mostly distinct as the 4 anchor requires.

3 / 5

Total

14

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

marchatton/agent-skills

Path

.agents/skills/03-plan/best-practices-researcher/SKILL.md

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.