This source did not publish a separate summary. Review SKILL.md before using the skill.
SKILL.md
Cancer Variant Interpretation for Precision Oncology
Comprehensive clinical interpretation of somatic mutations in cancer. Transforms a gene + variant input into an actionable precision oncology report covering clinical evidence, therapeutic options, resistance mechanisms, clinical trials, and prognostic implications.
KEY PRINCIPLES:
Report-first approach - Create report file FIRST, then populate progressively
Evidence-graded - Every recommendation has an evidence tier (T1-T4)
Actionable output - Prioritized treatment options, not data dumps
Clinical focus - Answer "what should we treat with?" not "what databases exist?"
Resistance-aware - Always check for known resistance mechanisms
Cancer-type specific - Tailor all recommendations to the patient's cancer type when provided
Source-referenced - Every statement must cite the tool/database source
English-first queries - Always use English terms in tool calls (gene names, drug names, cancer types), even if the user writes in another language. Respond in the user's language
When to Use
Apply when user asks:
"What treatments exist for EGFR L858R in lung cancer?"
"Patient has BRAF V600E melanoma - what are the options?"
"Is KRAS G12C targetable?"
"Patient progressed on osimertinib - what's next?"
"What clinical trials are available for PIK3CA E545K?"
ALL 4 required: query, case_sensitive, exact_match, limit
ChEMBL_get_drug_mechanisms
chembl_id
drug_chembl_id__exact
ensembl_lookup_gene
no species
species='homo_sapiens' is REQUIRED for Ensembl IDs
Workflow Overview
Input: Gene symbol + Variant notation + Optional cancer type
Phase 1: Gene Disambiguation & ID Resolution
- Resolve gene to Ensembl ID, UniProt accession, Entrez ID
- Get gene function, pathways, protein domains
- Identify cancer type EFO ID (if cancer type provided)
Phase 2: Clinical Variant Evidence (CIViC)
- Find gene in CIViC (via Entrez ID matching)
- Get all variants for the gene
- Match specific variant
- Retrieve evidence items (predictive, prognostic, diagnostic)
- Get CIViC assertions
Phase 3: Mutation Prevalence (cBioPortal)
- Frequency across cancer studies
- Co-occurring mutations
- Cancer type distribution
Phase 4: Therapeutic Associations (OpenTargets + ChEMBL + FDA + DrugBank)
- FDA-approved targeted therapies
- Clinical trial drugs (phase 2-3)
- Drug mechanisms of action
- Drug label information
- Combination therapies
Phase 5: Resistance Mechanisms
- Known resistance variants (CIViC, literature)
- Bypass pathway analysis (Reactome)
- Secondary mutations
Phase 6: Clinical Trials
- Active trials recruiting for this mutation
- Trial phase and status
- Eligibility criteria
Phase 7: Prognostic Impact & Pathway Context
- Survival associations (literature)
- Pathway context (Reactome)
- Expression data (GTEx)
- Literature evidence (PubMed)
Phase 8: Report Synthesis
- Executive summary
- Clinical actionability score
- Treatment recommendations (prioritized)
- Completeness checklist
Phase 1: Gene Disambiguation & ID Resolution
Goal: Resolve gene symbol to all cross-database identifiers needed for downstream queries.
1.1 MyGene ID Resolution (PRIMARY)
def resolve_gene_ids(tu, gene_symbol):
"""Resolve gene symbol to Ensembl, Entrez, UniProt IDs."""
result = tu.tools.MyGene_query_genes(query=gene_symbol, species='human')
hits = result.get('hits', [])
# Take the top hit where symbol matches exactly
gene_hit = None
for hit in hits:
if hit.get('symbol', '').upper() == gene_symbol.upper():
gene_hit = hit
break
if not gene_hit and hits:
gene_hit = hits[0]
ids = {
'symbol': gene_hit.get('symbol'),
'entrez_id': gene_hit.get('entrezgene'),
'ensembl_id': gene_hit.get('ensembl', {}).get('gene'),
'name': gene_hit.get('name'),
}
return ids
def get_opentargets_info(tu, gene_symbol):
"""Resolve gene to OpenTargets ensemblId and description."""
result = tu.tools.OpenTargets_get_target_id_description_by_name(targetName=gene_symbol)
# Response: {data: {search: {hits: [{id (ensemblId), name, description}]}}}
hits = result.get('data', {}).get('search', {}).get('hits', [])
# Match exact gene symbol
for hit in hits:
if hit.get('name', '').upper() == gene_symbol.upper():
return hit
return hits[0] if hits else None
1.4 Cancer Type EFO Resolution (if cancer type provided)
def resolve_cancer_type(tu, cancer_type):
"""Resolve cancer type to EFO ID for OpenTargets queries."""
result = tu.tools.OpenTargets_get_disease_id_description_by_name(diseaseName=cancer_type)
# Response: {data: {search: {hits: [{id (efoId), name, description}]}}}
hits = result.get('data', {}).get('search', {}).get('hits', [])
return hits[0] if hits else None
1.5 Gene Function Context
def get_gene_function(tu, uniprot_accession):
"""Get protein function from UniProt.
NOTE: Returns a list of function description strings, NOT a dict.
"""
result = tu.tools.UniProt_get_function_by_accession(accession=uniprot_accession)
# Response type: list of strings
# Example: ["Receptor tyrosine kinase binding ligands of the EGF family...", ...]
return result
1.6 CIViC Gene ID Resolution
IMPORTANT: The civic_search_genes tool does NOT support name filtering in its GraphQL query. To find a gene in CIViC, either:
Paginate through results (inefficient, genes sorted alphabetically)
Use the Entrez ID from MyGene to construct a CIViC gene lookup
Workaround: Use civic_search_genes with limit=100 and search the results client-side. For genes beyond alphabetical position ~100 (like EGFR, KRAS, TP53), you may need to use the CIViC gene ID if known from prior queries or documentation.
Known CIViC Gene IDs (for common cancer genes):
Gene
CIViC Gene ID
Entrez ID
BRAF
5
673
ABL1
4
25
ALK
1
238
For other genes, the skill should attempt to find the gene through pagination or use alternative evidence sources (OpenTargets, cBioPortal) if CIViC lookup fails.
Phase 2: Clinical Variant Evidence (CIViC)
Goal: Get clinical interpretations for the specific variant.
2.1 Get Gene Variants from CIViC
def get_civic_variants(tu, civic_gene_id):
"""Get all variants for a gene in CIViC."""
result = tu.tools.civic_get_variants_by_gene(gene_id=civic_gene_id, limit=200)
# Response: {data: {gene: {variants: {nodes: [{id, name}]}}}}
variants = result.get('data', {}).get('gene', {}).get('variants', {}).get('nodes', [])
return variants
2.2 Match Specific Variant
def find_variant_in_civic(variants, variant_name):
"""Find the specific variant in CIViC results."""
# Normalize variant name (remove 'p.' prefix if present)
normalized = variant_name.replace('p.', '').strip()
for v in variants:
if v.get('name', '').upper() == normalized.upper():
return v
# Partial match (e.g., "L858" matches "L858R")
for v in variants:
if normalized.upper() in v.get('name', '').upper():
return v
return None
2.3 Get Variant Details
def get_variant_details(tu, variant_id):
"""Get detailed variant information from CIViC."""
result = tu.tools.civic_get_variant(variant_id=variant_id)
# Response: {data: {variant: {id, name}}}
return result.get('data', {}).get('variant', {})
The current CIViC tools return limited field sets from GraphQL. If CIViC data is sparse:
Fallback to literature: Use PubMed to search for "{gene} {variant} clinical significance cancer"
Fallback to OpenTargets: Use OpenTargets_target_disease_evidence for target-disease evidence
Evidence Level Mapping
CIViC Level
Tier
Meaning
Clinical Action
A
T1 (highest)
FDA-approved, guideline
Standard of care
B
T2
Clinical evidence
Strong recommendation
C
T2
Case study
Consider with caution
D
T3
Preclinical
Research context only
E
T4
Inferential
Computational evidence
Phase 3: Mutation Prevalence (cBioPortal)
Goal: Determine how common this mutation is across cancer types and studies.
3.1 Find Relevant Studies
def find_cancer_studies(tu, cancer_keyword=None):
"""Find relevant cBioPortal studies."""
result = tu.tools.cBioPortal_get_cancer_studies(limit=50)
# Response: array of [{studyId, name, description, cancerTypeId, ...}]
studies = result if isinstance(result, list) else result.get('data', [])
if cancer_keyword:
# Filter by cancer type keyword
filtered = [s for s in studies
if cancer_keyword.lower() in str(s.get('name', '')).lower()
or cancer_keyword.lower() in str(s.get('cancerTypeId', '')).lower()]
return filtered
return studies
3.2 Get Mutation Data
def get_mutation_prevalence(tu, gene_symbol, study_id):
"""Get mutation data for a gene in a specific study."""
result = tu.tools.cBioPortal_get_mutations(study_id=study_id, gene_list=gene_symbol)
# Response: {status: 'success', data: [{proteinChange, mutationType, sampleId, ...}]}
# OR sometimes a plain list. Handle both formats:
if isinstance(result, list):
mutations = result
elif isinstance(result, dict):
mutations = result.get('data', []) if result.get('status') == 'success' else []
else:
mutations = []
return mutations
3.3 Analyze Mutation Distribution
def analyze_mutation_distribution(mutations, target_variant):
"""Count how many samples have the target variant vs. others."""
from collections import Counter
protein_changes = [m.get('proteinChange', '') for m in mutations]
counts = Counter(protein_changes)
total_mutated = len(mutations)
target_count = sum(1 for m in mutations
if target_variant.upper() in str(m.get('proteinChange', '')).upper())
return {
'total_mutated_samples': total_mutated,
'target_variant_count': target_count,
'target_variant_frequency': target_count / total_mutated if total_mutated > 0 else 0,
'top_variants': counts.most_common(10),
}
3.4 Key cBioPortal Studies for Common Cancer Types
Cancer Type
Study ID
Description
Lung adenocarcinoma
luad_tcga
TCGA Lung Adenocarcinoma
Breast cancer
brca_tcga
TCGA Breast Cancer
Colorectal cancer
coadread_tcga
TCGA Colorectal
Melanoma
skcm_tcga
TCGA Melanoma
Pancreatic cancer
paad_tcga
TCGA Pancreatic
Glioblastoma
gbm_tcga
TCGA Glioblastoma
Prostate cancer
prad_tcga
TCGA Prostate
Ovarian cancer
ov_tcga
TCGA Ovarian
Phase 4: Therapeutic Associations
Goal: Identify all available therapies -- approved, in trials, and experimental.
def get_target_drugs(tu, ensembl_id, size=50):
"""Get all drugs associated with a target from OpenTargets."""
result = tu.tools.OpenTargets_get_associated_drugs_by_target_ensemblID(
ensemblId=ensembl_id, size=size
)
# Response: {data: {target: {id, approvedSymbol, knownDrugs: {count, rows: [
# {drug: {id, name, tradeNames, maximumClinicalTrialPhase, isApproved, hasBeenWithdrawn},
# phase, mechanismOfAction, disease: {id, name}}
# ]}}}}
drugs = result.get('data', {}).get('target', {}).get('knownDrugs', {})
rows = drugs.get('rows', [])
# Categorize
approved = [r for r in rows if r.get('drug', {}).get('isApproved')]
phase3 = [r for r in rows if r.get('phase') == 3 and not r.get('drug', {}).get('isApproved')]
phase2 = [r for r in rows if r.get('phase') == 2]
return {
'total': drugs.get('count', 0),
'approved': approved,
'phase3': phase3,
'phase2': phase2,
'all_rows': rows
}
4.2 OpenTargets Drug Mechanisms
def get_drug_mechanism(tu, chembl_id):
"""Get mechanism of action for a drug."""
result = tu.tools.OpenTargets_get_drug_mechanisms_of_action_by_chemblId(chemblId=chembl_id)
return result
def get_drugbank_info(tu, drug_name):
"""Get drug information from DrugBank."""
result = tu.tools.drugbank_get_drug_basic_info_by_drug_name_or_id(
query=drug_name, case_sensitive=False, exact_match=False, limit=3
)
# Response: {query, total_matches, total_returned_results, results: [{drug_name, drugbank_id, description, ...}]}
return result
4.5 ChEMBL Drug Mechanism
def get_chembl_mechanism(tu, chembl_drug_id):
"""Get drug mechanism from ChEMBL."""
result = tu.tools.ChEMBL_get_drug_mechanisms(drug_chembl_id__exact=chembl_drug_id, limit=10)
return result
4.6 Disease-Specific Drug Filtering
When cancer type is provided, filter drugs by disease association:
def get_disease_specific_drugs(tu, efo_id, size=30):
"""Get drugs associated with a specific disease/cancer type."""
result = tu.tools.OpenTargets_get_associated_drugs_by_disease_efoId(efoId=efo_id, size=size)
return result
4.7 Treatment Prioritization
Priority
Criteria
Tier
1st Line
FDA-approved for exact indication + biomarker
T1
2nd Line
FDA-approved for different indication, same biomarker
T1-T2
3rd Line
Phase 3 clinical trial data
T2
4th Line
Phase 1-2 data, off-label with evidence
T3
5th Line
Preclinical or computational only
T4
Phase 5: Resistance Mechanisms
Goal: Identify known resistance patterns and strategies to overcome them.
5.1 CIViC Resistance Evidence
Search CIViC for variants with resistance significance for the target gene. Get all variants and look for those with "Resistance" in the name or description.
5.2 Literature-Based Resistance Search
def search_resistance_literature(tu, gene_symbol, drug_name):
"""Search PubMed for resistance mechanisms.
NOTE: PubMed returns a plain list of article dicts, NOT {articles: [...]}.
"""
result = tu.tools.PubMed_search_articles(
query=f'"{gene_symbol}" AND "{drug_name}" AND resistance AND mechanism',
limit=15,
include_abstract=True
)
# Response: list of [{pmid, title, authors, journal, pub_date, doi, abstract, ...}]
articles = result if isinstance(result, list) else result.get('articles', []) if isinstance(result, dict) else []
return articles
5.3 Pathway-Based Bypass Resistance
def get_bypass_pathways(tu, uniprot_id):
"""Get pathways that could mediate bypass resistance."""
result = tu.tools.Reactome_map_uniprot_to_pathways(id=uniprot_id)
return result
5.4 Known Resistance Patterns (Reference)
Primary Target
Primary Drug
Resistance Mutation
Mechanism
Strategy
EGFR L858R
Erlotinib/Gefitinib
T790M
Steric hindrance
Osimertinib (3rd-gen TKI)
EGFR T790M
Osimertinib
C797S
Covalent bond loss
4th-gen TKI trials
BRAF V600E
Vemurafenib
Splice variants
Paradoxical activation
BRAF+MEK combination
ALK fusion
Crizotinib
L1196M, G1269A
Kinase domain mutations
Alectinib, Lorlatinib
KRAS G12C
Sotorasib
Y96D, R68S
Drug binding loss
KRAS G12C combo trials
Phase 6: Clinical Trials
Goal: Find actively recruiting clinical trials relevant to this mutation.
| NCT ID | Phase | Agent(s) | Status | Cancer Type | Biomarker |
|--------|-------|----------|--------|-------------|-----------|
Phase 7: Prognostic Impact & Pathway Context
Goal: Assess the variant's impact on prognosis and biological context.
7.1 Literature Evidence
def get_prognostic_literature(tu, gene_symbol, variant_name, cancer_type=None):
"""Search for prognostic associations."""
query = f'"{gene_symbol}" "{variant_name}" prognosis survival'
if cancer_type:
query += f' "{cancer_type}"'
result = tu.tools.PubMed_search_articles(query=query, limit=10, include_abstract=True)
return result
7.2 Pathway Context (Reactome)
def get_pathway_context(tu, uniprot_id):
"""Get pathway context from Reactome."""
result = tu.tools.Reactome_map_uniprot_to_pathways(id=uniprot_id)
return result
7.3 Gene Expression (GTEx)
def get_expression_context(tu, ensembl_id):
"""Get tissue expression data from GTEx."""
# GTEx needs versioned ID. IMPORTANT: ensembl_lookup_gene requires species parameter.
gene_info = tu.tools.ensembl_lookup_gene(gene_id=ensembl_id, species='homo_sapiens')
# Response: {status: 'success', data: {id, version, display_name, ...}}
data = gene_info.get('data', gene_info) if isinstance(gene_info, dict) else {}
version = data.get('version', 1)
versioned_id = f"{ensembl_id}.{version}"
result = tu.tools.GTEx_get_median_gene_expression(
gencode_id=versioned_id, operation='median'
)
return result
7.4 UniProt Disease Variants
def get_known_disease_variants(tu, uniprot_accession):
"""Get known disease-associated variants from UniProt."""
result = tu.tools.UniProt_get_disease_variants_by_accession(accession=uniprot_accession)
return result
Returns list of [{pmid, title, authors, journal, pub_date, doi, abstract}] (NOT wrapped in dict)
Reactome_map_uniprot_to_pathways
id (required, UniProt accession)
Pathway mappings
GTEx_get_median_gene_expression
gencode_id (required), operation="median"
Expression by tissue
UniProt_get_function_by_accession
accession (required)
Protein function
UniProt_get_disease_variants_by_accession
accession (required)
Disease variants
Common Use Cases
Use Case 1: Oncologist Evaluating Treatment Options
Input: "EGFR L858R in lung adenocarcinoma"
Expected Output: Report showing osimertinib as 1st-line [T1], with FDA label details, resistance pattern (T790M), clinical trials for combination therapies, and prognostic context.
Use Case 2: Molecular Tumor Board Preparation
Input: "BRAF V600E, colorectal cancer"
Expected Output: Report noting that BRAF V600E is actionable in melanoma but requires combination therapy in CRC (encorafenib + cetuximab), with different resistance patterns than melanoma.
Use Case 3: Clinical Trial Matching
Input: "KRAS G12C, any cancer type"
Expected Output: Report with sotorasib/adagrasib as approved options [T1], comprehensive trial listing for KRAS G12C inhibitors, resistance patterns (Y96D, etc.), and mutation prevalence across cancer types.
Use Case 4: Resistance Mechanism Investigation
Input: "EGFR T790M after osimertinib failure"
Expected Output: Report focused on C797S resistance mutation, available 4th-generation TKI trials, amivantamab/lazertinib combinations, and bypass pathway mechanisms (MET amplification, HER2 activation).
Use Case 5: VUS Interpretation
Input: "PIK3CA E545K"
Expected Output: Report showing this is a known hotspot oncogenic mutation (not a VUS), with alpelisib as FDA-approved therapy for HR+/HER2- breast cancer, and prevalence data across cancer types.
Quantified Minimums
Section
Requirement
Gene IDs
At least Ensembl + UniProt resolved
Clinical evidence
CIViC queried + PubMed literature search
Mutation prevalence
At least 1 cBioPortal study
Therapeutic options
All approved drugs listed (OpenTargets) + FDA label for top drugs
Resistance
Literature search performed + known patterns documented
Clinical trials
At least 1 search query executed
Prognostic impact
PubMed literature search performed
Pathway context
Reactome pathway mapping attempted
See Also
QUICK_START.md - Example usage and quick reference
