reference-retrieval-skill

Based on user input, directly find relevant literature or automatically construct PubMed Boolean search queries to retrieve and filter references suitable for citation. Applicable for quickly finding high-quality evidence on specific topics and completing reference lists.

Quality

64%

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 ./scientific-skills/Evidence Insight/reference-retrieval-skill/SKILL.md

Quality

Content

63%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 delivers an actionable, well-sequenced search workflow with real bundled scripts and an explicit iteration loop, but it carries generic boilerplate sections that dilute conciseness and inlines content that would benefit from separate reference files. Workflow and actionability are its strongest dimensions.

Suggestions

Trim or remove the generic templated sections (When to Use/Not to Use, Output Contract, Input Validation, Quick Validation) that restate non-skill-specific guidance, keeping only reference-retrieval-specific guardrails.

Move the detailed selection criteria and citation output template into a references/ file (e.g., OUTPUT_FORMAT.md) and link to it from the body to improve progressive disclosure.

Add a short sample of the JSON fields returned by the scripts (pmid, title, is_oa, pmcid) so the Step 4 filtering instructions are directly executable without inspecting script source.

Dimension	Reasoning	Score
Conciseness	The core workflow is reasonably efficient, but several appended boilerplate sections (When to Use, Output Contract, Input Validation, Quick Validation) repeat generic, templated guidance such as "Use this skill when the user explicitly needs to perform the core task of reference-retrieval-skill" that adds tokens without adding skill-specific value.	3 / 5
Actionability	Provides concrete, copy-paste-ready commands ("python scripts/pubmed_search.py 'Metformin AND \"Type 2 Diabetes\"'", "--max 50") backed by real bundled scripts, with a worked Boolean example and a defined output format; minor gaps include no sample JSON payload to parse for the is_oa/pmcid filtering.	4 / 5
Workflow Clarity	Steps 1-4 are clearly sequenced with an explicit refine-iterate feedback loop (analyze cause, broaden/narrow, retry, max 5 rounds) and user checkpoints, but there is no hard validation gate before presenting results, leaving a minor checkpoint gap.	4 / 5
Progressive Disclosure	Bundle scripts are correctly referenced one level deep, but all guidance lives in a single ~160-line SKILL.md with inlined content (detailed filter criteria, output template, generic guardrail sections) that could be split into reference files; structure exists but is not optimally separated.	3 / 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 PubMed-focused reference retrieval capability with several concrete actions, but its 'when to use' guidance is a soft applicability clause rather than an explicit trigger phrase, capping completeness. Trigger term coverage is good but missing common synonyms.

Suggestions

Replace the 'Applicable for...' clause with an explicit 'Use when the user needs to find citable references, build a reference list, or run a PubMed Boolean/LitSense search' trigger phrase to raise completeness.

Add common synonyms users actually say ("citations", "papers", "PMID", "literature search") to broaden trigger term coverage.

Mention the semantic (LitSense) search path in the description so the stated capabilities match the bundled workflow.

Dimension	Reasoning	Score
Specificity	Names the PubMed domain and several concrete actions ("find relevant literature", "construct PubMed Boolean search queries", "retrieve and filter references", "completing reference lists"), but omits the semantic/LitSense path described in the body, so coverage is not fully comprehensive.	4 / 5
Completeness	The 'what' is clear, but the 'when' is only weakly implied via the soft "Applicable for quickly finding..." clause rather than an explicit "Use when..." trigger phrase, so it does not meet the explicit-trigger bar.	3 / 5
Trigger Term Quality	Includes natural terms users would say ("literature", "PubMed", "references", "high-quality evidence", "citation") with good coverage, but lacks common synonyms like "citations", "papers", or "PMID".	4 / 5
Distinctiveness Conflict Risk	The PubMed/citation-retrieval niche is fairly distinct with specific triggers, with only minor overlap risk against general literature-research skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aipoch/medical-research-skills
Path: scientific-skills/Evidence Insight/reference-retrieval-skill/SKILL.md
Commit: 63c61d3

Reviewed: 8 hours 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.