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

73%

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 ./backend/cli/skills/databases/clinicaltrials-database/SKILL.md

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

Highly actionable with concrete executable examples and well-signaled references, but the body is verbose and over-inline for a SKILL.md, with batch workflows lacking explicit validation checkpoints. Trimming inline detail into the existing reference and adding verification steps would lift the weaker dimensions.

Suggestions

Collapse the 10 capability sections into a concise overview table of parameters/use-cases, keeping one or two representative code samples inline and moving the rest into references/api_reference.md to cut redundancy.

Add an explicit validation checkpoint to the bulk/pagination workflow (e.g. verify `len(all_studies) == totalCount`, wrap the loop in try/except with the 429 retry, and log when pagination stops early due to max_pages).

Move the Technical Specifications and Data Structure Navigation sections into the API reference, leaving SKILL.md as a pointer ('For full endpoint specs and response paths, see references/api_reference.md').

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient code with little concept-explanation filler, but ~500 lines with repeated `from scripts.query_clinicaltrials import search_studies` boilerplate across 10 near-identical capability sections could be tightened; not a 3 because the volume competes with context, not a 1 because it assumes Claude's competence.	2 / 3
Actionability	Every capability ships fully executable, copy-paste-ready Python with real parameters and response-parsing examples (e.g. `requests.get(url, params=params)`, `search_studies(condition=..., status=...)`), matching the 'fully executable code/commands' anchor.	3 / 3
Workflow Clarity	The pagination loop has a sequence and a break checkpoint, and the rate-limit example offers a retry feedback loop, but the batch/bulk retrieval path has no inline validation or verification of result completeness; per the guidelines batch operations without validation cap workflow clarity at 2.	2 / 3
Progressive Disclosure	References are clearly signaled and one level deep (both `scripts/query_clinicaltrials.py` and `references/api_reference.md` exist and are named), but large inline blocks (10 full code examples, Data Structure Navigation, Technical Specifications) duplicate the reference file; the 'content that should be separate is inline' anchor fits, so not a 3.	2 / 3
	Total	9 / 12 Passed

Description

82%

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 specific, well-triggered description with concrete actions and a clear niche, but it lacks an explicit 'Use when…' trigger clause, leaving the 'when' only implied. Adding an explicit trigger sentence would raise completeness.

Suggestions

Append an explicit trigger clause, e.g. 'Use when searching or retrieving clinical trial data from ClinicalTrials.gov, or when the user mentions NCT IDs, trial recruitment, or study phases.'

Keep the concrete action list but tighten 'export data, for clinical research and patient matching' into the trigger clause so the 'when' is unambiguous rather than tacked on.

Dimension	Reasoning	Score
Specificity	Multiple concrete actions are listed — 'Query ClinicalTrials.gov via API v2', 'Search trials by condition, drug, location, status, or phase', 'Retrieve trial details by NCT ID, export data' — matching the 'lists multiple specific concrete actions' anchor.	3 / 3
Completeness	The 'what' is clearly stated, but there is no explicit 'Use when…' trigger clause; the trailing 'for clinical research and patient matching' only implies when to use it, so per the guidelines completeness is capped at 2.	2 / 3
Trigger Term Quality	Natural user-facing terms are well covered — 'clinical trials', 'condition', 'drug', 'NCT ID', 'clinical research', 'patient matching' — the kind of vocabulary a user would actually say when needing this skill.	3 / 3
Distinctiveness Conflict Risk	The niche is sharply defined (ClinicalTrials.gov, NCT IDs, trial phases) with distinct triggers unlikely to fire for unrelated skills; not a 2 because it would not meaningfully overlap with generic database skills.	3 / 3
	Total	11 / 12 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (507 lines); consider splitting into references/ and linking	Warning
metadata_version	'metadata.version' is missing	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	13 / 16 Passed

Repository: synthetic-sciences/openscience
Path: backend/cli/skills/databases/clinicaltrials-database/SKILL.md
Commit: 52845c3

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