ccc-skill

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.

1. If <this-skill-dir>/.last_update exists and is less than 24 hours old, skip this step entirely.

2. 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
   

3. 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.

4. If upstream is the same or older, refresh .last_update silently and continue.

5. 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

1. Using scaled/z-scored data (destroys zeros needed for proportion calculation)
2. Using raw integer counts (most tools expect normalized data)
3. Ignoring expr_prop / expression threshold — lowering it inflates false positives
4. Comparing CCC across conditions without multi-sample statistics (pseudoreplication)
5. Over-interpreting low-ranked interactions from a single method

How to Use Guides

Each guide in guides/ contains:

1. When to use — scenarios where this tool is the right choice
2. Installation — quick setup
3. Core workflow — step-by-step code template
4. Key parameters — what matters and what to tune
5. Output format — where results are stored and how to access them
6. Visualization — plotting code
7. 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.