Claude Skill

oban

Use when writing, scheduling, testing or debugging Oban jobs, even for a how-to question: workers, cron, retries, unique jobs, queues, Pro Workflow/Batch. Load it before touching job code; it holds the job rules.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-plugins_elixir-phoenix_skills_oban-268ac49.zip · 10 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/oban
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

Oban Background Jobs Reference

Quick reference for Elixir Oban patterns.

Oban Pro Detection

Before applying patterns, check for Oban Pro:

grep -E "oban_pro|oban_web" mix.exs
grep -r "use Oban.Pro.Worker" lib/
grep -r "Oban.Pro.Engines.Smart" config/

If Oban Pro detected, use Pro patterns for ALL new workers:

Standard Oban Oban Pro
use Oban.Worker use Oban.Pro.Worker
def perform(%Job{}) def process(%Job{})
Oban.Testing Oban.Pro.Testing
Advisory lock engine Oban.Pro.Engines.Smart

Pro features (all optional): args_schema (typed args), Workflows, Batches, Chunks, Relay, hooks, encryption, deadlines, chaining, Smart Engine (global concurrency + rate limiting). Pro plugins (DynamicCron, DynamicLifeline, DynamicPruner) enhance OSS equivalents — swap module, don't run both. See ${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md for all patterns and migration guide.


Iron Laws — Never Violate These

  1. JOBS MUST BE IDEMPOTENT — Safe to retry. Use idempotency keys for payments
  2. JOBS MUST STORE IDs, NOT STRUCTS — JSON serialization. %{user_id: 1} not %{user: %User{}}
  3. JOBS MUST HANDLE ALL RETURN VALUES — :ok, {:error, _}, {:cancel, _}, {:snooze, _}
  4. ARGS USE STRING KEYS — Pattern match %{"user_id" => id} not %{user_id: id}
  5. UNIQUE CONSTRAINTS FOR USER ACTIONS — Prevent double-click duplicates
  6. NEVER STORE LARGE DATA IN ARGS — Store references (IDs, paths), not content
  7. SMART ENGINE: NEVER USE attempt TO LIMIT SNOOZES — Snooze rolls back attempt counter. Use meta["snoozed"] instead. Causes infinite loops

Quick Worker Template

defmodule MyApp.Workers.ExampleWorker do
  use Oban.Worker,
    queue: :default,
    max_attempts: 5,
    unique: [period: {5, :minutes}, keys: [:entity_id]]

  @impl Oban.Worker
  def perform(%Oban.Job{args: %{"entity_id" => id}}) do
    case process(id) do
      {:ok, _} -> :ok
      {:error, :not_found} -> {:cancel, "Entity not found"}
      {:error, :rate_limited} -> {:snooze, {5, :minutes}}
      {:error, reason} -> {:error, reason}
    end
  end
end

Return Value Meanings

Return State Behavior
:ok completed Success
{:ok, value} completed Success with value
{:error, reason} retryable Retry with backoff
{:cancel, reason} cancelled Stop permanently
{:snooze, seconds} scheduled Delay and retry

Quick Decisions

Which Queue?

  • Critical operations → High concurrency (20+)
  • Mailers/Webhooks (I/O) → Medium concurrency (30-50)
  • CPU-intensive → Low concurrency (3-5)
  • External APIs → Use dispatch_cooldown for rate limiting

Testing Pattern

use Oban.Testing, repo: MyApp.Repo

# Assert enqueued
assert_enqueued worker: MyApp.Worker, args: %{id: 1}

# Execute and verify
assert :ok = perform_job(MyApp.Worker, %{id: 1})

Common Anti-patterns

Wrong Right
%{user_id: id} pattern match %{"user_id" => id} (string keys)
%{user: %User{}} in args %{user_id: 1} (IDs only)
No idempotency for payments Use idempotency keys
Ignoring return values Handle all outcomes explicitly

References

