clinical-trial-protocol-skill

Clinical Trial Protocol Skill

⚠️ EXECUTION CONTROL - READ THIS FIRST

CRITICAL: This orchestrator follows a SIMPLE START approach:

1. Display the welcome message FIRST (shown in "Startup: Welcome and Confirmation" section below)
2. Ask user to confirm they're ready to proceed - Wait for confirmation (yes/no)
3. Jump directly into Full Workflow Logic - Automatically run subskills sequentially
4. Do NOT pre-read subskill files - Subskills are loaded on-demand only when their step executes

Why this matters:

• Pre-reading all subskills wastes context and memory
• Subskills should only load when actually needed during execution
• Workflow automatically handles resuming from existing waypoints

Overview

This skill generates clinical trial protocols for medical devices or drugs using a modular, waypoint-based architecture

What This Skill Does

Starting with an intervention idea (device or drug), this orchestrated workflow offers two modes:

🔬 Research Only Mode (Steps 0-1): 0. Initialize Intervention - Collect device or drug information

1. Research Similar Protocols - Find similar trials, FDA guidance, and published protocols
   • Deliverable: Comprehensive research summary as formatted .md artifact

📄 Full Protocol Mode (Steps 0-5): 0. Initialize Intervention - Collect device or drug information

1. Research Similar Protocols - Find similar trials, FDA guidance, and published protocols
2. Protocol Foundation - Generate protocol sections 1-6 (foundation, design, population)
3. Protocol Intervention - Generate protocol sections 7-8 (intervention details)
4. Protocol Operations - Generate protocol sections 9-12 (assessments, statistics, operations)
5. Generate Protocol - Create professional file ready for stakeholder review

Architecture

Waypoint-Based Design

All analysis data is stored in waypoints/ directory as JSON/markdown files:

waypoints/
├── intervention_metadata.json           # Intervention info, status, initial context
├── 01_clinical_research_summary.json   # Similar trials, FDA guidance, recommendations
├── 02_protocol_foundation.md            # Protocol sections 1-6 (Step 2)
├── 03_protocol_intervention.md          # Protocol sections 7-8 (Step 3)
├── 04_protocol_operations.md            # Protocol sections 9-12 (Step 4)
├── 02_protocol_draft.md                 # Complete protocol (concatenated in Step 4)
├── 02_protocol_metadata.json            # Protocol metadata
└── 02_sample_size_calculation.json      # Statistical sample size calculation

Rich Initial Context Support: Users can provide substantial documentation, technical specifications, or research data when initializing the intervention (Step 0). This is preserved in intervention_metadata.json under the initial_context field. Later steps reference this context for more informed protocol development.

Modular Subskill Steps

Each step is an independent skill in references/ directory:

references/
├── 00-initialize-intervention.md    # Collect device or drug information
├── 01-research-protocols.md         # Clinical trials research and FDA guidance
├── 02-protocol-foundation.md        # Protocol sections 1-6 (foundation, design, population)
├── 03-protocol-intervention.md      # Protocol sections 7-8 (intervention details)
├── 04-protocol-operations.md        # Protocol sections 9-12 (assessments, statistics, operations)
└── 05-generate-document.md          # NIH Protocol generation

Utility Scripts

scripts/
└── sample_size_calculator.py   # Statistical power analysis (validated)

Prerequisites

1. clinical trials MCP Server (Required)

Installation:

• Install via drag-and-drop .mcpb file into Claude Desktop
• Or configure manually in Claude Desktop settings

Available Tools: search_clinical_trials - Search by:

condition - Disease or condition (e.g., "pancreatic cancer") intervention - Drug, device, or treatment (e.g., "pembrolizumab", "CAR-T") sponsor - Sponsor or collaborator name (e.g., "Pfizer", "NIH") location - City, state, or country (e.g., "California", "Boston") status - "recruiting" (default), "active", "completed", "all" phase - Trial phase: "1", "2", "3", "4", "early_phase1" max_results - Default 25, max 100

get_trial_details - Get comprehensive details for a specific trial using its nct_id (e.g., "NCT04267848"). Returns eligibility criteria, outcomes, study design, and contact information.

Verification: Step 1 will automatically test MCP connectivity at startup.

2. FDA Database Access (Built-in)

Purpose: FDA regulatory pathway research via explicit database URLs

Sources:

• Step 1: FDA device/drug databases (510(k), PMA, De Novo, Drugs@FDA, Orange Book, Purple Book)
• All sources use direct FDA database URLs - no generic web searches

3. Clinical Protocol Template

Template Files: Any .md files in the assets/ directory

