reference-finder

Automatically finds and ranks PubMed references for each sentence in scientific text; use when you need titles, DOIs, and brief recommendation reasons from the PubMed E-utilities API.

Quality

75%

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-finder/SKILL.md

Quality

Content

68%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.

A well-structured, mostly actionable skill body with good progressive disclosure and lean prose. The key weakness is workflow clarity: this batch, multi-call operation has no explicit validation or retry feedback loops, capping that dimension at 3.

Suggestions

Add explicit validation/feedback-loop checkpoints to the data flow (e.g., "If ESearch returns no PMIDs, fall back to full-text query and retry once"; "Verify each record has title + year before ranking") to lift workflow clarity.

Resolve the Python import path (the example uses `from reference_finder import find_references` but the function lives in scripts/find_refs.py) so the snippet is copy-paste runnable.

Either create the referenced tests/test_finder.py or remove the dangling reference so all listed bundle paths resolve.

Dimension	Reasoning	Score
Conciseness	The body largely assumes Claude's competence and avoids explaining known concepts, but endpoints are listed twice (Data flow and Defaults) and ranking signals are repeated across Key Features and Implementation Details; these minor duplications keep it just below a lean 5.	4 / 5
Actionability	It provides concrete, runnable CLI commands and a Python example backed by a real script (scripts/find_refs.py) plus example JSON output, but the Python snippet imports from "reference_finder" while the actual module lives in scripts/find_refs.py, a minor executable gap that prevents a 5.	4 / 5
Workflow Clarity	The data flow gives a clear five-step sequence but lacks validation/feedback-loop checkpoints for a batch (per-sentence, multi-API-call) operation; per the rubric cap, a batch skill without validation cannot score above 3, so it is not a 4.	3 / 5
Progressive Disclosure	The body is well-organized with clear sections and one-level-deep references to real bundle files (scripts/find_refs.py, references/evaluation-checklist.md), but it references tests/test_finder.py which does not exist in the bundle, a minor organization gap that keeps it from a 5.	4 / 5
	Total	15 / 20 Passed

Description

82%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.

A strong, third-person description that clearly states both capability and trigger conditions with low conflict risk. The main weakness is specificity, which names only two concrete actions rather than a comprehensive set.

Suggestions

Add one or two more concrete actions (e.g., "returns title, DOI, PMID, and year" or "deduplicates across sentences") to lift specificity toward a 5.

Broaden trigger terms with common synonyms a user might actually say (e.g., "citations", "literature search", "find papers") to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	The description names the domain ("PubMed references for each sentence in scientific text") and two concrete actions ("finds" and "ranks") but does not list several specific actions, matching the 1-2 concrete actions anchor; it falls short of the multi-action coverage expected for a 4.	3 / 5
Completeness	It explicitly answers "what" ("Automatically finds and ranks PubMed references for each sentence") and "when" ("use when you need titles, DOIs, and brief recommendation reasons"), with concrete trigger phrases; it clearly meets the both-what-and-when anchor rather than the weaker 4.	5 / 5
Trigger Term Quality	Natural terms like "PubMed references", "titles, DOIs", and "scientific text" are present and would be said by users, giving good keyword coverage; it is not a 5 because it omits common synonyms/variations and leans partly on technical jargon ("PubMed E-utilities API").	4 / 5
Distinctiveness Conflict Risk	The PubMed-reference-per-sentence niche with E-utilities-specific triggers is clearly distinct from other skills and has minimal overlap risk; it does not fit the minor-overlap 4 anchor.	5 / 5
	Total	17 / 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-finder/SKILL.md
Commit: 63c61d3

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