elixir-cyclic-deps

Detect and remove compile-time dependency cycles in Elixir projects using mix xref.

56|2|Updated Feb 8, 2026
One-click install
npx skills add https://github.com/matteing/opal --skill elixir-cyclic-deps
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: elixir-cyclic-deps
Source: https://github.com/matteing/opal/tree/main/.claude/skills/elixir-cyclic-deps
Command: npx skills add https://github.com/matteing/opal --skill elixir-cyclic-deps

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Detects and helps remove compile-time cyclic dependencies in Elixir projects that cause mix xref failures and broken builds, focusing on minimal code changes to restore a clean compile graph.

Core Features & Use Cases

  • Accurate cycle detection using mix xref with both compile-connected and compile labels to find modules involved in cycles.
  • Minimal-change remediation strategies such as extracting helper modules, moving code, inverting dependencies, or splitting modules to break cycles with low churn.
  • Verification workflow that re-runs xref checks, compiles with warnings-as-errors, and runs tests or lint tasks to ensure the fix is safe for CI and local development.

Quick Start

Use the elixir-cyclic-deps skill to run mix xref cycle checks, propose a minimal code change to break any compile-time cycles, and verify the project compiles and tests pass.

Frequently Asked Questions about elixir-cyclic-deps

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix compile-time dependency cycles in Elixir?

Fix Elixir compile-time dependency cycles by running mix xref to detect connected modules, then applying minimal-change strategies like extracting helpers or inverting dependencies to break the loops and restore a clean compile graph.

Why does mix xref cycle fail during my Elixir build?

mix xref cycle failures occur during Elixir builds because modules reference each other at compile time, creating cyclic dependencies that break the compilation graph and prevent successful project builds.

How do I detect which Elixir modules are causing dependency cycles?

Detect Elixir modules causing dependency cycles by running mix xref with compile-connected and compile labels, which identifies the specific modules involved in compile-time cyclic dependencies.

Does mix xref cycle detection work with older Elixir versions?

mix xref cycle detection requires Elixir 1.19 or higher for accurate compile-time dependency cycle detection, as earlier versions lack the necessary xref labeling capabilities for precise module relationship analysis.

What's the best way to break compile-time dependency cycles with minimal code changes?

Break compile-time dependency cycles with minimal code changes by extracting helper modules, moving shared code, inverting dependencies, or splitting modules to eliminate cyclic references while keeping churn low.

How do I verify Elixir dependency cycle fixes are safe for CI?

Verify Elixir dependency cycle fixes are safe for CI by re-running mix xref cycle checks, compiling with warnings-as-errors enabled, and executing the full test suite to confirm no regressions.