singlecell-portal
Programmatically query public single-cell study metadata from the Broad Institute Single Cell Portal REST API when you need to search and filter datasets by organism, tissue, disease, or cell type without an API key.
Best use case
singlecell-portal is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Programmatically query public single-cell study metadata from the Broad Institute Single Cell Portal REST API when you need to search and filter datasets by organism, tissue, disease, or cell type without an API key.
Teams using singlecell-portal 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/singlecell-portal/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How singlecell-portal Compares
| Feature / Agent | singlecell-portal | 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?
Programmatically query public single-cell study metadata from the Broad Institute Single Cell Portal REST API when you need to search and filter datasets by organism, tissue, disease, or cell type without an API key.
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
> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)
## When to Use
- You need to **discover relevant public single-cell studies** by filtering on organism (e.g., human/mouse) and tissue (e.g., lung/brain).
- You want to **quickly retrieve study-level metadata** (e.g., study name, accession, cell counts) for downstream curation or reporting.
- You are building a script or tool that needs **no authentication** and should work reliably on **Windows** with minimal setup.
- You want to **inspect available filter facets** (what tissues/diseases/cell types exist in the index) before constructing queries.
- You need a lightweight way to **validate that a study exists** and fetch its details by accession.
## Key Features
- Direct REST access to the official Single Cell Portal API (`/single_cell/api/v1/*`)
- No API key required (public endpoints)
- Faceted search for studies (organism, tissue, disease, cell type, etc.)
- Retrieve facet dictionaries to build valid filters
- Retrieve study details by accession
- Minimal dependency footprint (only `requests`)
- Windows-friendly behavior (optional SSL verification disablement for certificate issues)
## Dependencies
- `requests==2.31.0`
## Example Usage
```python
import requests
BASE_URL = "https://singlecell.broadinstitute.org/single_cell/api/v1"
def scp_get(path: str, params=None, verify_ssl: bool = True, timeout: int = 30):
"""
Minimal helper for Single Cell Portal API calls.
Security note:
- Only call official endpoints under:
https://singlecell.broadinstitute.org/single_cell/api/v1/*
- If you encounter Windows certificate issues, set verify_ssl=False.
"""
url = f"{BASE_URL}{path}"
resp = requests.get(url, params=params or {}, timeout=timeout, verify=verify_ssl)
resp.raise_for_status()
return resp.json()
def search_studies(facets: str, size: int = 5):
return scp_get("/search", params={"facets": facets, "size": size})
def get_facets():
return scp_get("/search/facets")
def get_study(accession: str):
return scp_get(f"/studies/{accession}")
if __name__ == "__main__":
# 1) Search: human lung studies
results = search_studies("organism:human,tissue:lung", size=5)
studies = results.get("studies", [])
print("Top matches:")
for s in studies:
print(f"- {s.get('name')} | accession={s.get('accession')} | cells={s.get('cell_count')}")
# 2) Inspect available facet values (useful to build valid filters)
facet_info = get_facets()
print("\nFacet keys available:", ", ".join(sorted(facet_info.keys())))
# 3) Fetch details for the first returned study (if any)
if studies and studies[0].get("accession"):
acc = studies[0]["accession"]
detail = get_study(acc)
print(f"\nStudy detail for {acc}:")
print("Name:", detail.get("name"))
print("Description:", detail.get("description"))
```
## Implementation Details
- **Base endpoint constraint**: All network requests must target
`https://singlecell.broadinstitute.org/single_cell/api/v1/*`
(no third-party URLs).
- **Core endpoints**:
- `GET /search`: returns study search results (metadata)
- `GET /search/facets`: returns available facet keys/values for filtering
- `GET /studies/{accession}`: returns details for a specific study
- **Facet filtering (`facets` parameter)**:
- Format: comma-separated `key:value` pairs, e.g. `organism:human,tissue:lung`
- Common facet keys include: `organism`, `tissue`, `disease`, `cell_type`
- Some values may be multi-word (e.g., `T cell`); pass them as-is in the string.
- **Pagination / result size**:
- `size` controls the number of returned studies (default behavior depends on the API; set explicitly for deterministic results).
- **SSL handling on Windows**:
- If certificate verification fails in certain environments, you may set `verify=False` in `requests.get(...)`.
- Prefer `verify=True` when possible; disabling verification reduces transport security.
- **Error handling**:
- Use `response.raise_for_status()` to surface HTTP errors.
- Treat missing keys defensively (`dict.get`) because response shapes may evolve.
- **Data scope**:
- The API primarily returns **metadata**; raw data downloads typically occur via the portal’s dataset pages and are not covered by these endpoints.Related Skills
skill-auditor
A comprehensive auditor for any agent skill — including Manus, OpenClaw/ClawHub, Claude, LobeHub, or custom SKILL.md-based skills. Use this skill whenever a user wants to evaluate, audit, review, score, or quality-check an agent skill before publishing, updating, or deploying. Covers two hard veto gates (structural redlines + research integrity redlines), static quality scoring across 25 criteria (ISO 25010 + OpenSSF + Agent), dynamic test input generation, multi-mode execution testing, multi-layer output evaluation with five specialized category rubrics (Evidence Insight / Protocol Design / Data Analysis / Academic Writing / Other), a Research Veto that applies to all four research categories, human eval viewer generation, actionable P0/P1/P2 optimization recommendations, and automatic skill improvement that outputs a polished, production-ready SKILL.md. Also use whenever a user says "audit my skill", "evaluate my skill", "improve my skill", or wants a corrected version after evaluation.
two-sample-mr-research-planner
Generates complete two-sample Mendelian randomization (MR) research designs from a user-provided research direction. Use when users want to design, plan, or build a study using two-sample MR to test causal relationships. Triggers:"design a two-sample MR study", "build a publishable MR paper", "test whether this biomarker causally affects this disease", "generate Lite/Standard/Advanced MR plans", "screen multiple exposures with MR", "bidirectional MR design", "causal inference using GWAS summary statistics", or "I want to study X and Y using MR". Always outputs four workload configurations (Lite / Standard / Advanced / Publication+) with a recommended primary plan, step-by-step workflow, figure plan, validation strategy, minimal executable version, and publication upgrade path.
research-proposal-generator
Generates a comprehensive research proposal design based on input literature, including hypothesis, mechanism verification, and budget. Use when the user wants to design a research project from a paper.
research-grants
Write competitive research proposals for NSF, NIH, DOE, DARPA, and Taiwan's NSTC when you need agency-compliant narratives, budgets, and review-criteria alignment for a specific solicitation/FOA/BAA.
protocol-standardization
Standardize fragmented experimental steps into reproducible protocol documents when you need method organization, lab SOP drafting, or cross-operator reproducibility; missing parameters must be explicitly marked as "To be supplemented/Not provided".
prospero-registration-helper
Assists researchers in generating PROSPERO registration content for meta-analyses from a title and optional protocol. Use when the user wants to draft a PROSPERO registration form.
non-tumor-ml-research-planner
Generates complete non-tumor biomedical machine learning research designs from a user-provided research direction. Always use this skill when users want to plan bioinformatics + ML papers for non-cancer diseases (metabolic, cardiovascular, kidney, inflammatory, autoimmune, infectious, neurological, endocrine, wound healing, chronic multifactor), design diagnostic biomarker studies, combine GEO datasets with feature selection and ML modeling, or generate Lite/Standard/Advanced/Publication+ workload plans. Trigger for:"non-tumor ML study", "bioinformatics paper outside oncology", "key genes and diagnostic model for a disease", "pyroptosis/ferroptosis/senescence/autophagy + disease", "GEO datasets + machine learning", "RF + LASSO diagnostic model", "DEG + feature selection + validation", "immune infiltration + biomarker", "non-cancer biomarker paper". Trigger even for casual phrasings like "I want to study X using machine learning", "help me design a non-tumor bioinformatics paper", or "how do I build a diagnostic model for disease Y".
network-tox-docking-research-planner
Generates complete network toxicology + molecular docking research designs from a user-provided toxicant and disease/phenotype. Always use this skill when users want to investigate how an environmental toxicant, endocrine disruptor, heavy metal, food contaminant, pharmaceutical residue, or consumer product chemical may contribute to a disease through shared molecular targets, hub genes, pathways, and docking evidence. Trigger for:"network toxicology study", "toxicology mechanism paper", "target prediction + PPI + docking", "environmental pollutant and disease mechanism", "hub genes and docking for toxicant", "Lite/Standard/Advanced toxicology plan", "CTD + SwissTargetPrediction + GeneCards + STRING", "CB-Dock2 docking study", "triclosan/BPA/cadmium/PFAS + disease". Also triggers for Chinese phrasings:"网络毒理学研究设计"、"毒物机制论文"、"靶点预测+PPI+对接"、"环境污染物与疾病机制". Trigger even for casual phrasings like "I want to study how chemical X affects disease Y" or "help me design a toxicology paper". Always output four workload configurations (Lite / Standard / Advanced / Publication+) with a recommended primary plan, step-by-step workflow, figure plan, validation strategy, minimal executable version, and publication upgrade path.
meta-protocol-writer
Generates a PROSPERO-compliant Meta-analysis protocol based on Title and PICOS. Use when the user wants to write a protocol for a systematic review or meta-analysis.
hypothesis-generation
Structured scientific hypothesis formulation from observations; use when you have experimental observations or preliminary data and need testable hypotheses with predictions, mechanisms, and validation experiments.
hypogenic
Automated LLM-driven hypothesis generation and testing for tabular datasets; use when you need systematic exploration of empirical patterns (e.g., fraud detection, content analysis) and want to combine literature insights with data-driven hypothesis evaluation.
faers-multi-drug-soc-planner
Generates complete FAERS-based multi-drug single-SOC safety comparison research designs from a user-provided drug set, comparator, and adverse event domain. Always use this skill when users want to compare safety signals across multiple drugs using FAERS or OpenFDA data within one System Organ Class (SOC) or bounded AE domain. Trigger for:"FAERS study comparing drugs within one SOC", "publishable FAERS safety comparison paper", "compare neuropsychiatric adverse events across beta-blockers", "Lite/Standard/Advanced FAERS safety plans", "active-comparator restricted disproportionality", "adjusted ROR logistic regression FAERS", "within-class head-to-head drug comparison", "pharmacovigilance signal comparison", "single-SOC PT-level FAERS design", or any phrasing like "I want to compare drug X and drug Y for adverse events in FAERS" or "build a comparative pharmacovigilance paper". Always output four workload configurations (Lite / Standard / Advanced / Publication+) with a recommended primary plan, step-by-step workflow, figure plan, validation strategy, minimal executable version, and publication upgrade path.