CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

medical-vector-search

Vector database retrieval and evidence-based answering for medical research topics. Use when users need knowledge-base-backed answers about methodology, disease mechanisms, drug effects, clinical research, or research tools. Input is a medical research question; output is a st...

Quality

77%

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/medical-vector-search/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

75%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 of this skill is excellent — concrete, verified commands and script references, clear query-rewriting examples, precise citation formatting, and a sensible retry loop for poor results. The main weakness is the ~50 lines of generic, non-specific boilerplate sections (When to Use through Quick Validation) that pad token cost without adding skill-specific guidance.

Suggestions

Cut or drastically compress the generic boilerplate sections ("When to Use", "When Not to Use", "Required Inputs", "Output Contract", "Failure Handling", "User Checkpoints", "Input Validation", "Quick Validation") — they are template text not tailored to this skill and consume roughly a third of the body.

Integrate script/API failure handling directly into Step 2 of the workflow (e.g., what to do if the request errors or returns zero items) rather than leaving it in the generic Failure Handling section, to close the workflow-validation gap.

Merge the duplicated guidance between "Important Notes" and the boilerplate sections (e.g., the missing-input rule appears in both Required Inputs and Input Validation) into one place.

DimensionReasoningScore

Conciseness

The core workflow (Steps 1-3, Important Notes) is tight and skill-specific, but the back half of the body — "When to Use", "When Not to Use", "Required Inputs", "Output Contract", "Failure Handling", "User Checkpoints", "Input Validation", "Quick Validation" — is ~50 lines of generic boilerplate with near-zero skill-specific information (e.g., "Use this skill when the user explicitly needs to perform the core task of medical-vector-search" is circular). This lands on anchor 3 (mostly efficient with unnecessary sections that could be trimmed) rather than 2, since no space is spent explaining concepts Claude already knows.

3 / 5

Actionability

Guidance is fully executable: a copy-paste bash command (`python scripts/search.py "<rewritten query>"`), an importable `search()` function (verified present in scripts/search.py), a four-row rewriting example table, fixed API parameters, the exact JSON path for citation URLs (`child_chunks[0].properties.metadata.helix_wiki_node_url`), and a concrete Markdown reference format. Common cases — good results, low-relevance results, and unsatisfactory first searches — are all covered, matching anchor 5.

5 / 5

Workflow Clarity

The three-step sequence (rewrite query → call search → parse and answer with citations) is clear, with a relevance-score checkpoint ("score > 0.3" prioritized) and an explicit retry feedback loop ("If first search results are unsatisfactory, try changing the query angle — e.g., switch to English terminology or split into multiple sub-queries"). It falls short of anchor 5 because there is no validation of the script call itself within the steps (script failure handling lives only in the generic Failure Handling section, not the workflow), and no error-recovery guidance for a failed or empty API response beyond the query-retry hint.

4 / 5

Progressive Disclosure

The body is well-sectioned and its single bundle dependency is correctly signaled: `scripts/search.py` exists and is referenced with exact invocation and import paths (verified against the actual bundle). At ~140 lines with everything inline, no content clearly demands its own file, and structure is good with only minor gaps — the generic boilerplate sections dilute navigation and the API parameter table could arguably live elsewhere — so anchor 4 fits better than 5.

4 / 5

Total

16

/

20

Passed

Description

70%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 has an explicit and well-targeted "Use when" clause with natural medical-research trigger terms, and a clear statement of what the skill does. Its main defects are the mid-sentence truncation ("output is a st...") and the thin enumeration of concrete capabilities, which read as two actions rather than a comprehensive list.

Suggestions

Rewrite the description to fix the truncation — the cut-off "Input is a medical research question; output is a st..." must be completed or removed, since frontmatter descriptions should be self-contained.

Enumerate the concrete actions (e.g., "rewrites user questions into professional search queries, searches a bundled vector knowledge base, and formats answers with citation-linked references") to raise specificity from naming 1-2 actions to several.

Add natural trigger variations users would actually say — "clinical trials", "medical literature", "treatment guidelines", "evidence" — alongside the existing topic list.

DimensionReasoningScore

Specificity

"Vector database retrieval and evidence-based answering" names the domain with two concrete actions, but coverage is not comprehensive — query rewriting, citation formatting, and the input/output contract are absent (and the output description is cut off mid-sentence at "output is a st..."). This matches anchor 3 ("Names domain and 1-2 concrete actions, but not comprehensive") better than anchor 4, which requires several listed actions.

3 / 5

Completeness

Both "what" ("Vector database retrieval and evidence-based answering for medical research topics") and "when" ("Use when users need knowledge-base-backed answers about...") are explicitly present with concrete trigger topics. It is not a 5 because the description is literally truncated mid-sentence ("Input is a medical research question; output is a st..."), leaving the output description incomplete, and the trigger phrasing is topic-list style rather than the fully concrete "when the user mentions X" pattern.

4 / 5

Trigger Term Quality

The "Use when" clause lists natural trigger terms users would plausibly say — "methodology, disease mechanisms, drug effects, clinical research, or research tools" — giving good keyword coverage. It falls short of anchor 5 because common variations like "clinical trials", "medical literature", "treatment guidelines", or "evidence-based medicine" are missing, and "knowledge-base-backed answers" is system jargon rather than user phrasing.

4 / 5

Distinctiveness Conflict Risk

The medical-research domain restriction ("disease mechanisms, drug effects, clinical research") gives it a clear niche distinct from generic search or document skills, matching anchor 4. It is not a 5 because "clinical research" and "research tools" are broad enough to overlap with general literature-search or web-search skills, and nothing signals it is specifically about a bundled knowledge base rather than external retrieval.

4 / 5

Total

15

/

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/medical-vector-search/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.