laravel-queues
Laravel 13 queue and job patterns — driver choice, job design (idempotency, ShouldQueue, model serialisation), retry and failure handling, worker scaling, Bus batching and chaining, Horizon when warranted, queue testing. Use when designing async jobs, scheduling background work, configuring Horizon, debugging stuck jobs, or auditing queue health. Triggers on "Laravel queue", "Laravel job", "background job", "Horizon setup", "failed jobs", "Bus batch", "queue worker tuning".
- Installs
- 704
- Last 24h
- +9
- Trending rank
- #9215
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/asyrafhussin/agent-skills --skill laravel-queues- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads laravel-queues automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Laravel Queues & Jobs
Production-grade queue patterns for Laravel 13 (MySQL + Redis). Contains 20 rules across 6 categories covering driver choice, job design, retry/failure handling, worker scaling, batching/chaining, and testing. Targets the failure modes that pass code review but break under load — silent re-dispatch on retry, models stale on serialisation, missing idempotency on payment jobs, workers leaking memory, and "we forgot ShouldQueue and the request takes 12 seconds in production."
Metadata
- Version: 1.0.0
- Scope: PHP / Laravel 13 + MySQL + Redis (queues), optional Horizon
- Rule Count: 20 rules across 6 categories
- License: MIT
How to Use
When the user asks "design this background job", "audit our queue setup", "why is this job not running", or anything queue-related — work through this skill's rules as a checklist against the relevant files (job classes, config/queue.php, config/horizon.php, supervisor config, the dispatching call sites).
For audit mode, output per-rule verdicts:
- PASS — pattern correctly applied
- FAIL — anti-pattern present (with file:line + fix recommendation)
- N/A — does not apply to this codebase
End with a top-priority fix list (idempotency on payment jobs, missing ShouldQueue, supervisor stopwaitsecs too low — these are the most common production-bite issues).
When to Apply
Reference this skill when:
- Writing a new background job (
php artisan make:job) - Reviewing a PR that adds or modifies a job class
- Setting up queue workers on a new server (Forge / Vapor / bare server)
- Configuring
config/queue.phporconfig/horizon.php - Debugging a stuck, looping, or repeatedly-failing job
- Choosing between
dispatch(),dispatchSync(),dispatchAfterResponse(),Bus::batch(),Bus::chain() - Adding queue testing (
Queue::fake(),Bus::fake()) - Deciding whether to adopt Horizon
Step 1: Detect Queue Setup
Inspect:
| File | What to learn |
|---|---|
config/queue.php | Default connection (QUEUE_CONNECTION env), failed-jobs storage, after_commit setting |
config/horizon.php (if present) | Horizon environments, balance strategy, worker counts, timeouts |
app/Jobs/*.php | Job classes, ShouldQueue usage, tries/backoff, failed() methods |
app/Console/Kernel.php or routes/console.php | Scheduled jobs (Schedule::job(...), withoutOverlapping) |
database/migrations/*_create_failed_jobs_table.php | Failed-jobs storage migration; or DynamoDB driver in config |
supervisor*.conf / /etc/supervisor/conf.d/ | Worker process management, numprocs, --max-time, stopwaitsecs |
Typical setups:
| Stack | Queue driver | Failed driver | Worker manager |
|---|---|---|---|
| Small Laravel + MySQL | database | database | Supervisor (or systemd) |
| Production Laravel + Redis | redis | database (or dynamodb for serverless) | Supervisor + Horizon |
| Laravel Vapor | sqs | dynamodb | Vapor-managed |
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Driver & Config | CRITICAL | config- |
| 2 | Job Design | CRITICAL | design- |
| 3 | Retry & Failure | HIGH | retry- |
| 4 | Scaling & Workers | HIGH | scaling- |
| 5 | Batching & Chaining | HIGH | bus- |
| 6 | Testing & Operations | MEDIUM | ops- |
Quick Reference
1. Driver & Config (CRITICAL)
config-driver-choice—databasefor small apps;redisfor production scale;sqsfor Laravel Vaporconfig-after-commit— setafter_commit: trueto prevent dispatching jobs that reference uncommitted DB rowsconfig-failed-storage—failed_jobstable is required (or DynamoDB on Vapor); set up retention/cleanup
2. Job Design (CRITICAL)
design-shouldqueue— every async job MUST implementShouldQueue(the #1 production bug: forgetting it makes the job run synchronously)design-pass-ids-not-models— pass IDs to the constructor; refetch inhandle()— avoids stale models and bloated serialised payloadsdesign-idempotency— payment, external API, and "create resource" jobs must be safe to run twice (ShouldBeUnique, idempotency keys, unique DB constraints)design-constructor-vs-handle— constructor runs at dispatch (sync);handle()runs on the worker. No DB writes or HTTP calls in the constructor.
3. Retry & Failure (HIGH)
retry-tries-and-backoff— set both:#[Backoff([1, 5, 30])]for exponential delays; default 3 tries is usually too few for transient failuresretry-failed-method— implementfailed(Throwable $e)for permanent-failure handling (alert, refund, mark-as-failed)retry-transient-vs-permanent—release($delay)for transient errors (rate-limited, network); throw for permanentretry-fail-on-timeout—#[FailOnTimeout]to avoid burning all attempts on hung jobs
4. Scaling & Workers (HIGH)
scaling-supervisor-config— Supervisor (or systemd) manages workers;stopwaitsecs > timeout;--max-time=3600to recyclescaling-multi-queue-priority— high/default/low queue lanes for SLA-critical jobs;--queue=high,default,lowscaling-worker-recycling—--max-jobsand--max-timeto combat memory leaks in long-running workers
5. Batching & Chaining (HIGH)
bus-batch-vs-chain—Bus::batchfor parallel + progress tracking;Bus::chainfor strict sequentialbus-batch-failure-handling—allowFailures()for fault-tolerant batches; usethen/catch/finallycallbacksbus-chunking-large-sets— for 1000+ items, chunk viaBus::batch(...)rather than one job per item
6. Testing & Operations (MEDIUM)
ops-queue-fake—Queue::fake()/Bus::fake()in tests;assertDispatched,assertPushed,assertChained,assertBatchedops-schedule-queued-jobs—Schedule::job(new X)->everyMinute()queues the job; pair withwithoutOverlapping()for safetyops-horizon-when— adopt Horizon when on Redis with multiple supervisors; not fordatabasequeue or single-worker setups
Essential Patterns
Minimum-viable job class (Laravel 13)
<?php
namespace App\Jobs;
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\FailOnTimeout;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Throwable;
#[Backoff([1, 5, 30])]
#[FailOnTimeout]
class ChargeOrder implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public int $tries = 5;
public int $timeout = 30;
public function __construct(public readonly int $orderId) {}
public function handle(StripeGateway $stripe): void
{
$order = Order::findOrFail($this->orderId); // refetch — don't trust serialised state
if ($order->status === 'paid') return; // idempotency guard
$charge = $stripe->charge($order);
$order->markPaid($charge->id);
}
public function failed(Throwable $e): void
{
Order::find($this->orderId)?->markPaymentFailed($e->getMessage());
}
}
Dispatching
ChargeOrder::dispatch($order->id); // default queue
ChargeOrder::dispatch($order->id)->onQueue('high'); // priority lane
ChargeOrder::dispatch($order->id)->delay(now()->addMinutes(5));
ChargeOrder::dispatchAfterResponse($order->id); // run after HTTP response sent
Supervisor config (recommended)
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/app/artisan queue:work redis --queue=high,default,low --sleep=3 --tries=3 --max-time=3600 --backoff=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=forge
numprocs=8
redirect_stderr=true
stdout_logfile=/var/www/app/storage/logs/worker.log
stopwaitsecs=3600
Critical: stopwaitsecs must be greater than your longest job's timeout, or Supervisor will kill mid-job on deploy.
References
- Laravel 13 — Queues
- Laravel 13 — Horizon
- Laravel 13 — Task Scheduling
- Supervisor — A Process Control System
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
FAQ
What does the laravel-queues skill do?
Laravel 13 queue and job patterns — driver choice, job design (idempotency, ShouldQueue, model serialisation), retry and failure handling, worker scaling, Bus batching and chaining, Horizon when warranted, queue testing. Use when designing async jobs, scheduling background work, configuring Horizon, debugging stuck jobs, or auditing queue health. Triggers on "Laravel queue", "Laravel job", "background job", "Horizon setup", "failed jobs", "Bus batch", "queue worker tuning".
How do I install laravel-queues?
Run npx skills add https://github.com/asyrafhussin/agent-skills --skill laravel-queues in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/laravel-queues/ (personal) or .claude/skills/laravel-queues/ (project).
Which AI agents can use laravel-queues?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is laravel-queues safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains laravel-queues?
It is published by asyrafhussin in asyrafhussin/agent-skills. It has 704 recorded installs.
More from asyrafhussin/agent-skills
php-best-practices
asyrafhussin/agent-skills
PHP 8.x modern patterns, PSR standards, and SOLID principles. Use when reviewing PHP code, checking type safety, auditing code quality, or ensuring PHP best practices. Triggers on "review PHP", "check PHP code", "audit PHP", or "PHP best practices".
react-vite-best-practices
asyrafhussin/agent-skills
React and Vite performance optimization guidelines. Use when writing, reviewing, or optimizing React components built with Vite. Triggers on tasks involving Vite configuration, build optimization, code splitting, lazy loading, HMR, bundle size, or React performance.
laravel-best-practices
asyrafhussin/agent-skills
Laravel 13 conventions and best practices. Use when creating controllers, models, migrations, validation, services, or structuring Laravel applications. Triggers on tasks involving Laravel architecture, Eloquent, database, API development, or PHP patterns.
laravel-inertia-react
asyrafhussin/agent-skills
Laravel + Inertia.js + React integration patterns. Use when building Inertia page components, handling forms with useForm, managing shared data, or implementing persistent layouts. Triggers on tasks involving Inertia.js, page props, form handling, or Laravel React integration.
clean-code-principles
asyrafhussin/agent-skills
SOLID principles, design patterns, DRY, KISS, and clean code fundamentals. Use when reviewing architecture, checking code quality, refactoring, or discussing design decisions. Triggers on "review architecture", "check code quality", "SOLID principles", "design patterns", or "clean code".
typescript-react-patterns
asyrafhussin/agent-skills
TypeScript best practices for React development. Use when writing typed React components, hooks, events, refs, or generic components. Triggers on tasks involving TypeScript errors, type definitions, props typing, or type-safe React patterns.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.