Claude Skill

elixir-idioms

OTP/BEAM patterns and Elixir idioms — GenServer, Supervisor, Task, Registry, pattern matching, with chains, pipes. Use when designing processes or debugging BEAM issues.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-plugins_elixir-phoenix_skills_elixir-idioms-9767a82.zip · 22 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/elixir-idioms
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Elixir Idioms

Reference for writing idiomatic Elixir code with BEAM-aware patterns.

Iron Laws — Never Violate These

  1. NO PROCESS WITHOUT A RUNTIME REASON — Processes model concurrency, state, isolation—NOT code structure
  2. MESSAGES ARE COPIED — Keep messages small (except binaries >64 bytes)
  3. GUARDS USE and/or/not — Never use short-circuit operators in guards (guards require boolean operands)
  4. CHANGESETS FOR EXTERNAL DATA — Use cast/4 for user input, change/2 for internal
  5. RESCUE ONLY FOR EXTERNAL CODE — Never use rescue for control flow
  6. NO DYNAMIC ATOM CREATION — String.to_atom(user_input) causes memory leak (atoms aren't GC'd)
  7. @external_resource FOR COMPILE-TIME FILES — Modules reading files at compile time MUST declare @external_resource
  8. SUPERVISE ALL LONG-LIVED PROCESSES — Never bare GenServer.start_link/Agent.start_link in production. Use supervision trees
  9. WRAP THIRD-PARTY LIBRARY APIs — Always facade external deps behind a project-owned module. Enables swapping without touching callers
  10. MIX TASKS START ONLY WHAT THEY NEED — Mix.Task.run("app.config") + Application.ensure_all_started/1, never Mix.Task.run("app.start") (boots the FULL tree: endpoint port, Oban consuming)
  11. CAPTURE LOCALE BEFORE SPAWNING — Gettext/CLDR locale is process-local. Read it in the caller and pass explicitly; a spawned Task/GenServer starts with the default locale

BEAM Architecture (Why Elixir Works This Way)

  • Processes are cheap (2.6KB) — Spawn liberally for concurrency/isolation
  • Complete memory isolation — No shared state, no locks needed
  • Messages are copied (except binaries >64 bytes) — Keep messages small
  • Per-process GC — No global GC pauses
  • "Let it crash" — Supervisors restart to known-good state

Core Principles

  1. Pattern match over conditionals — Function heads first, then case, then cond
  2. Tagged tuples for expected failures — {:ok, _}/{:error, _} for expected errors, raise for bugs
  3. Pipe operator for data transformation — Start with data, never pipe single calls
  4. Let it crash — Handle expected errors, crash on unexpected ones
  5. Explicit over implicit — Be clear about intentions

Quick Decision Trees

Control Flow

Need patterns? → case (or function heads)
Multiple operations? → with
Boolean conditions? → cond (multiple) or if (single)

Error Handling

Expected failure? → {:ok, _}/{:error, _} tuples
Unexpected/bug? → raise exception (let supervisor handle)
External library? → rescue (only here!)

OTP

Need state?
├─ No → Plain functions
├─ Simple get/update → Agent or ETS
├─ Complex messages/timeouts → GenServer
└─ One-off async → Task

Quick Patterns

# Pattern match in function head
def process(%{status: :active} = user), do: activate(user)
def process(%{status: :inactive} = user), do: deactivate(user)

# with for happy path
with {:ok, user} <- get_user(id),
     {:ok, order} <- create_order(user) do
  {:ok, order}
end

# Task for async
Task.Supervisor.async_nolink(TaskSup, fn -> work() end)
|> Task.yield(5000) || Task.shutdown(task)

Common Pitfalls

Wrong Right
length(list) == 0 list == [] or Enum.empty?(list)
list ++ [item] [item \| list] \|> Enum.reverse()
String.to_atom(input) String.to_existing_atom(input)
spawn(fn -> log(conn) end) ip = conn.ip; spawn(fn -> log(ip) end)
unless condition if !condition (unless deprecated in 1.18)

