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.

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

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.

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

1. 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?

Step 2: What data type?

Step 3: Language preference?

Tools with Full Guides (8)

Additional Tools (brief reference)

These tools are referenced in the decision tree but do not have dedicated guides. Use official documentation.

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.