CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

clinicaltrials-database

Query ClinicalTrials.gov via API v2. Search trials by condition, drug, location, status, or phase. Retrieve trial details by NCT ID, export data, for clinical research and patient matching.

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/clinicaltrials-database/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

67%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, highly actionable API skill whose code examples are executable and match the bundled script exactly. Its main weaknesses are length and repetition — duplicated technical specs, generic Python error-handling tutorials, and a Quick Start path that doesn't match the real bundle layout.

Suggestions

Consolidate the rate limit, max page size, and base URL facts into Technical Specifications only, and trim the generic try/except and '.get()' tutorials in Best Practices to one-line pointers — Claude already knows this Python.

Fix the Quick Start path inconsistency: 'cd scientific-databases/clinicaltrials-database/scripts' should be 'cd scripts' relative to the skill root, matching 'python3 scripts/query_clinicaltrials.py' used later.

Move several of the ten capability walkthroughs (e.g., sponsor search, combined query strategies) into references/api_reference.md, keeping SKILL.md as a lean overview with the strongest 3-4 patterns.

DimensionReasoningScore

Conciseness

Mostly efficient, API-specific content, but with notable slack: the ~50 req/min rate limit is stated three times (Overview, Best Practices, Technical Specifications), max page size 1000 and base URL are each repeated, and the Best Practices section teaches generic Python Claude already knows (boilerplate try/except requests error handling, '.get()' safe navigation). Not a 2 because the bulk is genuinely novel, domain-specific API guidance rather than padded concept explanation. Not a 4 because the duplication and generic tutorials are more than minor instances.

3 / 5

Actionability

Code examples are concrete and executable: real API parameters ('query.cond', 'filter.overallStatus'), real response paths, and helper functions that all exist in scripts/query_clinicaltrials.py (verified: search_studies, get_study_details, search_with_all_results, extract_study_summary, with matching signatures including format='csv'). Not a 5 because of the Quick Start path bug — 'cd scientific-databases/clinicaltrials-database/scripts' does not match the actual bundle layout (script lives at scripts/query_clinicaltrials.py, invoked as 'python3 scripts/query_clinicaltrials.py' elsewhere in the same file), and the 'from scripts.query_clinicaltrials import ...' examples silently assume running from the skill root.

4 / 5

Workflow Clarity

Clear task-oriented sequencing: Quick Start → capability-specific patterns → pagination/bulk handling → export, with validation guidance present (rate-limit 429 backoff retry loop, raise_for_status error handling, pageToken break condition, missing-data checks). Not a 5 because checkpoints are advisory rather than woven into the workflows themselves — e.g., no step verifying retrieved count against totalCount or confirming response status before parsing in the main examples. Not a 3 because the sequences are coherent and error-recovery guidance is explicitly provided.

4 / 5

Progressive Disclosure

Bundle structure is solid: both referenced files exist (references/api_reference.md, scripts/query_clinicaltrials.py), references are one level deep, and the Resources section clearly signals what each contains and when to load it ('Load this reference when working with unfamiliar API features or troubleshooting issues'). Not a 5 because the SKILL.md itself runs ~500 lines with ten full capability walkthroughs and Best Practices detail that partly duplicate the reference file and could be split out, leaving the main file less of a lean overview than the anchor describes.

4 / 5

Total

15

/

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 strong, concrete description with excellent specificity and distinctiveness, held back by the absence of an explicit 'Use when...' trigger clause — the 'when' is only weakly conveyed by the purpose phrase 'for clinical research and patient matching'. Keyword coverage is good but misses a few natural synonyms.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks about clinical trials, mentions an NCT ID/number, or needs trial data for research or patient matching.'

Include common synonyms users would say — 'study/studies', 'clinical trial registry', 'trial status', 'recruiting trials' — to strengthen trigger matching.

State the output format expectation briefly (e.g., 'returns structured JSON study records') to sharpen the 'what' for downstream consumers.

DimensionReasoningScore

Specificity

The description lists multiple concrete, specific actions: "Query ClinicalTrials.gov via API v2", "Search trials by condition, drug, location, status, or phase", "Retrieve trial details by NCT ID", "export data". This matches the anchor 'Lists multiple specific concrete actions; comprehensive coverage' for the domain — nothing is vague or abstract. Not a 4 because there are no minor gaps: search criteria, single-record retrieval, and export are all covered.

5 / 5

Completeness

The 'what' is clearly and concretely answered (search, retrieve, export), but the 'when' is only weakly implied by the purpose phrase "for clinical research and patient matching" — there is no explicit 'Use when...' trigger clause (e.g., 'Use when the user asks about clinical trials or mentions an NCT number'). Per the guideline that a missing 'Use when...' clause or equivalent explicit trigger guidance caps completeness at 3, this sits at anchor 3 rather than 4.

3 / 5

Trigger Term Quality

Good natural keyword coverage: "clinical trials", "trials", "condition", "drug", "NCT ID", "patient matching", "clinical research" — phrases users would naturally say. Not a 5 because common synonyms like "study/studies", "clinical trial registry", or "trial results" are missing; not a 3 because coverage goes well beyond a bare domain mention and includes scenario terms like patient matching.

4 / 5

Distinctiveness Conflict Risk

The description occupies a clear niche anchored by unambiguous triggers: "ClinicalTrials.gov", "API v2", "NCT ID", "patient matching" — a user asking about these would almost certainly intend this skill. Minimal conflict risk with generic database or research skills. Not a 4 because there is no meaningful overlap with a closely related skill named in the description.

5 / 5

Total

17

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (521 lines); consider splitting into references/ and linking

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

aipoch/medical-research-skills

Path

scientific-skills/Evidence Insight/clinicaltrials-database/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.