laravel-13-app-guidelines
Skill68 starsChanged 7 months agoApache-2.0View on GitHub
Implement Laravel 13 changes or upgrade Laravel 12 to 13 using verified package versions and project conventions. Use only for the installed or requested major; optional framework features are not required dependencies.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agents-md-generatorSkill
- brainstorm-firstSkill
- debugging-workflowSkill
- design-system-generatorSkill
- docker-local-devSkill
- documentation-guidelinesSkill
- laravel-11-12-app-guidelinesSkill
- office-web-ui-systemSkill
- performance-optimizationSkill
- project-development-mindsetSkill
- run-reviewable-subtask-loopSkill
- testing-verificationSkill
- ui-ux-concept-implementationSkill
- vps-docker-traefik-deploySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
27 rules. About 0 are common, 20 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈20
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 10
Use a repository-first workflow for Laravel 13 work.
- Distinctive: line 16
Run in the main conversation by default.
- Very specific: line 20
Read repository instructions such as AGENTS.md, CLAUDE.md, and relevant docs/ files before making decisions.
- Distinctive: line 34
Follow existing architecture and naming.
- Distinctive: line 39
Do not install, upgrade, or replace packages merely because this skill lists them.
- Very specific: line 49
Treat routes/web.php and routes/console.php as fresh-application defaults.
- Distinctive: line 55
Use named arguments for Laravel framework methods cautiously because parameter names are outside Laravel's backward-compatibility promise.
- Distinctive: line 60
Keep controllers and route closures thin.
- Distinctive: line 63
Use Form Requests for reusable or non-trivial validation and authorization.
- Distinctive: line 68
Prefer Eloquent models and relationships for domain-oriented work.
- Very specific: line 76
When changing a column with change(), restate every modifier that must be retained because omitted modifiers are dropped.
- Very specific: line 85
Add or use routes/api.php only when the project exposes a stateless API.
- Distinctive: line 87
Follow the existing response envelope, error format, pagination, and versioning contract.
- Distinctive: line 89
Use Laravel 13 JSON:API Resources only when the API contract requires JSON:API.
- Distinctive: line 94
Keep API-only work independent of Vite, Tailwind, and Node unless those tools are already part of the requested surface.
- Distinctive: line 104
Use Inertia links, forms, visits, partial reloads, deferred data, and SSR only where the installed adapter and local patterns support them.
- Distinctive: line 107
Use Wayfinder only when installed.
- Very specific: line 116
Read references/stack-guidance.md when the task touches starter kits, authentication, Inertia, Livewire, Blade, Wayfinder, or Tailwind.
- Distinctive: line 131
Prefer feature tests for behavior crossing framework boundaries and focused unit tests for isolated logic.
- Distinctive: line 136
Run the smallest relevant test target.
- Distinctive: line 138
Run focused formatting, static analysis, frontend lint, type-check, build, and browser or E2E checks when they can fail for the changed …
- Distinctive: line 146
Read application information before relying on framework or package versions.
- Very specific: line 147
Use search-docs with short topic queries before implementing version-sensitive behavior.
- Distinctive: line 151
Keep database inspection read-only and scope executable-code tools to local or test environments.
- Very specific: line 154
Read references/boost-tools.md for the current tool-selection and fallback workflow.
- Distinctive: line 161
Keep credentials in environment configuration and never expose secrets in logs, fixtures, frontend bundles, or agent output.
- Distinctive: line 163
Update durable documentation when behavior, setup, public APIs, or operational procedures change.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Laravel 13 App Guidelines
Overview
Use a repository-first workflow for Laravel 13 work. Detect the actual framework, packages, frontend, command runner, and local conventions before selecting a Laravel pattern; do not turn optional Laravel 13 capabilities into dependencies.
Delegation
Run in the main conversation by default. Delegation can increase usage: obtain explicit approval for the proposed agent count and scope before using subagents. Reuse that approval within its bounds; ask again before expanding the approved count or scope.
Execute the Workflow
- Read repository instructions such as
AGENTS.md,CLAUDE.md, and relevantdocs/files before making decisions. - Inspect
composer.json,composer.lock,package.json, frontend lockfiles,bootstrap/app.php,bootstrap/providers.php, routes, configuration, and tests. Usephp artisan aboutorcomposer showwhen dependencies are installed and the repository's command runner permits it. - Identify the supported command path: host PHP, Sail, Docker Compose, or a repository wrapper. Reuse that path consistently and do not assume Sail.
- Confirm the application shape: API-only or full-stack; Blade, Livewire, or Inertia; frontend framework and major version; authentication; test runner; queue, cache, search, and database drivers.
- Consult version-matched guidance before changing framework behavior. Prefer
Laravel Boost
search-docswhen Boost is installed and available; otherwise use Laravel 13.x or the installed package's official documentation. - Follow existing architecture and naming. Implement the smallest coherent change, add or update focused tests, and run focused checks for the affected surface, plus required repository checks. Broaden only when changed contracts or unresolved risks justify it, within the authorized testing budget.
Do not install, upgrade, or replace packages merely because this skill lists them. Confirm a task requirement and compatibility first.
Apply the Laravel 13 Baseline
- Require PHP 8.3 or newer for Laravel 13 and respect the exact platform range declared by the repository and its deployment environment.
- Configure application routing, middleware, and exception handling through
bootstrap/app.phpwhen the project follows the modern skeleton. Register application providers throughbootstrap/providers.php. - Treat
routes/web.phpandroutes/console.phpas fresh-application defaults.routes/api.phpandroutes/channels.phpare optional and may be installed byinstall:apiandinstall:broadcasting; do not assume they exist. - Preserve an upgraded application's established structure when it remains supported. Do not reorganize it to resemble a fresh Laravel 13 application unless the task requires that migration.
- Use named arguments for Laravel framework methods cautiously because parameter names are outside Laravel's backward-compatibility promise.
Design HTTP and Domain Changes
- Keep controllers and route closures thin. Put reusable domain behavior in the application's existing action, service, job, model, or domain layer instead of introducing a new abstraction by default.
- Use Form Requests for reusable or non-trivial validation and authorization. Inline validation remains reasonable for a small one-off endpoint when it matches local conventions.
- Enforce authorization with policies, gates, or the repository's established authorization layer; validation is not authorization.
- Prefer Eloquent models and relationships for domain-oriented work. Use the query builder or bound raw expressions when they make bulk or complex queries clearer and measurable; never interpolate untrusted SQL.
- Prevent N+1 queries with deliberate eager loading, constrain selected columns
when useful, and use
whenLoadedin API resources. Paginate, cursor, or chunk large result sets according to consistency and memory requirements. - Wrap multi-write invariants in transactions and make queued side effects safe for retries. Dispatch after commit when consumers require committed data.
- When changing a column with
change(), restate every modifier that must be retained because omitted modifiers are dropped. Inspect the current schema first and make migrations reversible when practical. - Require authorization covering the target and data effects of destructive
operations such as
migrate:fresh,db:wipe, broad deletes, and irreversible drops. Reuse permission already given; a code edit alone does not grant it.
Build APIs Deliberately
- Add or use
routes/api.phponly when the project exposes a stateless API. Useinstall:apionly when adding that surface is part of the requested change. - Follow the existing response envelope, error format, pagination, and versioning contract. Use standard API Resources by default when the project uses them.
- Use Laravel 13 JSON:API Resources only when the API contract requires JSON:API; do not silently convert an established API format.
- Detect Sanctum, Passport, session authentication, WorkOS AuthKit, or custom authentication from installed packages and configuration. Preserve its guard and token semantics.
- Keep API-only work independent of Vite, Tailwind, and Node unless those tools are already part of the requested surface.
Follow the Detected Frontend Stack
- Discover page, component, and layout paths from the repository; casing and
locations vary. Do not assume
resources/js/Pages. - For Inertia, use the APIs supported by the installed Inertia major version. Official Laravel 13 starter kits use Inertia 3 for React, Vue, and Svelte, but existing Laravel 13 apps may use another compatible version.
- Use Inertia links, forms, visits, partial reloads, deferred data, and SSR only where the installed adapter and local patterns support them. Provide loading, empty, validation, and error states for affected interactions.
- Use Wayfinder only when installed. Prefer generated named imports where the project supports them and run the repository's route-generation or build command after route changes.
- For Livewire, follow the installed Livewire version and component style. Use Flux UI only when present; do not replace Blade or existing components merely to match a starter kit.
- For Tailwind CSS 4, preserve the project's CSS-first configuration, tokens, component library, responsive rules, and dark-mode strategy. Do not migrate a working Tailwind 3 setup unless requested.
- Read
references/stack-guidance.mdwhen the task touches starter kits, authentication, Inertia, Livewire, Blade, Wayfinder, or Tailwind.
Adopt Laravel 13 Features Only When They Fit
Laravel 13 adds first-party AI primitives, JSON:API resources, semantic and
vector search, and stronger request-forgery defaults. Treat each as an optional
design choice with package, provider, database, security, cost, and operational
consequences. Read references/laravel-13-features-and-upgrade.md before using a
new Laravel 13 feature or upgrading an application from Laravel 12.
Test, Format, and Verify
- Preserve Pest or PHPUnit according to the repository. Laravel 13 supports both; do not force PHPUnit into a Pest project or vice versa.
- Prefer feature tests for behavior crossing framework boundaries and focused unit tests for isolated logic. Add regression tests when they provide durable protection.
- Confirm generator flags with
php artisan help make:testbefore using them. For upgrades, expect Pest 4 or PHPUnit 12 only after dependency compatibility has been verified. - Run the smallest relevant test target. Use the repository wrapper and test database; never point tests at production.
- Run focused formatting, static analysis, frontend lint, type-check, build, and browser or E2E checks when they can fail for the changed surface. Complete required checks and reuse passing results unless relevant changes invalidate them. Follow explicit approval requirements for broader suites.
- Report the exact checks run, results, and any checks that could not run.
Use Laravel Boost Safely
- Read application information before relying on framework or package versions.
- Use
search-docswith short topic queries before implementing version-sensitive behavior. Let Boost filter documentation by installed package versions. - Discover the tools exposed by the installed Boost server instead of assuming every Boost release has the same names or capabilities.
- Keep database inspection read-only and scope executable-code tools to local or test environments. Never use Tinker or database tools to mutate production data without explicit authorization.
- Read
references/boost-tools.mdfor the current tool-selection and fallback workflow.
Preserve Project Integrity
- Reuse existing dependencies, components, factories, policies, resources, and conventions before creating replacements.
- Keep credentials in environment configuration and never expose secrets in logs, fixtures, frontend bundles, or agent output.
- Update durable documentation when behavior, setup, public APIs, or operational procedures change.
- Distinguish framework facts from recommendations and from repository-specific conventions in the final handoff.
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
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.

