CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Evidence Insight/reference-finder/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

61%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 well structured and actionable, with executable examples verified against the actual script. The main weaknesses are duplicated constraint/ranking content across sections, a missing validation or retry loop for the batch per-sentence API workflow, and a dead reference to tests/test_finder.py.

Suggestions

Merge the 'Key Features' bullets with the 'Implementation Details' sections — ranking signals, allowed host, timeout, endpoints, and top-N are each stated twice; a single consolidated section would cut roughly a quarter of the body.

Add a validation/recovery step for the batch per-sentence API loop (e.g., retry with backoff on timeout, verify retrieved PMID count vs. requested, skip-and-report on failed sentences) so the workflow includes explicit checkpoints.

Remove the dead 'tests/test_finder.py' reference (the file does not exist), fix the example output placeholder "pmid": "PMID:" to a realistic value, and signal when to read references/evaluation-checklist.md (e.g., 'See the evaluation checklist before accepting results').

DimensionReasoningScore

Conciseness

The body is mostly efficient and assumes Claude's competence, but facts are duplicated across sections: ranking signals, the host allowlist, the 30s timeout, the endpoints, and top-N=3 each appear both in "Key Features" and again in "Implementation Details". This is more than anchor 4's "minor instances" but less than anchor 2's padded explanatory fluff, so anchor 3 fits best.

3 / 5

Actionability

The Python example is executable and matches the actual "find_references" function in scripts/find_refs.py, and the CLI commands are copy-paste ready, matching anchor 4. It is not 5 because the example output contains a placeholder value ("pmid": "PMID:") rather than a realistic record, and options such as max_refs/top-N are mentioned but never demonstrated.

4 / 5

Workflow Clarity

The data flow (sentence splitting → ESearch → EFetch → field extraction → ranking) is clearly sequenced with concrete endpoints, but this is a batch operation (one API request pair per sentence, with rate limiting) and no validation or verification steps or retry guidance exist — only a promise of readable error messages. Per the batch-operation rule, workflow clarity is capped at 3; it is above 2 because the sequence itself is well defined.

3 / 5

Progressive Disclosure

Sections are well organized, the body stays at overview size, and references are one level deep (scripts/find_refs.py and references/evaluation-checklist.md both exist), matching anchor 4. It is not 5 because "tests/test_finder.py" is referenced but does not exist in the bundle, and the evaluation checklist is listed under "Related project files" without signaling when Claude should read it.

4 / 5

Total

14

/

20

Passed

Description

78%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 strong: it states concrete capabilities in third person and includes an explicit trigger clause with natural domain terms. The main improvement opportunity is making the "when" clause task-oriented (manuscript drafting, literature grounding) and adding common synonyms like "citations" or "papers".

DimensionReasoningScore

Specificity

"finds and ranks PubMed references for each sentence in scientific text" plus "titles, DOIs, and brief recommendation reasons" names several concrete actions, matching anchor 4. It is not 5 because the description omits output fields and usage modes (PMID/year, API/CLI) that appear only in the body; not 3 because it lists more than 1-2 concrete actions.

4 / 5

Completeness

Both parts are explicit: what ("Automatically finds and ranks PubMed references for each sentence in scientific text") and when ("use when you need titles, DOIs, and brief recommendation reasons from the PubMed E-utilities API"). Not 5 because the when clause is framed around outputs rather than concrete task scenarios (e.g., "when drafting or reviewing a manuscript"); not 3 because the when is explicitly stated, not merely implied.

4 / 5

Trigger Term Quality

Natural phrases like "PubMed references", "scientific text", and "titles, DOIs" give good keyword coverage, matching anchor 4. It falls short of 5 because common synonyms users would say — "citations", "papers", "literature search", "manuscript" — are missing; it is above 3 because multiple natural terms beyond generic language are present.

4 / 5

Distinctiveness Conflict Risk

"PubMed references for each sentence" via "the PubMed E-utilities API" is a clear niche with distinct triggers and minimal conflict risk against generic search or citation skills, matching anchor 5. It does not sit at 4 because the domain (PubMed-only, sentence-level, official API) is specific enough that overlap with related skills is negligible.

5 / 5

Total

17

/

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

aipoch/medical-research-skills

Path

scientific-skills/Evidence Insight/reference-finder/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.