Non-negotiable rules:
- Load
references/stack.md first, then only the task-relevant references.
- Inspect
composer.json and composer.lock before applying version-specific APIs. Recommend Laravel 13 for new applications and explicit upgrades; never silently upgrade an existing application during unrelated work.
- No business logic in controllers. Controllers validate (Form Request), delegate (Action), return (API Resource). Nothing else.
- No returning Eloquent models directly. Every response goes through an API Resource.
- No inline validation. All validation lives in Form Request classes.
- No
$guarded = []. Every model uses explicit $fillable.
- No raw queries. Use Eloquent or query builder with parameter bindings.
- No bare
queue:work. All queue processing uses Horizon.
Model::shouldBeStrict() must be enabled in AppServiceProvider::boot().
laravel
Inputs
$request: The Laravel task, bug, feature, or subsystem being worked on
Goal
Route Laravel work through the correct project conventions so the implementation follows the existing backend architecture instead of generic framework defaults.
Step 0: Read the stack contract
Always start with:
That establishes the locked runtime, package, and architecture choices for this Laravel surface.
For a new application, a framework-version decision, or a Laravel 12 to 13 upgrade, also read:
Success criteria: The project's Laravel stack choices are explicit before implementation starts.
Step 1: Load only the relevant references
Use the routing table to pick reference files that match the actual task. Do not bulk-load the full reference tree.
| Task |
Read |
| Starting a session / understanding the stack |
references/stack.md |
| New application, framework version choice, Laravel 12 to 13 upgrade |
references/upgrading.md |
| Creating or modifying files, folder conventions |
references/folder-structure.md |
| API routes, versioning, middleware |
references/routing.md |
| Creating or editing a controller |
references/controller-pattern.md |
| Adding validation to a request |
references/form-requests.md |
| Creating or editing a model, relationships, scopes |
references/eloquent-models.md |
| API response transformation, pagination, filtering |
references/api-resources.md |
| Business logic, Actions, DTOs, service providers |
references/service-layer.md |
| Authentication, tokens, roles, policies |
references/auth.md |
| Migrations, seeders, factories, query optimization |
references/database.md |
| Error responses, exception handling |
references/error-handling.md |
| Logging configuration, structured logging |
references/logging.md |
| Redis caching, cache invalidation, TTL strategy |
references/caching.md |
| Jobs, queues, events, Horizon, broadcasting |
references/queues-jobs.md |
| Writing tests (feature or unit) |
references/testing.md |
| Security hardening, CORS, rate limiting, webhooks |
references/security.md |
| API documentation generation |
references/api-docs.md |
| Telescope, Horizon dashboard, Pulse, health checks |
references/observability.md |
| Laravel/Filament integration boundary |
references/filament.md, then use the laravel-filament skill for Filament code |
| Docker setup, CI/CD, deployment |
references/docker.md |
| Notifications, email, SMS |
references/notifications-mail.md |
| File uploads, S3, media library |
references/file-storage.md |
| Task scheduling, cron jobs |
references/scheduling.md |
| AI agents, text/image/audio generation, embeddings, RAG |
references/ai-sdk.md |
| AI-assisted development, Boost setup, guidelines, skills |
references/boost.md |
| MCP servers, exposing app to AI clients, tools/resources/prompts |
references/mcp.md |
Multiple tasks? Read multiple files. The references are self-contained.
Success criteria: Only the task-relevant Laravel conventions are in play.
Step 2: Implement with the core Laravel guardrails
Keep these rules active:
- controllers validate, delegate, and return
- responses go through API Resources
- list endpoints paginate
- models use explicit
$fillable
- mutations use the correct Action or transaction pattern
- queues use the project's queue and Horizon conventions
Success criteria: The change matches the project’s Laravel architecture instead of framework-default shortcuts.
Step 3: Verify with the narrowest relevant checks
Use the smallest verification loop that matches the task:
- PHPUnit or Pest tests
- focused artisan or framework checks
- static analysis or linting if already part of the repo workflow
- for framework upgrades, the dependency and regression checks in
references/upgrading.md
Success criteria: The change is validated in the way this Laravel project expects.
Guardrails
- Do not inline the whole Laravel handbook in
SKILL.md.
- Do not skip
references/stack.md.
- Do not return raw Eloquent models directly.
- Do not put business logic in controllers.
- Do not apply Laravel 13-only APIs to a Laravel 12 project unless the task includes the upgrade.
- Do not pin today's Laravel patch release; use the supported
^13.0 constraint and the lockfile.
- Do not add
disable-model-invocation; this is a normal domain skill.
When To Load References
Output Contract
Report:
- the detected Laravel major and whether Laravel 13 was recommended or already in use
- which Laravel references were loaded
- the architecture pattern chosen
- the change made
- the verification run
1---
2name: laravel
3version: 3.0.0
4description: |
5 Write and change Laravel the way THIS project already does it, with Laravel 13 as the recommended
6 baseline for new applications and explicit compatibility handling for existing versions. Carries
7 the real controller/Action/Resource boundaries and conventions for thin controllers, Form Request
8 validation, strict Eloquent, API Resources, Horizon queues, caching, auth, observability, and the
9 Laravel AI/Boost/MCP stack. Use when a task touches this project's Laravel code and should follow
10 its backend conventions rather than generic or outdated framework defaults.
11allowed-tools:
12 - Bash
13 - Read
14 - Write
15 - Edit
16 - Grep
17argument-hint: "[Laravel task or subsystem]"
18arguments:
19 - request
20when_to_use: |
21 Use when the task touches Laravel application code, routes, controllers, models, actions,
22 requests, resources, jobs, notifications, tests, or Laravel AI/MCP integrations. Examples:
23 "add a Laravel API endpoint", "fix this model validation", "create a queued job", "wire up a
24 Laravel MCP server". Do NOT use for Filament-specific admin panels (laravel-filament) or for
25 non-Laravel code — it supplies the conventions a change follows, not the bug hunt, plan, or
26 build itself.
27effort: high
28metadata:
29 source: https://skillmd.com/skills/ulpi-io/laravel
30---
31
32<EXTREMELY-IMPORTANT>
33This skill is a routing shell over the reference set, not a place to retype the whole Laravel playbook.
34
35Non-negotiable rules:
361. Load `references/stack.md` first, then only the task-relevant references.
372. Inspect `composer.json` and `composer.lock` before applying version-specific APIs. Recommend Laravel 13 for new applications and explicit upgrades; never silently upgrade an existing application during unrelated work.
383. **No business logic in controllers.** Controllers validate (Form Request), delegate (Action), return (API Resource). Nothing else.
394. **No returning Eloquent models directly.** Every response goes through an API Resource.
405. **No inline validation.** All validation lives in Form Request classes.
416. **No `$guarded = []`.** Every model uses explicit `$fillable`.
427. **No raw queries.** Use Eloquent or query builder with parameter bindings.
438. **No bare `queue:work`.** All queue processing uses Horizon.
449. **`Model::shouldBeStrict()`** must be enabled in `AppServiceProvider::boot()`.
45</EXTREMELY-IMPORTANT>
46
47# laravel
48
49## Inputs
50
51- `$request`: The Laravel task, bug, feature, or subsystem being worked on
52
53## Goal
54
55Route Laravel work through the correct project conventions so the implementation follows the existing backend architecture instead of generic framework defaults.
56
57## Step 0: Read the stack contract
58
59Always start with:
60
61- `references/stack.md`
62
63That establishes the locked runtime, package, and architecture choices for this Laravel surface.
64
65For a new application, a framework-version decision, or a Laravel 12 to 13 upgrade, also read:
66
67- `references/upgrading.md`
68
69**Success criteria**: The project's Laravel stack choices are explicit before implementation starts.
70
71## Step 1: Load only the relevant references
72
73Use the routing table to pick reference files that match the actual task. Do not bulk-load the full reference tree.
74
75| Task | Read |
76|------|------|
77| Starting a session / understanding the stack | `references/stack.md` |
78| New application, framework version choice, Laravel 12 to 13 upgrade | `references/upgrading.md` |
79| Creating or modifying files, folder conventions | `references/folder-structure.md` |
80| API routes, versioning, middleware | `references/routing.md` |
81| Creating or editing a controller | `references/controller-pattern.md` |
82| Adding validation to a request | `references/form-requests.md` |
83| Creating or editing a model, relationships, scopes | `references/eloquent-models.md` |
84| API response transformation, pagination, filtering | `references/api-resources.md` |
85| Business logic, Actions, DTOs, service providers | `references/service-layer.md` |
86| Authentication, tokens, roles, policies | `references/auth.md` |
87| Migrations, seeders, factories, query optimization | `references/database.md` |
88| Error responses, exception handling | `references/error-handling.md` |
89| Logging configuration, structured logging | `references/logging.md` |
90| Redis caching, cache invalidation, TTL strategy | `references/caching.md` |
91| Jobs, queues, events, Horizon, broadcasting | `references/queues-jobs.md` |
92| Writing tests (feature or unit) | `references/testing.md` |
93| Security hardening, CORS, rate limiting, webhooks | `references/security.md` |
94| API documentation generation | `references/api-docs.md` |
95| Telescope, Horizon dashboard, Pulse, health checks | `references/observability.md` |
96| Laravel/Filament integration boundary | `references/filament.md`, then use the `laravel-filament` skill for Filament code |
97| Docker setup, CI/CD, deployment | `references/docker.md` |
98| Notifications, email, SMS | `references/notifications-mail.md` |
99| File uploads, S3, media library | `references/file-storage.md` |
100| Task scheduling, cron jobs | `references/scheduling.md` |
101| AI agents, text/image/audio generation, embeddings, RAG | `references/ai-sdk.md` |
102| AI-assisted development, Boost setup, guidelines, skills | `references/boost.md` |
103| MCP servers, exposing app to AI clients, tools/resources/prompts | `references/mcp.md` |
104
105Multiple tasks? Read multiple files. The references are self-contained.
106
107**Success criteria**: Only the task-relevant Laravel conventions are in play.
108
109## Step 2: Implement with the core Laravel guardrails
110
111Keep these rules active:
112
113- controllers validate, delegate, and return
114- responses go through API Resources
115- list endpoints paginate
116- models use explicit `$fillable`
117- mutations use the correct Action or transaction pattern
118- queues use the project's queue and Horizon conventions
119
120**Success criteria**: The change matches the project’s Laravel architecture instead of framework-default shortcuts.
121
122## Step 3: Verify with the narrowest relevant checks
123
124Use the smallest verification loop that matches the task:
125
126- PHPUnit or Pest tests
127- focused artisan or framework checks
128- static analysis or linting if already part of the repo workflow
129- for framework upgrades, the dependency and regression checks in `references/upgrading.md`
130
131**Success criteria**: The change is validated in the way this Laravel project expects.
132
133## Guardrails
134
135- Do not inline the whole Laravel handbook in `SKILL.md`.
136- Do not skip `references/stack.md`.
137- Do not return raw Eloquent models directly.
138- Do not put business logic in controllers.
139- Do not apply Laravel 13-only APIs to a Laravel 12 project unless the task includes the upgrade.
140- Do not pin today's Laravel patch release; use the supported `^13.0` constraint and the lockfile.
141- Do not add `disable-model-invocation`; this is a normal domain skill.
142
143## When To Load References
144
145- `references/stack.md`
146 Always.
147
148- then only the task-relevant files under `references/`
149
150## Output Contract
151
152Report:
153
1541. the detected Laravel major and whether Laravel 13 was recommended or already in use
1552. which Laravel references were loaded
1563. the architecture pattern chosen
1574. the change made
1585. the verification run