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

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

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.

A highly actionable, well-structured body with executable examples throughout and a real, clearly-signaled reference bundle. Its main weakness is token efficiency: the ten capability sections duplicate the api_reference.md use cases and repeat rate-limit/error details, so the body could be roughly halved.

Suggestions

Collapse the ten full capability sections into short one-line summaries with a single representative example, and point each to the corresponding section of references/api_reference.md, which already contains these use cases.

State the rate limit, error-handling, and technical specifications once (a single Best Practices section) instead of repeating them in Overview, Quick Start, and Technical Specifications.

Drop the "Common use cases" bullet lists under each capability — they mostly restate the section's purpose and add padding without new information.

Dimension	Reasoning	Score
Conciseness	Most content is concrete API specifics Claude doesn't know (parameters, response paths, status values), but the ten near-identical capability sections (~300 lines) substantially duplicate the use cases already in references/api_reference.md, and rate-limit/error information is repeated across Overview, Best Practices, and Technical Specifications. It fits the 3 anchor ("could be tightened") better than 4 because the duplication goes beyond minor over-explanation.	3 / 5
Actionability	Every capability ships copy-paste-ready executable code with real parameters ("query.cond", "filter.overallStatus", "pageSize"), and the documented helper functions (search_studies, get_study_details, search_with_all_results, extract_study_summary) exist in scripts/query_clinicaltrials.py. Fully executable and covers the common cases, matching the 5 anchor.	5 / 5
Workflow Clarity	Each capability is presented as a clear sequenced workflow (search → filter → extract), and bulk retrieval includes a 429 retry feedback loop and a max_pages guard, which serves as validation for the batch operation. It stays at 4 rather than 5 because explicit validation checkpoints (e.g., verifying response shape or totalCount before paginating) are not consistently called out.	4 / 5
Progressive Disclosure	Structure is good: overview → when-to-use → quick start → capabilities → resources → best practices, with clearly signaled one-level-deep references ("Load this reference when working with unfamiliar API features") pointing to real files (references/api_reference.md, scripts/query_clinicaltrials.py). Not 5 because a significant amount of capability detail inlined in the body duplicates what the reference file already covers.	4 / 5
	Total	16 / 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 specific, third-person description with strong trigger keywords and a clear niche, but it lacks an explicit "Use when…" clause, leaving the invocation condition only weakly implied. Adding a trigger sentence would make it fully complete.

Suggestions

Append an explicit trigger clause, e.g. "Use when the user asks about clinical trials, trial eligibility, NCT IDs, or recruiting studies for a condition or drug."

Include common user synonyms such as "clinical trials", "clinical studies", or "trial search" alongside the parameter-based keywords to broaden natural trigger matching.

Replace the generic "export data" with concrete formats, e.g. "export trial data to CSV".

Dimension	Reasoning	Score
Specificity	The description lists multiple specific concrete actions — "Search trials by condition, drug, location, status, or phase", "Retrieve trial details by NCT ID, export data" — in third-person voice, giving comprehensive coverage of the skill's capabilities. It matches the 5 anchor rather than 4 because there are no meaningful coverage gaps beyond the slightly generic "export data".	5 / 5
Completeness	The "what" is clear and specific, but there is no explicit "Use when…" clause; "for clinical research and patient matching" only weakly implies when to invoke the skill. Per the judging guidelines, a missing explicit trigger clause caps completeness at 3.	3 / 5
Trigger Term Quality	Terms like "condition, drug, location, status, or phase", "NCT ID", "patient matching", and "clinical research" are natural phrases users would say, giving good keyword coverage. It falls short of the 5 anchor because common variations such as "clinical trials"/"clinical study" as standalone trigger phrases are absent.	4 / 5
Distinctiveness Conflict Risk	"ClinicalTrials.gov via API v2" and "NCT ID" establish a clear niche with distinct triggers, making conflict with other skills minimal. Not 4: the domain-specific terms leave virtually no overlap risk with generic database or search skills.	5 / 5
	Total	17 / 20 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 (513 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: 4082a2e

Reviewed: 1 day 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.