| name | ccc-skill |
| description | Domain expertise for cell-cell communication (CCC) analysis. Intent-to-tool routing, workflow patterns, code templates, and pitfall warnings for LIANA+, CellPhoneDB, CellChat, NicheNet, COMMOT, Squidpy, MEBOCOST, DIALOGUE, and 10+ additional tools across scRNA-seq and spatial transcriptomics data. |
| license | MIT |
| homepage | https://github.com/Agents365-ai/ccc-skill |
| platforms | ["macos","linux","windows"] |
| metadata | {"author":"Agents365-ai","version":"0.2.0"} |
Cell-Cell Communication Analysis Skill
You are an expert in cell-cell communication (CCC) inference from single-cell and spatial transcriptomics. Use this skill to select the right tool, design the workflow, and generate correct code.
Step 0. Update check (notify, don't pull) — first use per conversation
Throttle to one check per 24 hours per installation; never mutate the skill directory without explicit user consent.
-
If <this-skill-dir>/.last_update exists and is less than 24 hours old, skip this step entirely.
-
Otherwise, fetch the latest tag from upstream:
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
| awk '{print $2}' | sed 's|refs/tags/||' \
| sort -V | tail -1
-
Compare with this skill's metadata.version from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:
"A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to git pull?"
If they say yes, run git -C <this-skill-dir> pull --ff-only. Refresh .last_update either way so the prompt doesn't repeat for 24 hours.
-
If upstream is the same or older, refresh .last_update silently and continue.
-
On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.
Decision Tree
Use this decision tree to recommend the right tool(s). Multiple tools can be combined.
Step 1: What is the primary analysis goal?
| Goal | Recommended Tool(s) | Guide |
|---|
| Ligand-receptor inference (steady-state) | LIANA+ rank_aggregate or CellPhoneDB | liana.md, cellphonedb.md |
| LR with signaling pathway hierarchy | CellChat | cellchat.md |
| Ligand → downstream target gene prediction | NicheNet / MultiNicheNet | nichenet.md |
| Spatial CCC with distance decay | COMMOT or LIANA+ bivariate | commot.md, liana.md |
| Spatial CCC within scanpy/scverse pipeline | Squidpy sq.gr.ligrec() | squidpy.md |
| Spatial CCC + H&E morphology | stLearn — docs | |
| Spatial CCC + knowledge graph pathway cascade | SpaTalk — GitHub | |
| Spatial signaling direction / vector fields | COMMOT | commot.md |
| Multi-sample / multi-condition comparison | LIANA+ tensor/MOFA+, CellChat merged, MultiNicheNet | liana.md, cellchat.md, nichenet.md |
| Cross-context CCC pattern discovery (tensor) | cell2cell / Tensor-cell2cell — GitHub | |
| Differential CCC network analysis | CrossTalkeR — GitHub | |
| Differential CCC with aging focus | scDiffCom — GitHub |
Step 2: What data type?
| Data Type | Compatible Tools |
|---|
| scRNA-seq (Python/AnnData) | LIANA+, CellPhoneDB, MEBOCOST, Squidpy |
| scRNA-seq (R/Seurat) | CellChat, NicheNet, DIALOGUE, NICHES, Scriabin |
| Spatial spot-based (Visium) | LIANA+ bivariate, COMMOT, CellChat v2, Squidpy, stLearn, SpaTalk |
| Spatial single-cell (MERFISH, Xenium) | COMMOT, LIANA+ bivariate/inflow, CellChat v3 |
| Multi-modal (MuData) | LIANA+ |
| Multi-sample comparison | LIANA+ tensor/MOFA+, CellChat merged, MultiNicheNet, cell2cell, scDiffCom |
| Brain / neuronal | NeuronChat (specialized LR database) |
Step 3: Language preference?
| Language | Tools |
|---|
| Python | LIANA+, CellPhoneDB, COMMOT, Squidpy, MEBOCOST, CellOracle, SCENIC+, FlowSig, stLearn, cell2cell |
| R | CellChat, NicheNet/MultiNicheNet, DIALOGUE, NICHES, Scriabin, SpaTalk, CrossTalkeR, scDiffCom, NeuronChat |
Tools with Full Guides (8)
| Tool | Language | Guide | Unique Strength |
|---|
| LIANA+ | Python | liana.md | Multi-method meta-analysis + spatial + tensor/MOFA+ |
| CellPhoneDB | Python | cellphonedb.md | Curated DB + heteromeric complexes + v5 scoring |
| CellChat | R | cellchat.md | Pathway hierarchy + rich visualization + comparison |
| NicheNet | R | nichenet.md | Ligand→TF→target prediction + MultiNicheNet |
| COMMOT | Python | commot.md | Optimal transport spatial CCC + vector fields |
| Squidpy | Python | squidpy.md | scverse ecosystem LR analysis, zero-friction spatial |
| MEBOCOST | Python | mebocost.md | Metabolite-mediated CCC (non-protein signals) |
| DIALOGUE | R | dialogue.md | Multicellular programs (cross-cell-type coordination) |
Additional Tools (brief reference)
These tools are referenced in the decision tree but do not have dedicated guides. Use official documentation.
| Tool | Language | Stars | When to Use | Link |
|---|
| CellOracle | Python | 440 | GRN + in silico TF perturbation → predict cell state after signal | GitHub |
| SCENIC+ | Python | 251 | Multi-omic GRN (scRNA+scATAC) → regulatory context of CCC | GitHub |
| stLearn | Python | 244 | Spatial CCC combining H&E morphology + expression | GitHub |
| MultiNicheNet | R | 185 | Multi-sample differential CCC (pseudobulk + edgeR) | GitHub |
| Scriabin | R | 106 | Single-cell resolution CCC, atlas-scale | GitHub |
| FlowSig | Python | 86 | Causal flow inference on top of CCC outputs (post-analysis) | GitHub |
| cell2cell | Python | 79 | Tensor decomposition across contexts (time/tissue/disease) | GitHub |
| SpaTalk | R | 76 | Spatial + knowledge graph LR→target pathway cascade | GitHub |
| NICHES | R | 58 | Single-cell resolution niche interactions (cell-pair objects) | GitHub |
| CrossTalkeR | R/Python | 49 | Differential CCC network visualization + centrality | GitHub |
| NeuronChat | R | 45 | Neural-specific LR database (synaptic, gap junction, neuromodulator) | GitHub |
Universal CCC Principles
LR Database Selection
- consensus (LIANA+ default): union of multiple databases — broadest coverage, recommended for discovery
- CellPhoneDB: manually curated, strong on heteromeric complexes — best for confidence
- CellChatDB: pathway-annotated — best when you need pathway-level grouping
- Omnipath (Squidpy default): comprehensive multi-source integration
- Custom: always an option; filter to expressed genes for performance
Preprocessing Requirements (all tools)
- Normalized, log-transformed expression (NOT raw counts, NOT scaled/z-scored)
- Cell type annotations in metadata
- For spatial: coordinates in the correct unit system
Interpreting Results
- No single tool is ground truth — consider running 2+ tools and looking for consensus
- Magnitude vs specificity: high expression doesn't mean specific; highly specific doesn't mean strong
- Permutation p-values: affected by cell type size imbalance — small populations have less power
- Spatial distance: paracrine signals (~100-500um) vs juxtacrine/contact (~10-50um) need different cutoffs
Common Mistakes to Avoid
- Using scaled/z-scored data (destroys zeros needed for proportion calculation)
- Using raw integer counts (most tools expect normalized data)
- Ignoring
expr_prop / expression threshold — lowering it inflates false positives
- Comparing CCC across conditions without multi-sample statistics (pseudoreplication)
- Over-interpreting low-ranked interactions from a single method
How to Use Guides
Each guide in guides/ contains:
- When to use — scenarios where this tool is the right choice
- Installation — quick setup
- Core workflow — step-by-step code template
- Key parameters — what matters and what to tune
- Output format — where results are stored and how to access them
- Visualization — plotting code
- Pitfalls — tool-specific gotchas
Read the relevant guide(s) based on the decision tree above, then generate code following the templates. For tools without guides, refer to the official documentation linked in the table.