Purpose: Reference template for protocol structure and content guidance. The system automatically detects available templates and uses them dynamically.

4. Python Dependencies (Required for Step 2)

Installation:

pip install -r requirements.txt

Dependencies:

• scipy >= 1.11.0 (statistical calculations)
• numpy >= 1.24.0 (numerical operations)

Purpose: Accurate statistical sample size calculations for clinical protocols

How to Use

Simply invoke the skill and select your desired mode:

🔬 Research Only Mode:

1. Select "Research Only" from the main menu
2. Provide intervention information
3. Receive comprehensive research summary as formatted .md artifact
4. Option to continue with full protocol generation or exit

📄 Full Protocol Mode:

1. Select "Full Protocol" from the main menu
2. Guide you through all steps sequentially (Steps 0-5)
3. Pause after Step 4 to review the draft protocol
4. Generate the final protocol document when ready

Resume Capability: If interrupted, simply restart the skill and it will automatically resume from your last completed step.

Execution Flow

Startup: Welcome and Mode Selection

When skill is invoked, display the following message:

🧬 CLINICAL TRIAL PROTOCOL

Welcome! This skill generates clinical trial protocols for medical devices or drugs.

[If waypoints/intervention_metadata.json exists:]
✓ Found existing protocol in progress: [Intervention Name]
  Type: [Device/Drug]
  Completed: [List of completed steps]
  Next: [Next step to execute]

📋 SELECT MODE:

1. 🔬 Research Only - Run clinical research analysis (Steps 0-1)
   • Collect intervention information
   • Research similar clinical trials
   • Find FDA guidance and regulatory pathways
   • Generate comprehensive research summary as .md artifact

2. 📄 Full Protocol - Generate complete clinical trial protocol (Steps 0-5)
   • Everything in Research Only, plus:
   • Generate all protocol sections
   • Create professional protocol document

3. ❌ Exit

Please select an option (1, 2, or 3):

🛑 STOP and WAIT for user selection (1, 2, or 3)

• If 1 (Research Only): Set execution_mode = "research_only" and proceed to Research Only Workflow Logic
• If 2 (Full Protocol): Set execution_mode = "full_protocol" and proceed to Full Workflow Logic
• If 3 (Exit): Exit gracefully with "No problem! Restart the skill anytime to continue."

---

Research Only Workflow Logic

This workflow executes only Steps 0 and 1, then generates a formatted research summary artifact.

Step 1: Check for Existing Waypoints

• If waypoints/intervention_metadata.json exists: Load metadata, check if steps 0 and 1 are already complete
• If no metadata exists: Start from Step 0

Step 2: Execute Research Steps (0 and 1)

For each step (0, 1):

1. Check completion status: If step already completed in metadata, skip with "✓ Step [X] already complete"

2. Execute step:

   • Display "▶ Executing Step [X]..."
   • Read and follow the corresponding subskill file instructions
   • Wait for completion
   • Display "✓ Step [X] complete"
   • Step execution method (ON-DEMAND LOADING): When a step is ready to execute (NOT before), read the subskill markdown file and execute ALL instructions within it
   • Step-to-file mapping:
     • Step 0: references/00-initialize-intervention.md (collect intervention info)
     • Step 1: references/01-research-protocols.md (clinical research and FDA guidance)

3. Handle errors: If step fails, ask user to retry or exit. Save current state for resume capability.

Step 3: Generate Research Summary Artifact

After Step 1 completes successfully:

1. Read waypoint files:

   • waypoints/intervention_metadata.json (intervention details)
   • waypoints/01_clinical_research_summary.json (research findings)

2. Create formatted markdown summary: Generate a comprehensive, well-formatted research summary as a markdown artifact with the following structure:

# Clinical Research Summary: [Intervention Name]

## Intervention Overview
- **Type:** [Device/Drug]
- **Indication:** [Target condition/disease]
- **Description:** [Brief intervention description]
- **Mechanism of Action:** [How it works]

## Similar Clinical Trials
[List top 5-10 similar trials with NCT ID, title, phase, status, key findings]

## FDA Regulatory Pathway
- **Recommended Pathway:** [510(k), PMA, De Novo, IND, NDA, BLA, etc.]
- **Regulatory Basis:** [Rationale for pathway selection]
- **Key Requirements:** [Major regulatory considerations]

## FDA Guidance Documents
[List relevant FDA guidance documents with links and key excerpts]

## Study Design Recommendations
- **Suggested Study Type:** [RCT, single-arm, etc.]
- **Phase Recommendation:** [Phase 1, 2, 3, etc.]
- **Primary Endpoint Suggestions:** [Based on similar trials]
- **Sample Size Considerations:** [Preliminary thoughts]

