elixir-essentials_skill

Overview

This skill enforces a compact set of Elixir idioms and safety patterns that must be applied before writing any .ex or .exs file. It codifies Elixir best practices like pattern matching, tagged tuples, pipe usage, and supervision-first error handling. Use it as a checklist to keep code idiomatic, maintainable, and aligned with OTP conventions.

How this skill works

The skill inspects Elixir source for common anti-patterns and missing conventions: excessive if/else nesting, missing @impl on callbacks, absence of tagged-tuple returns, and misuse of pipes or with for sequential fallible operations. It highlights places to replace defensive checks with pattern matching, recommends when to let processes crash under supervision, and suggests naming and punctuation conventions (?, !). It does not modify code automatically but provides actionable guidance to apply before committing changes.

When to use it

• Mandatory for every change that adds or edits .ex or .exs files
• When implementing callbacks (GenServer, LiveView, Phoenix) to ensure @impl usage
• When writing fallible operations that should return {:ok, value} | {:error, reason}
• When converting nested case/if chains into with or multi-clause functions
• When refactoring pipelines to use |> or list comprehensions instead of multiple Enum passes

Best practices

• Prefer pattern matching and multi-clause function heads over if/else and nested conditionals
• Add @impl true to every behaviour callback to catch signature mismatches
• Return tagged tuples for fallible APIs and use with for 2+ sequential fallible steps
• Use |> for chains of 2+ transformations; use for comprehensions to combine transform+filter in one pass
• Name predicates with ? and raising helpers with !; favor let-it-crash and supervision trees over defensive checks

Example use cases

• Validating and creating resources: use with to flow validate -> build_changeset -> Repo.insert returning {:ok, resource} or formatted errors
• Refactoring HTTP response handling: replace status checks with multiple function heads matching status atoms
• GenServer callbacks: add @impl true, return tagged tuples on failure, and let supervisor restart on unexpected exceptions
• Processing collections: convert multiple Enum.map/filter/map to a single for comprehension for efficiency
• Error reporting: extract and format Ecto changeset errors into user-friendly messages before returning {:error, errors}