agentleFS
peakdong68peakdong68/my-skills/skills/laravel-specialist/SKILL.md

laravel-specialist

Skill0 starsChanged 3 months agoMITView on GitHub

Use when building or maintaining Laravel applications — Eloquent ORM, Blade, Livewire, queues, Pest testing, middleware, service providers, migrations. Trigger conditions: Laravel project setup, Eloquent model design, Blade or Livewire component creation, queue/job implementation, Pest test writing, middleware configuration, migration authoring, route definition, Form Request validation, policy authorization, Sanctum/Passport authentication, Horizon queue monitoring.

  • Reads credentials

15 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ui-ux-pro-max.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • StrayDragonSkill

    ui-ux-pro-max

    UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 8 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient.

    Also in 6 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 12 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Check for Livewire, Inertia, or Blade-only frontend stack

    line 29
  2. Very specific:

    [HARD-GATE]: When uncertain about any Laravel API — verify, don't guess.

    line 35
  3. Distinctive:

    Verify directory structure follows Laravel conventions (see section below)

    line 39
  4. Distinctive:

    Check caching strategy (config, route, view, application-level)

    line 43
  5. Distinctive:

    Write migrations first — schema is the source of truth

    line 49
  6. Distinctive:

    Create controllers (single-action or resourceful) bound to routes

    line 52
  7. Distinctive:

    Add Form Requests for validation, Policies for authorization

    line 53
  8. Very specific:

    Use {{ }} for escaped output, {!!

    line 107
  9. Very specific:

    Prefer Blade directives (@auth, @can, @env) over raw PHP conditionals

    line 108
  10. Distinctive:

    Use deferred providers for bindings that are not needed on every request

    line 157
  11. Distinctive:

    Avoid heavy logic in providers — delegate to dedicated classes

    line 158
  12. Distinctive:

    Do NOT skip migrations and edit the database directly -- migrations are the source of truth.

    line 228
  13. Distinctive:

    Do NOT put business logic in controllers because "it's faster" -- use Action classes.

    line 229
  14. Distinctive:

    Do NOT skip Form Requests because "the validation is simple" -- it always grows.

    line 230
  15. Very specific:

    Do NOT disable preventLazyLoading() because "it's annoying" -- fix the N+1 queries.

    line 231
  16. Distinctive:

    Do NOT store money as floats because "the amounts are small" -- precision errors compound.

    line 232

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Laravel Specialist

Overview

Design, build, and maintain production-grade Laravel applications following the framework's conventions and best practices. This skill covers the full Laravel ecosystem: Eloquent ORM with advanced relationship patterns, Blade templating and Livewire interactivity, queue and event systems, middleware pipelines, service providers, Pest testing at every layer, and Artisan tooling for migrations, seeders, and factories.

Apply this skill whenever Laravel is the application framework, whether greenfield or brownfield.

Multi-Phase Process

Phase 1: Context Discovery

  1. Identify Laravel version (composer.json -> laravel/framework)
  2. Scan config/ for enabled packages and custom configuration
  3. Map existing models, relationships, and migration history
  4. Review routes/ for API, web, console, and channel definitions
  5. Catalog installed first-party packages (Sanctum, Horizon, Telescope, Pulse, Pennant, Scout, Cashier)
  6. Check for Livewire, Inertia, or Blade-only frontend stack

STOP — Do NOT begin architecture review without knowing the Laravel version and installed packages.

Documentation Verification Protocol

[HARD-GATE] When uncertain about any Laravel API — verify, don't guess. Use mcp__context7__resolve-library-id then mcp__context7__query-docs (preferred). Fallback: fetch from https://github.com/laravel/docs. For Livewire, Pest, Inertia — resolve each via context7 separately. Returned docs override memorized knowledge.

Phase 2: Architecture Review

  1. Verify directory structure follows Laravel conventions (see section below)
  2. Assess service provider registrations and deferred loading
  3. Review middleware stack ordering and grouping
  4. Evaluate queue connection configuration and worker topology
  5. Check caching strategy (config, route, view, application-level)

STOP — Do NOT begin implementation until architecture gaps are documented.

Phase 3: Implementation

  1. Write migrations first — schema is the source of truth
  2. Build Eloquent models with relationships, scopes, casts, and accessors
  3. Implement business logic in dedicated Action or Service classes
  4. Create controllers (single-action or resourceful) bound to routes
  5. Add Form Requests for validation, Policies for authorization
  6. Wire events, listeners, and jobs for asynchronous workflows

STOP — Do NOT skip Form Requests and Policies. Inline validation and authorization are anti-patterns.

Phase 4: Testing

  1. Unit tests for isolated logic (Actions, Value Objects, Casts)
  2. Feature tests for HTTP endpoints and middleware behavior
  3. Browser tests with Laravel Dusk for critical user flows
  4. Database assertions with assertDatabaseHas, assertSoftDeleted
  5. Queue and event fakes for side-effect verification

STOP — Do NOT proceed to optimization without passing tests at all layers.

Phase 5: Optimization

  1. Apply eager loading to eliminate N+1 queries
  2. Cache expensive computations and config/route/view
  3. Index frequently-queried columns; use EXPLAIN to verify
  4. Profile with Telescope or Debugbar in development
  5. Configure Horizon for production queue monitoring

Eloquent Patterns

Relationships

RelationshipMethodInverseUse Case
One-to-OnehasOnebelongsToUser -> Profile
One-to-ManyhasManybelongsToPost -> Comments
Many-to-ManybelongsToManybelongsToManyUser <-> Roles (pivot)
Has-Many-ThroughhasManyThrough—Country -> Posts (through Users)
PolymorphicmorphMany / morphTomorphToComments on Posts and Videos
Many-to-Many PolymorphicmorphToManymorphedByManyTags on Posts and Videos

Scopes

See REFERENCE.md for code examples.

Accessors, Mutators, and Casts

See REFERENCE.md for code examples.

Query Optimization with Eager Loading

See REFERENCE.md for code examples.

Blade Templates and Livewire Components

Blade Conventions

  • Layouts: resources/views/layouts/app.blade.php using @yield / @section or component-based <x-app-layout>
  • Components: resources/views/components/ — anonymous or class-based
  • Partials: @include('partials.sidebar') for reusable fragments
  • Use {{ }} for escaped output, {!! !!} only when HTML is explicitly trusted
  • Prefer Blade directives (@auth, @can, @env) over raw PHP conditionals

Livewire Patterns

See REFERENCE.md for code examples.

Frontend Stack Decision Table

DecisionChoose LivewireChoose Inertia
Existing Blade codebaseYesNo
SPA-like experience requiredPartial (with wire:navigate)Yes
Team has Vue/React expertiseNoYes
Server-side rendering priorityYesDepends on adapter
Real-time reactivityYes (polling, streams)Requires Echo setup
SEO-critical pagesEither worksEither works (SSR adapter)

Queue, Job, and Event Patterns

Job Design

See REFERENCE.md for code examples.

Event / Listener Pattern

See REFERENCE.md for code examples.

Sync vs Async Decision Table

TaskQueuedSynchronous
Sending emails / notificationsYesNever in request cycle
PDF generationYesOnly if < 2s and user waits
Payment processingDepends — webhook-driven preferredIf gateway responds < 5s
Cache warmingYesNever
Audit loggingYes (high-volume) or Sync (low-volume)If guaranteed delivery needed
Search indexingYesNever

Middleware and Service Providers

Middleware Stack Ordering

Middleware order matters. The default stack in bootstrap/app.php (Laravel 11+):

See REFERENCE.md for code examples.

Service Provider Best Practices

  • Register bindings in register(), never resolve from the container there
  • Boot logic (event listeners, route model binding, macros) goes in boot()
  • Use deferred providers for bindings that are not needed on every request
  • Avoid heavy logic in providers — delegate to dedicated classes

Testing with Pest

See REFERENCE.md for code examples (Unit Test, Feature Test, Queue and Event Fakes, Browser Test).

Artisan Commands, Migrations, Seeders, Factories

Migration Conventions

See REFERENCE.md for code examples.

Factory Patterns

See REFERENCE.md for code examples.

Laravel Directory Structure Conventions

See REFERENCE.md for the full directory layout.

Decision Tables

Authentication Strategy

ScenarioRecommended Approach
SPA + same domainSanctum (cookie-based, CSRF)
SPA + different domainSanctum (token-based)
Mobile appSanctum (token-based)
Third-party API consumersPassport (OAuth2)
Simple API tokensSanctum (plaintext hash)
Social loginSocialite + Sanctum

Caching Layer

Data TypeCache DriverTTLInvalidation
Config / routes / viewsFile (artisan cache)Until next deployartisan optimize:clear
Database query resultsRedis / Memcached5-60 minEvent-driven or TTL
Full-page / fragmentRedis1-15 minCache tags
Session dataRedisSession lifetimeAutomatic
Rate limitingRedisWindow durationAutomatic

File Storage

ScenarioDiskDriver
User uploads (production)s3Amazon S3 / compatible
User uploads (local dev)localLocal filesystem
Public assetspublicLocal with symlink
Temporary fileslocalLocal, pruned by schedule

Anti-Patterns / Common Mistakes

Anti-PatternWhy It FailsWhat To Do Instead
Fat controllersUntestable, unmaintainable business logicMove logic to Action or Service classes
Raw SQL in controllersSQL injection risk, not portableUse Eloquent or Query Builder
Missing mass-assignment protectionData manipulation vulnerabilitiesAlways define $fillable or $guarded
Inline validation in controllersCouples validation to HTTP layerUse Form Requests
Jobs without retry/backoff configSilent failures, no recoveryConfigure $tries, $backoff, failed()
Over-using global scopesHidden query behavior surprises developersPrefer local scopes
Storing money as floatsFloating-point precision errorsUse integer cents, convert at presentation
Missing database indexesSlow queries at scaleAdd composite indexes for WHERE + ORDER BY
Secrets in config filesCredential leaks in version controlUse .env exclusively
Testing against production DBData corruption, unreliable testsUse SQLite in-memory or dedicated test DB
Lazy loading in API responsesN+1 queries, slow API responsesEnable preventLazyLoading() in dev

Anti-Rationalization Guards

  • Do NOT skip migrations and edit the database directly -- migrations are the source of truth.
  • Do NOT put business logic in controllers because "it's faster" -- use Action classes.
  • Do NOT skip Form Requests because "the validation is simple" -- it always grows.
  • Do NOT disable preventLazyLoading() because "it's annoying" -- fix the N+1 queries.
  • Do NOT store money as floats because "the amounts are small" -- precision errors compound.

Integration Points

SkillHow It Connects
php-specialistModern PHP 8.x patterns underpin all Laravel code
laravel-boostAI-assisted development guidelines and MCP tooling
senior-backendAPI design, caching strategies, event-driven architecture
test-driven-developmentPest testing workflow with RED-GREEN-REFACTOR
database-schema-designMigration planning, indexing strategy, data modeling
security-reviewSanctum/Passport configuration, CSRF, input validation
performance-optimizationQuery profiling, cache tuning, queue worker scaling
deploymentForge/Vapor/Envoyer deployment, artisan optimize
context7 MCPFetches up-to-date Laravel docs when information is uncertain
laravel/docs GitHubAuthoritative source for Laravel API reference

Skill Type

FLEXIBLE — Adapt the multi-phase process to the scope of work. A single model change may skip Phase 2 entirely, while a new module should follow all five phases. Core conventions (eager loading, Form Requests, Pest tests, migration-first schema changes) are non-negotiable regardless of scope.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.