Skip to main content
skill CX Codex

background-jobs-designer — Claude Code skill: jobs and setup

The background-jobs-designer skill designs queued background work with retries, idempotency, and monitoring. Use it when building BullMQ, Celery, or worker-based processing.

MIT 286 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill background-jobs-designer -a claude-code
Open on GitHub

What background-jobs-designer does

background-jobs-designer lays out background processing around a queue, typed job payloads, retry rules, and failure handling. Its examples cover BullMQ in Node.js and Celery in Python, including Redis-backed queue setup and retry behavior with exponential delays.

The skill also describes job state fields, a processed-job check keyed by job.id, and transactional execution. Worker events such as completed, failed, and stalled feed metrics and logs. The accompanying checklist covers dead letter queues, timeouts, queue-depth monitoring, and graceful worker shutdown.

Without handlers for failed and stalled, the matching events will not produce the metrics shown in the examples.

What it helps with

  • design a queue for background work
  • define job types and payload fields
  • configure retries with exponential backoff
  • prevent a worker from processing the same job twice
  • track completed and stalled jobs

Example prompts for the agent

  • Design a BullMQ background email workflow with a queue, worker, retry policy, and failure handling.
  • Make process-payment idempotent by checking job.id and wrapping the work in a database transaction.
  • Add metrics and logs for the worker’s completed, failed, and stalled events.

How to install background-jobs-designer

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill background-jobs-designer -a claude-code

2Manually: put the files in place

~/.claude/skills/background-jobs-designer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/background-jobs-designer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about background-jobs-designer

How do I install background-jobs-designer in Claude Code?

Run npx skills add patricio0312rev/skills --skill background-jobs-designer -a claude-code, then check ~/.claude/skills/background-jobs-designer/SKILL.md.

What does background-jobs-designer do?

It helps design background workers with BullMQ or Celery, retry policies, idempotent execution, error handling, and monitoring hooks.

Which queue technologies does the skill cover?

The material includes BullMQ for Node.js and Celery for Python. Queue setup uses Redis or RabbitMQ; the BullMQ example connects to Redis at localhost on port 6379.

Source text

SKILL.md · MIT
---
name: background-jobs-designer
description: Designs background job processing systems with queue integration (BullMQ/Celery), job definitions, retry policies, exponential backoff, idempotent execution, and monitoring hooks. Use when implementing "background jobs", "task queues", "async processing", or "job workers".
---

# Background Jobs Designer

Design reliable background job processing with retries and monitoring.

## Queue Integration

**BullMQ (Node.js)**:

```typescript
import { Queue, Worker } from "bullmq";

const emailQueue = new Queue("email", {
  connection: { host: "localhost", port: 6379 },
});

// Add job
await emailQueue.add(
  "send-welcome",
  {
    userId: "123",
    email: "[email protected]",
  },
  {
    attempts: 3,
    backoff: { type: "exponential", delay: 2000 },
  }
);
```

**Celery (Python)**:

```python
from celery import Celery

app = Celery('tasks', broker='redis://localhost:6379')

@app.task(bind=True, max_retries=3)
def send_email(self, user_id, email):
    try:
        # Send email
        pass
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)
```

## Job Definitions

```typescript
export interface Job {
  id: string;
  type: string;
  payload: unknown;
  attempts: number;
  maxAttempts: number;
  createdAt: Date;
  processedAt?: Date;
  failedAt?: Date;
  error?: string;
}

export const JOB_TYPES = {
  SEND_EMAIL: "send-email",
  PROCESS_PAYMENT: "process-payment",
  GENERATE_REPORT: "generate-report",
  SYNC_DATA: "sync-data",
} as const;
```

## Retry Strategy

```typescript
// Exponential backoff
const RETRY_CONFIG = {
  maxAttempts: 5,
  delays: [
    1000, // 1 second
    5000, // 5 seconds
    30000, // 30 seconds
    300000, // 5 minutes
    1800000, // 30 minutes
  ],
};

// Worker with retry
const worker = new Worker("email", async (job) => {
  try {
    await sendEmail(job.data);
  } catch (error) {
    if (job.attemptsMade < RETRY_CONFIG.maxAttempts) {
      throw error; // Will retry
    }
    await handleFailedJob(job, error);
  }
});
```

## Idempotent Jobs

```typescript
// Track processed jobs
export const processJob = async (job: Job) => {
  // Check if already processed
  const processed = await db.query(
    "SELECT 1 FROM processed_jobs WHERE job_id = $1",
    [job.id]
  );

  if (processed.rows.length > 0) {
    console.log("Job already processed");
    return; // Idempotent
  }

  await db.transaction(async (trx) => {
    // Mark as processed
    await trx("processed_jobs").insert({ job_id: job.id });

    // Do work
    await performWork(job, trx);
  });
};
```

## Monitoring

```typescript
// Job events
worker.on("completed", (job) => {
  metrics.increment("jobs.completed", { type: job.name });
});

worker.on("failed", (job, err) => {
  metrics.increment("jobs.failed", { type: job.name });
  logger.error("Job failed", { jobId: job.id, error: err });
});

worker.on("stalled", (jobId) => {
  metrics.increment("jobs.stalled");
  logger.warn("Job stalled", { jobId });
});
```

## Best Practices

- Jobs should be idempotent
- Use exponential backoff for retries
- Set reasonable timeouts
- Monitor queue depth
- Dead letter queue for failed jobs
- Log job start/completion
- Graceful shutdown handling

## Output Checklist

- [ ] Queue setup (Redis/RabbitMQ)
- [ ] Job type definitions
- [ ] Retry policy with backoff
- [ ] Idempotency tracking
- [ ] Error handling
- [ ] Monitoring/metrics
- [ ] Dead letter queue
- [ ] Graceful shutdown

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Backend and APIs →

From the same set148

The whole set →
github-actions-pipeline-creator github-actions-pipeline-creator builds GitHub Actions workflows for linting, tests, builds, and deployment. Useful when a project needs caching, matrix runs, artifacts, or failure reports. CX Codex +1 288installs webhook-receiver-hardener webhook-receiver-hardener hardens webhook endpoints against spoofing, replay attacks, and duplicate event deliveries. Generates verification code, dedupe strategies, and incident guides. CX Codex +1 287installs secrets-scanner secrets-scanner catches leaked keys, tokens and passwords in a repo, with checks before commit and in CI. Handy when a .env file or a live key already slipped into history. CX Codex +1 287installs project-scaffolder project-scaffolder scaffolds complete starter repositories for web and API frameworks with configs, tooling, working baseline routes, and setup guides. CX Codex +1 287installs adr-writer The adr-writer skill turns technical choices into Architecture Decision Records with context, options, tradeoffs, consequences, and owners. Use it when a decision needs a lasting record. CX Codex +1 286installs quality-gates-enforcer quality-gates-enforcer enforces strict CI thresholds for test coverage, ESLint zero-warning rules, type safety, vulnerability audits, and bundle budgets. CX Codex +1 284installs system-design-generator system-design-generator turns product or feature requirements into architecture plans with components, data flows, API contracts, and scaling notes. Useful before implementation starts. CX Codex +1 284installs pii-redaction-logging-policy-builder pii-redaction-logging-policy-builder sets up redaction rules and a logging policy to keep sensitive user data out of logs. Replaces emails, phone numbers, and payment cards with safe placeholders. CX Codex +1 283installs

Project sponsors

Companies that keep this analytics open