Splitting Laravel Boost Guidelines Across Multiple Files

Laravel Boost discovers AI guidelines from third-party packages by reading a single file at resources/boost/guidelines/core.blade.php. When someone runs php artisan boost:install, that file is rendered and its contents get appended to the generated AGENTS.md / CLAUDE.md.

That works great for a short, focused guideline. But if your package ships enough conventions to fill hundreds of lines (architecture, code style, testing, tooling, package-specific APIs), a single core.blade.php quickly turns into a scroll-fest that nobody wants to maintain.

#The obvious thing that does not work

The first instinct is to drop several .blade.php files next to core.blade.php:

 1resources/boost/guidelines/
 2├── core.blade.php
 3├── architecture.blade.php
 4├── code-style.blade.php
 5└── testing.blade.php

Because of how Boost currently merges third-party guidelines (the files get put into a map keyed by package name, each entry overwriting the last), only one of these files ends up in the final output. The others are silently dropped. Alphabetical ordering of the file system walker decides the winner, which is rarely the file you want.

#The working pattern

Keep exactly one file in resources/boost/guidelines/ (the core.blade.php Boost reads), and put the rest in a sibling directory such as resources/boost/partials/:

 1resources/
 2└── boost/
 3    ├── guidelines/
 4    │   └── core.blade.php
 5    └── partials/
 6        ├── architecture.blade.php
 7        ├── code-style.blade.php
 8        └── testing.blade.php

Then register a Blade view namespace from your package service provider so the partials are reachable by a short identifier:

 1<?php
 2
 3namespace Vendor\ExamplePackage;
 4
 5use Illuminate\Support\ServiceProvider;
 6
 7class ExampleServiceProvider extends ServiceProvider
 8{
 9    public function boot(): void
10    {
11        $this->loadViewsFrom(
12            dirname(__DIR__) . '/resources/boost/partials',
13            'example-package',
14        );
15    }
16}

Pick a namespace that is unique across the ecosystem (typically your vendor/package combination). In core.blade.php, compose the final guideline by including the partials:

 1# Example Package
 2
 3@include('example-package::architecture')
 4
 5@include('example-package::code-style')
 6
 7@include('example-package::testing')

This works because Boost renders core.blade.php through the global Blade instance (via Blade::render()), which already knows about every view namespace registered by booted service providers. By the time boost:install runs, your loadViewsFrom() call has taken effect, and the includes resolve normally.

#One gotcha: escape your code examples

Guideline partials almost always contain code examples that use Blade-like syntax, for example:

• Directives such as @csrf, @vite(...), @include(...)
• Expressions such as {{ $user->name }}, {{ route('users.show', $user) }}
• Literal @@placeholder@@ tokens (Blade collapses @@ to a single @)

Without protection, Blade would happily try to evaluate those tokens while rendering the guideline, either throwing errors or quietly mangling your examples. Wrap each partial in @verbatim ... @endverbatim so its entire body is passed through as-is:

 1@verbatim
 2## Forms
 3
 4Always include `@csrf` in POST forms:
 5
 6```html
 7<form method="POST" action="{{ route('users.store') }}">
 8    @csrf
 9    ...
10</form>
11```
12@endverbatim

Do not wrap core.blade.php itself in @verbatim, since you want Blade to process the @include directives there.

#Why this is worth the small ceremony

• Only one file (core.blade.php) is exposed to Boost, so the overwrite behavior never kicks in.
• Partials stay organized by topic and can be edited, reviewed, and diffed independently.
• The namespaced @include syntax keeps core.blade.php tiny and readable, essentially acting as a table of contents.
• Nothing about the pattern is Boost-specific, you are just using Laravel's standard view infrastructure inside a different rendering context.

If you maintain a third-party Laravel package that is starting to outgrow a single guideline file, this is the minimal structure that lets you keep the package AI-friendly without fighting the current discovery behavior.