clinical-trials-search
Search ClinicalTrials.gov with natural language queries. Find clinical trials, enrollment, and outcomes using Valyu semantic search.
Best use case
clinical-trials-search is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Search ClinicalTrials.gov with natural language queries. Find clinical trials, enrollment, and outcomes using Valyu semantic search.
Teams using clinical-trials-search should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/clinical-trials-search/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How clinical-trials-search Compares
| Feature / Agent | clinical-trials-search | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Search ClinicalTrials.gov with natural language queries. Find clinical trials, enrollment, and outcomes using Valyu semantic search.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Clinical Trials Search
Search the complete ClinicalTrials.gov database of clinical studies using natural language queries powered by Valyu's semantic search API.
## Why This Skill is Powerful
- **No API Parameter Parsing**: Just pass natural language queries directly - no need to construct complex search parameters
- **Semantic Search**: Understands the meaning of your query, not just keyword matching
- **Full-Text Access**: Returns complete trial information including phases, conditions, interventions, and outcomes
- **Image Links**: Includes data visualizations when available
- **Comprehensive Coverage**: Access to all ClinicalTrials.gov data
## Requirements
1. Node.js 18+ (uses built-in fetch)
2. Valyu API key from https://platform.valyu.ai ($10 free credits)
## CRITICAL: Script Path Resolution
The `scripts/search` commands in this documentation are relative to this skill's installation directory.
Before running any command, locate the script using:
```bash
CLINICAL_TRIALS_SCRIPT=$(find ~/.claude/plugins/cache -name "search" -path "*/clinical-trials-search/*/scripts/*" -type f 2>/dev/null | head -1)
```
Then use the full path for all commands:
```bash
$CLINICAL_TRIALS_SCRIPT "CAR-T cell therapy trials" 15
```
## API Key Setup Flow
When you run a search and receive `"setup_required": true`, follow this flow:
1. **Ask the user for their API key:**
"To search ClinicalTrials.gov, I need your Valyu API key. Get one free ($10 credits) at https://platform.valyu.ai"
2. **Once the user provides the key, run:**
```bash
scripts/search setup <api-key>
```
3. **Retry the original search.**
## When to Use This Skill
- Finding ongoing and completed clinical trials
- Identifying trial eligibility criteria
- Recruiting status and enrollment information
- Comparing treatment approaches in trials
- Patient recruitment and enrollment research
- Outcomes and safety data from trials
## Output Format
```json
{
"success": true,
"type": "clinical_trials_search",
"query": "CAR-T cell therapy trials",
"result_count": 10,
"results": [
{
"title": "Trial Title",
"url": "https://clinicaltrials.gov/...",
"content": "Trial details, phase, conditions, outcomes...",
"source": "clinical-trials",
"relevance_score": 0.95,
"images": []
}
],
"cost": 0.025
}
```
## Processing Results
### With jq
```bash
# Get trial titles
scripts/search "query" 10 | jq -r '.results[].title'
# Get URLs
scripts/search "query" 10 | jq -r '.results[].url'
# Extract full content
scripts/search "query" 10 | jq -r '.results[].content'
```
## Common Use Cases
### Drug Development
```bash
# Find drug trials
scripts/search "phase 2 trials for Alzheimer's disease" 50
```
### Treatment Research
```bash
# Search for treatment studies
scripts/search "checkpoint inhibitor combinations in lung cancer" 20
```
### Medical Device Studies
```bash
# Find device trials
scripts/search "continuous glucose monitoring device studies" 15
```
### Intervention Analysis
```bash
# Search for intervention studies
scripts/search "behavioral interventions for obesity" 25
```
## Error Handling
All commands return JSON with `success` field:
```json
{
"success": false,
"error": "Error message"
}
```
Exit codes:
- `0` - Success
- `1` - Error (check JSON for details)
## API Endpoint
- Base URL: `https://api.valyu.ai/v1`
- Endpoint: `/search`
- Authentication: X-API-Key header
## Architecture
```
scripts/
├── search # Bash wrapper
└── search.mjs # Node.js CLI
```
Direct API calls using Node.js built-in `fetch()`, zero external dependencies.
## Adding to Your Project
If you're building an AI project and want to integrate Clinical Trials Search directly into your application, use the Valyu SDK:
### Python Integration
```python
from valyu import Valyu
client = Valyu(api_key="your-api-key")
response = client.search(
query="your search query here",
included_sources=["valyu/valyu-clinical-trials"],
max_results=20
)
for result in response["results"]:
print(f"Title: {result['title']}")
print(f"URL: {result['url']}")
print(f"Content: {result['content'][:500]}...")
```
### TypeScript Integration
```typescript
import { Valyu } from "valyu-js";
const client = new Valyu("your-api-key");
const response = await client.search({
query: "your search query here",
includedSources: ["valyu/valyu-clinical-trials"],
maxResults: 20
});
response.results.forEach((result) => {
console.log(`Title: ${result.title}`);
console.log(`URL: ${result.url}`);
console.log(`Content: ${result.content.substring(0, 500)}...`);
});
```
See the [Valyu docs](https://docs.valyu.ai) for full integration examples and SDK reference.Related Skills
wikipedia-search
Search and fetch structured content from Wikipedia using the MediaWiki API for reliable, encyclopedic information
tooluniverse-target-research
Gather comprehensive biological target intelligence from 9 parallel research paths covering protein info, structure, interactions, pathways, expression, variants, drug interactions, and literature. Features collision-aware searches, evidence grading (T1-T4), explicit Open Targets coverage, and mandatory completeness auditing. Use when users ask about drug targets, proteins, genes, or need target validation, druggability assessment, or comprehensive target profiling.
tooluniverse-literature-deep-research
Conduct comprehensive literature research with target disambiguation, evidence grading, and structured theme extraction. Creates a detailed report with mandatory completeness checklist, biological model synthesis, and testable hypotheses. For biological targets, resolves official IDs (Ensembl/UniProt), synonyms, naming collisions, and gathers expression/pathway context before literature search. Default deliverable is a report file; for single factoid questions, uses a fast verification mode and may include an inline answer. Use when users need thorough literature reviews, target profiles, or to verify specific claims from the literature.
tooluniverse-drug-research
Generates comprehensive drug research reports with compound disambiguation, evidence grading, and mandatory completeness sections. Covers identity, chemistry, pharmacology, targets, clinical trials, safety, pharmacogenomics, and ADMET properties. Use when users ask about drugs, medications, therapeutics, or need drug profiling, safety assessment, or clinical development research.
tooluniverse-disease-research
Generate comprehensive disease research reports using 100+ ToolUniverse tools. Creates a detailed markdown report file and progressively updates it with findings from 10 research dimensions. All information includes source references. Use when users ask about diseases, syndromes, or need systematic disease analysis.
tooluniverse-clinical-trial-matching
AI-driven patient-to-trial matching for precision medicine and oncology. Given a patient profile (disease, molecular alterations, stage, prior treatments), discovers and ranks clinical trials from ClinicalTrials.gov using multi-dimensional matching across molecular eligibility, clinical criteria, drug-biomarker alignment, evidence strength, and geographic feasibility. Produces a quantitative Trial Match Score (0-100) per trial with tiered recommendations and a comprehensive markdown report. Use when oncologists, molecular tumor boards, or patients ask about clinical trial options for specific cancer types, biomarker profiles, or post-progression scenarios.
tooluniverse-clinical-trial-design
Strategic clinical trial design feasibility assessment using ToolUniverse. Evaluates patient population sizing, biomarker prevalence, endpoint selection, comparator analysis, safety monitoring, and regulatory pathways. Creates comprehensive feasibility reports with evidence grading, enrollment projections, and trial design recommendations. Use when planning Phase 1/2 trials, assessing trial feasibility, or designing biomarker-driven studies.
tooluniverse-clinical-guidelines
Search and retrieve clinical practice guidelines across 12+ authoritative sources including NICE, WHO, ADA, AHA/ACC, NCCN, SIGN, CPIC, CMA, CTFPHC, GIN, MAGICapp, PubMed, EuropePMC, TRIP, and OpenAlex. Covers disease management, cardiology, oncology, diabetes, pharmacogenomics, and more. Use when users ask about clinical guidelines, treatment recommendations, standard of care, evidence-based medicine, or drug-gene dosing recommendations.
research-lookup
Look up current research information using Perplexity's Sonar Pro Search or Sonar Reasoning Pro models through OpenRouter. Automatically selects the best model based on query complexity. Search academic papers, recent studies, technical documentation, and general research information with citations.
research-grants
Write competitive research proposals for NSF, NIH, DOE, and DARPA. Agency-specific formatting, review criteria, budget preparation, broader impacts, significance statements, innovation narratives, and compliance with submission requirements.
pubmed-search
Search PubMed for scientific literature. Use when the user asks to find papers, search literature, look up research, find publications, or asks about recent studies. Triggers on "pubmed", "papers", "literature", "publications", "research on", "studies about".
perplexity-search
Perform AI-powered web searches with real-time information using Perplexity models via LiteLLM and OpenRouter. This skill should be used when conducting web searches for current information, finding recent scientific literature, getting grounded answers with source citations, or accessing information beyond the model's knowledge cutoff. Provides access to multiple Perplexity models including Sonar Pro, Sonar Pro Search (advanced agentic search), and Sonar Reasoning Pro through a single OpenRouter API key.