References

For detailed patterns, see:

  • ${CLAUDE_SKILL_DIR}/references/pattern-matching.md - Pattern matching, guards, binary matching
  • ${CLAUDE_SKILL_DIR}/references/otp-patterns.md - GenServer, Supervisor, Task, Registry
  • ${CLAUDE_SKILL_DIR}/references/error-handling.md - Tagged tuples, rescue, with
  • ${CLAUDE_SKILL_DIR}/references/with-and-pipes.md - When to use with and |> (idiomatic patterns)
  • ${CLAUDE_SKILL_DIR}/references/troubleshooting.md - Production BEAM debugging (memory, performance, crashes)
  • ${CLAUDE_SKILL_DIR}/references/anti-patterns.md - Common mistakes and fixes
  • ${CLAUDE_SKILL_DIR}/references/mix-tasks.md - Mix task naming, option parsing, shell output
  • ${CLAUDE_SKILL_DIR}/references/elixir-118-features.md - Duration module, dbg improvements (1.18+)
  • ${CLAUDE_SKILL_DIR}/references/elixir-120-type-system.md - Gradual type checker, dynamic(), verified bugs as compile warnings (1.20+, OTP 27+)
Files (claude-elixir-phoenix)
  • references
    • anti-patterns.md 4.6 KB
      Loading…
    • elixir-118-features.md 3.6 KB
      Loading…
    • elixir-120-type-system.md 5.9 KB
      Loading…
    • error-handling.md 2.7 KB
      Loading…
    • mix-tasks.md 2.9 KB
      Loading…
    • otp-patterns.md 10.6 KB
      Loading…
    • pattern-matching.md 1.9 KB
      Loading…
    • troubleshooting.md 4.5 KB
      Loading…
    • with-and-pipes.md 7.2 KB
      Loading…
  • SKILL.md 4.8 KB
    ---
    name: elixir-idioms
    description: "OTP/BEAM patterns and Elixir idioms — GenServer, Supervisor, Task, Registry, pattern matching, with chains, pipes. Use when designing processes or debugging BEAM issues."
    effort: medium
    user-invocable: false
    ---
    
    # Elixir Idioms
    
    Reference for writing idiomatic Elixir code with BEAM-aware patterns.
    
    ## Iron Laws — Never Violate These
    
    1. **NO PROCESS WITHOUT A RUNTIME REASON** — Processes model concurrency, state, isolation—NOT code structure
    2. **MESSAGES ARE COPIED** — Keep messages small (except binaries >64 bytes)
    3. **GUARDS USE `and`/`or`/`not`** — Never use short-circuit operators in guards (guards require boolean operands)
    4. **CHANGESETS FOR EXTERNAL DATA** — Use `cast/4` for user input, `change/2` for internal
    5. **RESCUE ONLY FOR EXTERNAL CODE** — Never use rescue for control flow
    6. **NO DYNAMIC ATOM CREATION** — `String.to_atom(user_input)` causes memory leak (atoms aren't GC'd)
    7. **@external_resource FOR COMPILE-TIME FILES** — Modules reading files at compile time MUST declare `@external_resource`
    8. **SUPERVISE ALL LONG-LIVED PROCESSES** — Never bare `GenServer.start_link`/`Agent.start_link` in production. Use supervision trees
    9. **WRAP THIRD-PARTY LIBRARY APIs** — Always facade external deps behind a project-owned module. Enables swapping without touching callers
    10. **MIX TASKS START ONLY WHAT THEY NEED** — `Mix.Task.run("app.config")` + `Application.ensure_all_started/1`, never `Mix.Task.run("app.start")` (boots the FULL tree: endpoint port, Oban consuming)
    11. **CAPTURE LOCALE BEFORE SPAWNING** — Gettext/CLDR locale is process-local. Read it in the caller and pass explicitly; a spawned Task/GenServer starts with the default locale
    
    ## BEAM Architecture (Why Elixir Works This Way)
    
    - **Processes are cheap (2.6KB)** — Spawn liberally for concurrency/isolation
    - **Complete memory isolation** — No shared state, no locks needed
    - **Messages are copied** (except binaries >64 bytes) — Keep messages small
    - **Per-process GC** — No global GC pauses
    - **"Let it crash"** — Supervisors restart to known-good state
    
    ## Core Principles
    
    1. **Pattern match over conditionals** — Function heads first, then `case`, then `cond`
    2. **Tagged tuples for expected failures** — `{:ok, _}`/`{:error, _}` for expected errors, raise for bugs
    3. **Pipe operator for data transformation** — Start with data, never pipe single calls
    4. **Let it crash** — Handle expected errors, crash on unexpected ones
    5. **Explicit over implicit** — Be clear about intentions
    
    ## Quick Decision Trees
    
    ### Control Flow
    
    ```
    Need patterns? → case (or function heads)
    Multiple operations? → with
    Boolean conditions? → cond (multiple) or if (single)
    ```
    
    ### Error Handling
    
    ```
    Expected failure? → {:ok, _}/{:error, _} tuples
    Unexpected/bug? → raise exception (let supervisor handle)
    External library? → rescue (only here!)
    ```
    
    ### OTP
    
    ```
    Need state?
    ├─ No → Plain functions
    ├─ Simple get/update → Agent or ETS
    ├─ Complex messages/timeouts → GenServer
    └─ One-off async → Task
    ```
    
    ## Quick Patterns
    
    ```elixir
    # Pattern match in function head
    def process(%{status: :active} = user), do: activate(user)
    def process(%{status: :inactive} = user), do: deactivate(user)
    
    # with for happy path
    with {:ok, user} <- get_user(id),
         {:ok, order} <- create_order(user) do
      {:ok, order}
    end
    
    # Task for async
    Task.Supervisor.async_nolink(TaskSup, fn -> work() end)
    |> Task.yield(5000) || Task.shutdown(task)
    ```
    
    ## Common Pitfalls
    
    | Wrong | Right |
    |-------|-------|
    | `length(list) == 0` | `list == []` or `Enum.empty?(list)` |
    | `list ++ [item]` | `[item \| list] \|> Enum.reverse()` |
    | `String.to_atom(input)` | `String.to_existing_atom(input)` |
    | `spawn(fn -> log(conn) end)` | `ip = conn.ip; spawn(fn -> log(ip) end)` |
    | `unless condition` | `if !condition` (unless deprecated in 1.18) |
    
    ## References
    
    For detailed patterns, see:
    
    - `${CLAUDE_SKILL_DIR}/references/pattern-matching.md` - Pattern matching, guards, binary matching
    - `${CLAUDE_SKILL_DIR}/references/otp-patterns.md` - GenServer, Supervisor, Task, Registry
    - `${CLAUDE_SKILL_DIR}/references/error-handling.md` - Tagged tuples, rescue, with
    - `${CLAUDE_SKILL_DIR}/references/with-and-pipes.md` - When to use `with` and `|>` (idiomatic patterns)
    - `${CLAUDE_SKILL_DIR}/references/troubleshooting.md` - Production BEAM debugging (memory, performance, crashes)
    - `${CLAUDE_SKILL_DIR}/references/anti-patterns.md` - Common mistakes and fixes
    - `${CLAUDE_SKILL_DIR}/references/mix-tasks.md` - Mix task naming, option parsing, shell output
    - `${CLAUDE_SKILL_DIR}/references/elixir-118-features.md` - Duration module, dbg improvements (1.18+)
    - `${CLAUDE_SKILL_DIR}/references/elixir-120-type-system.md` - Gradual type checker, `dynamic()`, verified bugs as compile warnings (1.20+, OTP 27+)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.