## Key Insights and Recommendations
[Synthesized recommendations for protocol development]

## Next Steps
[If user wants to proceed with full protocol development]

---
*Generated by Clinical Trial Protocol Skill*
*Date: [Current date]*

3. Save artifact: Write the formatted summary to waypoints/research_summary.md

4. Display completion message:

✅ RESEARCH COMPLETE

Research Summary Generated: waypoints/research_summary.md

📊 Key Findings:
  • Similar Trials Found: [X trials]
  • Recommended Pathway: [Pathway name]
  • FDA Guidance Documents: [X documents identified]
  • Study Design: [Recommended design]

📄 The research summary has been saved as a formatted markdown artifact.

Would you like to:
1. Continue with full protocol generation (steps 2-5)
2. Exit and review research summary

Option 1 Logic (Continue to Full Protocol):

• Set execution_mode = "full_protocol"
• Continue to Full Workflow Logic starting from Step 2 (since 0 and 1 are complete)

Option 2 Logic (Exit):

• Display: "✓ Research summary saved. Restart the skill anytime to continue with protocol generation."
• Exit orchestrator gracefully

---

Full Workflow Logic

Step 1: Check for Existing Waypoints

• If waypoints/intervention_metadata.json exists: Load metadata, check completed_steps array, resume from next incomplete step
• If no metadata exists: Start from Step 0

Step 2: Execute Steps in Order

For each step (0, 1, 2, 3, 4, 5):

1. Check completion status: If step already completed in metadata, skip with "✓ Step [X] already complete"

2. Execute step: Display "▶ Executing Step [X]...", read and follow the corresponding subskill file instructions, wait for completion, display "✓ Step [X] complete"

   • Step execution method (ON-DEMAND LOADING): When a step is ready to execute (NOT before), read the subskill markdown file and execute ALL instructions within it
   • IMPORTANT: Do NOT read subskill files in advance. Only read them at the moment of execution.
   • Step-to-file mapping:
     • Step 0: references/00-initialize-intervention.md (read when Step 0 executes)
     • Step 1: references/01-research-protocols.md (read when Step 1 executes)
     • Step 2: references/02-protocol-foundation.md (read when Step 2 executes - sections 1-6)
     • Step 3: references/03-protocol-intervention.md (read when Step 3 executes - sections 7-8)
     • Step 4: references/04-protocol-operations.md (read when Step 4 executes - sections 9-12)
     • Step 5: references/05-concatenate-protocol.md (read when Step 5 executes - final concatenation)

3. Handle errors: If step fails, ask user to retry or exit. Save current state for resume capability.

4. Display progress: "Progress: [X/6] steps complete", show estimated remaining time

5. Step 4 Completion Pause: After Step 4 completes, pause and display the Protocol Completion Menu (see below). Wait for user selection before proceeding.

Step 2.5: Protocol Completion Menu

After Step 4 completes successfully, display the EXACT menu below (do not improvise or create alternative options):

✅ PROTOCOL COMPLETE: Protocol Draft Generated

Protocol Details:
  • Study Design: [Design from metadata]
  • Sample Size: [N subjects from metadata]
  • Primary Endpoint: [Endpoint from metadata]
  • Study Duration: [Duration from metadata]

Protocol file: waypoints/02_protocol_draft.md
File size: [Size in KB]

📋 WHAT WOULD YOU LIKE TO DO NEXT?

1. 📄 Review Protocol in Artifact - click on the .md file above

2. 📄 Concatenate Final Protocol (Step 5)

3. ⏸️  Exit and Review Later

Option 1 Logic (Review in Artifact): Pause, let user open the section files, wait for further instruction

Option 2 Logic (Concatenate Protocol):

1. Execute Step 5 by reading and following references/05-concatenate-protocol.md
2. Step 5 will concatenate all section files into final protocol document
3. Continue to Step 3 (Final Summary) after Step 5 completes

Option 3 Logic (Exit):

1. Display: "✓ Protocol sections saved. You can resume with Step 5 anytime to concatenate."
2. Exit orchestrator gracefully

Step 3: Final Summary

Display completion message with:

• Intervention name, type (device/drug), indication
• Protocol details (design, sample size, endpoints, duration)
• All completed steps list
• Final deliverable: Complete protocol markdown file location (waypoints/protocol_complete.md)
• Waypoint files list for reference
• Important disclaimers (FDA Pre-Sub, biostatistician review, IRB approval required)
• Thank you message

Technical Details

Waypoint File Formats

JSON Waypoints (Steps 0, 1):

• Structured data for programmatic access
• Small file sizes (1-15KB)
• Easy to parse and reference