For detailed patterns, see:

  • ${CLAUDE_SKILL_DIR}/references/worker-patterns.md - Worker options, backoff, timeout
  • ${CLAUDE_SKILL_DIR}/references/queue-config.md - Queue design, pool sizing, cron, Smart Engine
  • ${CLAUDE_SKILL_DIR}/references/testing-patterns.md - Testing, assertions, drain (OSS + Pro)
  • ${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md - Pro.Worker, Workflow, Batch, Chunk, Relay, plugins
Files (claude-elixir-phoenix)
  • references
    • oban-pro-basics.md 9.7 KB
      Loading…
    • queue-config.md 3.1 KB
      Loading…
    • testing-patterns.md 2.9 KB
      Loading…
    • worker-patterns.md 3 KB
      Loading…
  • SKILL.md 4.1 KB
    ---
    name: oban
    description: "Use when writing, scheduling, testing or debugging Oban jobs, even for a how-to question: workers, cron, retries, unique jobs, queues, Pro Workflow/Batch. Load it before touching job code; it holds the job rules."
    effort: medium
    user-invocable: false
    paths:
      - "**/workers/**/*.ex"
      - "**/*_worker.ex"
      - "**/*_worker_test.exs"
      - "**/*_job.ex"
    ---
    
    # Oban Background Jobs Reference
    
    Quick reference for Elixir Oban patterns.
    
    ## Oban Pro Detection
    
    **Before applying patterns, check for Oban Pro:**
    
    ```bash
    grep -E "oban_pro|oban_web" mix.exs
    grep -r "use Oban.Pro.Worker" lib/
    grep -r "Oban.Pro.Engines.Smart" config/
    ```
    
    **If Oban Pro detected**, use Pro patterns for ALL new workers:
    
    | Standard Oban | Oban Pro |
    |---------------|----------|
    | `use Oban.Worker` | `use Oban.Pro.Worker` |
    | `def perform(%Job{})` | `def process(%Job{})` |
    | `Oban.Testing` | `Oban.Pro.Testing` |
    | Advisory lock engine | `Oban.Pro.Engines.Smart` |
    
    **Pro features** (all optional): `args_schema` (typed args), Workflows, Batches, Chunks,
    Relay, hooks, encryption, deadlines, chaining, Smart Engine (global concurrency + rate limiting).
    Pro plugins (DynamicCron, DynamicLifeline, DynamicPruner) **enhance** OSS equivalents — swap module, don't run both.
    See `${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md` for all patterns and migration guide.
    
    ---
    
    ## Iron Laws — Never Violate These
    
    1. **JOBS MUST BE IDEMPOTENT** — Safe to retry. Use idempotency keys for payments
    2. **JOBS MUST STORE IDs, NOT STRUCTS** — JSON serialization. `%{user_id: 1}` not `%{user: %User{}}`
    3. **JOBS MUST HANDLE ALL RETURN VALUES** — `:ok`, `{:error, _}`, `{:cancel, _}`, `{:snooze, _}`
    4. **ARGS USE STRING KEYS** — Pattern match `%{"user_id" => id}` not `%{user_id: id}`
    5. **UNIQUE CONSTRAINTS FOR USER ACTIONS** — Prevent double-click duplicates
    6. **NEVER STORE LARGE DATA IN ARGS** — Store references (IDs, paths), not content
    7. **SMART ENGINE: NEVER USE `attempt` TO LIMIT SNOOZES** — Snooze rolls back attempt counter. Use `meta["snoozed"]` instead. Causes infinite loops
    
    ## Quick Worker Template
    
    ```elixir
    defmodule MyApp.Workers.ExampleWorker do
      use Oban.Worker,
        queue: :default,
        max_attempts: 5,
        unique: [period: {5, :minutes}, keys: [:entity_id]]
    
      @impl Oban.Worker
      def perform(%Oban.Job{args: %{"entity_id" => id}}) do
        case process(id) do
          {:ok, _} -> :ok
          {:error, :not_found} -> {:cancel, "Entity not found"}
          {:error, :rate_limited} -> {:snooze, {5, :minutes}}
          {:error, reason} -> {:error, reason}
        end
      end
    end
    ```
    
    ## Return Value Meanings
    
    | Return | State | Behavior |
    |--------|-------|----------|
    | `:ok` | `completed` | Success |
    | `{:ok, value}` | `completed` | Success with value |
    | `{:error, reason}` | `retryable` | Retry with backoff |
    | `{:cancel, reason}` | `cancelled` | Stop permanently |
    | `{:snooze, seconds}` | `scheduled` | Delay and retry |
    
    ## Quick Decisions
    
    ### Which Queue?
    
    - **Critical operations** → High concurrency (20+)
    - **Mailers/Webhooks (I/O)** → Medium concurrency (30-50)
    - **CPU-intensive** → Low concurrency (3-5)
    - **External APIs** → Use `dispatch_cooldown` for rate limiting
    
    ### Testing Pattern
    
    ```elixir
    use Oban.Testing, repo: MyApp.Repo
    
    # Assert enqueued
    assert_enqueued worker: MyApp.Worker, args: %{id: 1}
    
    # Execute and verify
    assert :ok = perform_job(MyApp.Worker, %{id: 1})
    ```
    
    ## Common Anti-patterns
    
    | Wrong | Right |
    |-------|-------|
    | `%{user_id: id}` pattern match | `%{"user_id" => id}` (string keys) |
    | `%{user: %User{}}` in args | `%{user_id: 1}` (IDs only) |
    | No idempotency for payments | Use idempotency keys |
    | Ignoring return values | Handle all outcomes explicitly |
    
    ## References
    
    For detailed patterns, see:
    
    - `${CLAUDE_SKILL_DIR}/references/worker-patterns.md` - Worker options, backoff, timeout
    - `${CLAUDE_SKILL_DIR}/references/queue-config.md` - Queue design, pool sizing, cron, Smart Engine
    - `${CLAUDE_SKILL_DIR}/references/testing-patterns.md` - Testing, assertions, drain (OSS + Pro)
    - `${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md` - Pro.Worker, Workflow, Batch, Chunk, Relay, plugins
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.