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
npx skills add patricio0312rev/skills --skill background-jobs-designer -a claude-codeWhat 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-paymentidempotent by checkingjob.idand wrapping the work in a database transaction. - Add metrics and logs for the worker’s
completed,failed, andstalledevents.
How to install background-jobs-designer
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill background-jobs-designer -a claude-code2Manually: put the files in place
~/.claude/skills/background-jobs-designer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/background-jobs-designer/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill background-jobs-designer -a codex2Manually: put the files in place
.agents/skills/background-jobs-designer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill background-jobs-designer -a cursor2Manually: put the files in place
.cursor/skills/background-jobs-designer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install patricio0312rev/skills backend/background-jobs-designer/SKILL.md2Manually: put the files in place
.github/skills/background-jobs-designer/SKILL.md1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill background-jobs-designer -a gemini-cli2Platform CLI
gemini skills install https://github.com/patricio0312rev/skills --path backend/background-jobs-designerManually: put the files in place
.devin/skills/background-jobs-designer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill background-jobs-designer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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