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.
How do I install this agent skill?
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix --skill obanIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a professional development reference for Elixir's Oban background job library. It provides guidelines on worker patterns, testing, and configuration for both OSS and Pro versions. No security issues or malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1/5 files flagged
What does this agent skill do?
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
- JOBS MUST BE IDEMPOTENT — Safe to retry. Use idempotency keys for payments
- JOBS MUST STORE IDs, NOT STRUCTS — JSON serialization.
%{user_id: 1}not%{user: %User{}} - JOBS MUST HANDLE ALL RETURN VALUES —
:ok,{:error, _},{:cancel, _},{:snooze, _} - ARGS USE STRING KEYS — Pattern match
%{"user_id" => id}not%{user_id: id} - UNIQUE CONSTRAINTS FOR USER ACTIONS — Prevent double-click duplicates
- NEVER STORE LARGE DATA IN ARGS — Store references (IDs, paths), not content
- SMART ENGINE: NEVER USE
attemptTO LIMIT SNOOZES — Snooze rolls back attempt counter. Usemeta["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_cooldownfor 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oliver-kriska/claude-elixir-phoenix/oban">View oban on skillZs</a>