Markdown Waypoints (Steps 2, 3, 4):

• Step 2: 02_protocol_foundation.md (Sections 1-6)
• Step 3: 03_protocol_intervention.md (Sections 7-8)
• Step 4: 04_protocol_operations.md (Sections 9-12)
• Step 4: 02_protocol_draft.md (concatenated complete protocol)
• Human-readable protocol documents
• Can be directly edited by users
• Individual section files preserved for easier regeneration

Data Minimization Strategy

Each step implements aggressive summarization:

• Keep: Top-N results (5-10 max)
• Keep: Key facts and IDs (NCT numbers, endpoint types)
• Keep: Concise rationale (2-3 sentences)
• Discard: Raw MCP query results (not needed after analysis)
• Discard: Full FDA guidance text (only excerpts/citations kept)
• Discard: Lower-ranked search results

Step Independence

Each subskill is designed to:

• Read only from waypoint files (not conversation history)
• Produce complete output in single execution
• Not depend on conversation context from previous steps
• Be runnable standalone

Error Handling

MCP Server Unavailable

• Detected in: Step 1
• Action: Display error with installation instructions
• Allow user to retry after installing MCP server
• No fallback available - MCP server is required for protocol research

Step Fails or Returns Error

• Action: Display error message from subskill
• Ask user: "Retry step? (Yes/No)"
  • Yes: Re-run step
  • No: Save current state, exit orchestrator

User Interruption

• All progress saved in waypoint files
• User can resume anytime by restarting the skill
• Workflow automatically detects completed steps and resumes from next step
• No data loss

Disclaimers

⚠️ IMPORTANT: This protocol generation tool provides preliminary clinical study protocol based on NIH/FDA guidelines and similar trials. It does NOT constitute:

• Official FDA or IRB determination or approval
• Medical, legal, or regulatory advice
• Substitute for professional biostatistician review
• Substitute for FDA Pre-Submission meeting
• Guarantee of regulatory or clinical success

REQUIRED before proceeding with clinical study:

• Biostatistician review and sample size validation
• FDA Pre-Submission meeting (Q-Submission for devices, Pre-IND for drugs)
• IRB review and approval
• Clinical expert and regulatory consultant engagement
• Legal review of protocol and informed consent
• Site investigator review and input
• Sponsor completion of all [TBD] items in protocol

PROFESSIONAL CONSULTATION STRONGLY RECOMMENDED

Clinical trial protocols are complex, high-stakes documents requiring expertise across multiple disciplines. Professional consultation with clinical trial experts, biostatisticians, and regulatory affairs specialists is essential before proceeding with clinical study planning.

Implementation Requirements

When this skill is invoked:

1. Display the welcome message with mode selection (shown in "Startup: Welcome and Mode Selection" section)

2. Wait for user mode selection (1: Research Only, 2: Full Protocol, 3: Exit)

3. Execute based on selected mode:

   • Research Only Mode (Option 1):
     • Execute Research Only Workflow Logic (Steps 0-1 only)
     • Generate formatted research summary as .md artifact
     • Offer option to continue with full protocol or exit
   • Full Protocol Mode (Option 2):
     • Execute Full Workflow Logic (Steps 0-5)
     • Check for existing waypoints and resume from last completed step
     • OR start from Step 0 if no waypoints exist
     • Execute all steps sequentially until complete

4. For each step execution (LAZY LOADING - On-Demand Only):

   • ONLY when a step is ready to execute, read the corresponding subskill file
   • Do NOT read subskill files in advance or "to prepare"
   • Example: When Step 1 needs to run, THEN read references/01-research-protocols.md and follow its instructions
   • For protocol development: Execute Steps 2, 3, 4 sequentially in order
   • Do NOT try to execute multiple steps in parallel - run sequentially
   • Read each step's subskill file only when that specific step is about to execute

5. Research summary artifact generation (Research Only Mode):

   • After Step 1 completes, read waypoint files
   • Generate comprehensive, well-formatted markdown summary
   • Save to waypoints/research_summary.md
   • Display completion message with key findings

6. Handle errors gracefully:

   • If a step fails, give user option to retry or exit
   • If MCP server unavailable, explain how to install
   • All progress is saved automatically in waypoints

7. Track progress:

   • Update waypoints/intervention_metadata.json after each step
   • Show progress indicators to user (e.g., "Progress: 3/6 steps complete" or "Progress: 2/2 research steps complete")
   • Provide clear feedback on what's happening

8. Final output:

   • Research Only: Display research summary location and offer to continue with full protocol
   • Full Protocol: Congratulate user, display protocol location and next steps
   • Remind user of disclaimers