CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

81%

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

SKILL.md
Quality
Evals
Security

Quality

Content

81%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 operational core is excellent: concrete commands, a bounded self-correcting iteration loop, explicit selection criteria, and a precise output contract with a worked example. The main weakness is the ~50 lines of generic "When to Use / Output Contract / Failure Handling / Input Validation" boilerplate that duplicates itself and pads the token budget without adding skill-specific value.

Suggestions

Collapse "When to Use", "When Not to Use", "Required Inputs", "Output Contract", "Failure Handling", "User Checkpoints", "Input Validation", and "Quick Validation" into one short "Guardrails" section — they repeat the same missing-input and confirmation guidance three times and consume ~50 lines.

Delete explanations of concepts Claude already knows, e.g., "Use AND (intersection), OR (union), NOT (exclusion)" and the general truncation explanation; keep only the PubMed-specific conventions (MeSH terms, field tags like [ti]).

Consider moving the detailed citation output-format specification and the Step-3 refinement playbook into a references/ file (e.g., OUTPUT-FORMAT.md) linked one level deep, keeping SKILL.md as a lean overview of the four workflow steps.

DimensionReasoningScore

Conciseness

The core workflow (Steps 1–4, ~110 lines) is efficient and earns its tokens, but there are several padded or unnecessary passages: the "When to Use / When Not to Use / Required Inputs / Output Contract / Failure Handling / User Checkpoints / Input Validation / Quick Validation" sections (~50 lines) are generic template boilerplate that repeats the same "stop and ask for missing inputs" guidance three times, and "Logical operators: Use AND (intersection), OR (union), NOT (exclusion)" explains Boolean basics Claude already knows. This sits at the "mostly efficient but includes some unnecessary explanation" anchor rather than clearly below it, since the operational content itself is tight.

3 / 5

Actionability

Fully executable, copy-paste-ready commands are given for both scenarios (`python scripts/litsense_search.py "natural language query"`, `python scripts/pubmed_search.py "YOUR_BOOLEAN_QUERY"` with the `--max` flag), plus a worked Boolean example, concrete escaping examples with correct/incorrect forms, specific result fields to check (`is_oa: true`, `pmcid`), and an exact output template with a real PMID and link. The referenced scripts exist in the bundle. This matches the anchor for copy-paste-ready commands covering the common cases.

5 / 5

Workflow Clarity

The four-step sequence is clear, and Step 3 is a textbook feedback loop: evaluate results, analyze cause (zero results → misspelling/too specific; irrelevant → ambiguous terms or bad logic), refine (broaden/narrow/switch API), repeat with a hard limit of 5 rounds, then escalate to the user with a report of tried strategies. Selection criteria and PubMed link generation rules act as the final validation checklist. This is not destructive or unbounded batch work, so no workflow-clarity cap applies, and the explicit evaluate→fix→retry loop matches the top anchor.

5 / 5

Progressive Disclosure

Good structure: a single well-sectioned SKILL.md whose script references (`scripts/pubmed_search.py`, `scripts/litsense_search.py`) are real bundle files referenced one level deep with no nested-reference chains. Not a 5 because everything lives inline in one ~155-line file with no separate reference material — the detailed output-format spec and iteration guidance could be split out — and the generic governance sections add inline bulk that belongs either in a reference or nowhere.

4 / 5

Total

17

/

20

Passed

Description

75%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 solid description that names concrete capabilities in the PubMed literature-retrieval domain and includes an explicit applicability clause with natural trigger keywords. It could be sharpened by converting the "Applicable for..." clause into a crisper "Use when..." form with concrete user phrasings and by trimming the "Based on user input" filler.

DimensionReasoningScore

Specificity

Lists several concrete actions — "directly find relevant literature", "construct PubMed Boolean search queries", "retrieve and filter references suitable for citation", "completing reference lists" — covering search, query construction, filtering, and output. Not a 5 because "Based on user input" is filler and the actions, while specific, stop short of the most comprehensive coverage (e.g., presenting formatted citations).

4 / 5

Completeness

The "what" is clear (find literature, construct Boolean queries, retrieve and filter references) and the "when" is explicitly present via "Applicable for quickly finding high-quality evidence on specific topics and completing reference lists" — an equivalent explicit trigger clause, so the score-3 cap for a missing when does not apply. Not a 5 because the when-clause blends applicability with the what rather than giving concrete user-facing trigger phrases (e.g., "Use when the user needs citations or asks for literature on a topic").

4 / 5

Trigger Term Quality

Good natural keywords users would actually say: "literature", "references", "citation", "high-quality evidence", "reference lists", plus the domain term "PubMed". A few common synonyms are missing (e.g., "papers", "bibliography", "cite"), which keeps it below the comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

The PubMed/Boolean-query/citation-reference niche is well defined and mostly distinct — "PubMed Boolean search queries" and "references suitable for citation" are unlikely to fire for an unrelated skill. Minor overlap risk remains with generic literature- or evidence-search skills because "directly find relevant literature" and "high-quality evidence" are broad phrasings, keeping it just below the clear-niche anchor 5.

4 / 5

Total

16

/

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-retrieval-skill/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.