Guidelines Skills Laravel Package

Getting Started

This package is content, not infrastructure. There is no service provider, no config file, no runtime code path, no facade. It ships four markdown skill definitions (spatie-laravel-php, spatie-javascript, spatie-version-control, spatie-security) that an AI coding agent reads as instructions. Every practical decision below follows from that single fact: you are versioning a policy document for a model, not installing a library.

Install on a Laravel team (Composer path):

composer require laravel/boost --dev
composer require spatie/guidelines-skills --dev
php artisan boost:install

At the prompts, select the Spatie guidelines and only the coding agents your team actually uses. Commit composer.json and composer.lock, and commit whatever Boost generates into your agent directories so the whole team shares one rulebook.

Install for non-PHP contributors (skills.sh path):

npx skills add spatie/guidelines-skills

Pick one channel per repository. Composer gives you a pinned, reviewable version; npx gives you whatever is current. A team running both will see agents behave differently on different machines with no visible cause — the worst class of bug, because nobody thinks to blame the AI rules.

Where to look first — not the README. Go straight to the skill files:

vendor/spatie/guidelines-skills/skills/spatie-laravel-php/SKILL.md
vendor/spatie/guidelines-skills/skills/spatie-laravel-php/references/spatie-laravel-php-guidelines.md

Each skill has the same two-layer shape: a short SKILL.md (Overview → When to Activate → Scope → Workflow → Core Rules Summary → References) and a long references/*-guidelines.md. Read the four SKILL.md summaries — that's ten minutes and it covers 90% of what the agent will actually apply. Open the reference documents only when you need depth on a specific topic, and then open the section, not the file.

Verify the skill is live before you judge it. New session, then:

"Which skills do you have loaded? Quote the first rule from spatie-laravel-php verbatim."

If it can't quote a rule, it isn't loaded — wrong agent selected during boost:install, or the editor needs a restart. An agent that silently never loaded the skill looks exactly like an agent ignoring the skill, and you will waste an afternoon on prompt engineering to fix an installation problem.

First use case — do this on day one, in fifteen minutes. Enable spatie-laravel-php and spatie-security only, and ask for something small and heavily conventional:

"Add a PostsController with index, store, and destroy actions, a StorePostRequest, and the routes."

Then diff the output against the summary rules you just read: tuple route notation [PostController::class, 'index'], camelCase route names, kebab-case URLs, plural resource controller, constructor property promotion, explicit return types including void, early returns with no else, curly braces always, config() instead of env(), array-notation validation rules. That gap between what you expected and what came out is your real adoption decision — and it is a fifteen-minute decision, not a sprint planning item.

Implementation Patterns

Generate-then-verify. Never generate-and-trust. The intended loop pairs the skill (which shapes what the agent produces) with your deterministic tooling (which catches what it got wrong):

# agent writes the code
vendor/bin/pint --test
vendor/bin/phpstan analyse
npm run lint && npx prettier --check .

The skill reduces the volume of Pint and PHPStan findings; it never removes the need for them. Anything in the skill that is also statically checkable — env() outside config/, missing return types, controller naming — should eventually be an architecture test or a PHPStan rule. Migrate high-value skill rules into CI gates over time and let the skill carry only the stylistic residue that linters can't express.

Use it as a reviewer, not only a generator. The highest value-per-token pattern in the whole package:

"Review this diff against the spatie-laravel-php skill and list only violations of its stated rules. Do not suggest refactors outside the skill."

You get a consistent, quotable review pass that doesn't invent opinions, and the identical prompt works on every PR. It's especially useful for contract or junior work where you want feedback anchored to something written down rather than to a reviewer's taste.

Respect the scope gates — they're a feature. Look at the Scope sections: spatie-laravel-php puts JS/TS, CSS, infrastructure, and schema design explicitly out of scope; spatie-javascript puts PHP, Laravel, CSS-only, and server config out of scope. In a monorepo that keeps agent context narrow and prevents cross-contamination — the classic symptom being four-space JavaScript indentation leaking into a Blade file. Practically: run PHP work and Vue/Prettier work in separate sessions, or name the skill explicitly when the file type is ambiguous.

Align Prettier to the skill, not the other way round. spatie-javascript states four-space indent, 120-character print width, single quotes, const over let, never var, strict equality, destructuring preferred. If your prettier.config.js says two spaces and 80 characters, the agent and your formatter will fight on every single file. Either update Prettier to match, or edit the vendored reference copy to match your config. Do not leave the mismatch in place and hope.

State precedence in one line, at the top of your rules file. Undefined precedence between the skill and your existing CLAUDE.md / AGENTS.md / .cursorrules is the most common real-world failure, and it costs one line to fix:

Project conventions in this file override any spatie-* skill. Where this file is silent, follow the Spatie skill. Laravel framework conventions override both.

The spatie-laravel-php workflow itself already defers — "if a rule conflicts with existing project conventions, follow Laravel conventions and keep changes consistent" — but your agent needs the local half of that contract spelled out.

Point at sections when you need depth. SKILL.md is short and cheap; the reference documents are long. For a quick edit, the summary is enough. For a migration or a test suite, be surgical:

"Read references/spatie-laravel-php-guidelines.md, section on migrations, then write the migration."

That's targeted context spend instead of inviting the agent to read everything and dilute its attention.

Pair the skill with Boost's other capabilities. Boost also provides Laravel documentation search and REPL-style tooling. Let the skill own style and Boost's doc search own API surface. An agent writing Laravel 10 syntax with immaculate formatting is still wrong, and no style guideline will catch it.

Fork deliberately, or track upstream — pick one. MIT plus plain markdown makes forking trivial:

• Track upstream: keep the --dev dependency, run composer update spatie/guidelines-skills && php artisan boost:update on your normal cadence, and treat the resulting markdown diff as a reviewed change.
• Fork-and-own: copy skills/ into your own agent skills directory, delete what conflicts with house style, add skills for what Spatie doesn't cover, drop the dependency. You now own maintenance — budget a review pass per quarter.

The only genuinely bad configuration is the half-fork, where some skills come from vendor/ and some from a local directory and nobody remembers which is which.

Fill the gaps with your own skills. Four skills cover Laravel/PHP, JS, git, and security. Nothing covers testing conventions, accessibility, CI config, deployment, or infrastructure. You now have a working template: SKILL.md with an explicit "When to Activate" and "Scope" section, plus a references/ document with the long-form rules. Write the missing ones in the same shape so the agent's loader treats them uniformly.

Onboarding hand-off. Point new hires at the skill files in vendor/ and at spatie.be/guidelines for the human-readable prose. Conventions living inside the tool someone already uses beat a wiki page nobody opens.

Gotchas and Tips

It does not enforce anything. These are instructions to a model. The package will not fail a build, will not flag env() in a controller in CI, and will not stop an agent from ignoring it. Don't let a compliance narrative attach to it — "we follow the Spatie guidelines" is not an auditable claim. Pint, PHPStan, and your test suite remain the source of truth; the skill is advisory upstream pressure.

boost:update is a silent behavior change. Unlike bumping a linter, updating this package changes what your agent believes is correct with no failing build to alert anyone. Output quality shifts quietly; the first symptom is a PR that "feels off" and nobody can say why. Pin the version, run the update as its own isolated commit, and actually read the markdown diff before merging.

Treat a guideline bump as a policy change, not a patch bump. The release history makes the point: 1.0.0 → 1.1.0 was literally "Update packaged guidelines." The content is the behavior. Skim the changelog before you run composer update.

Precedence conflicts are undefined out of the box. Spatie's conventions may contradict what you already do. spatie-version-control has opinions about repository naming (lowercase naked domain for site repos, kebab-case otherwise), a develop-during-initial-development / feature-branches-after-launch split, keeping main deployable, lowercase-hyphen branch names, present-tense granular commits, regular rebasing, and squashing feature branches — plus cautions around history-rewriting and destructive commands. If you use Conventional Commits, gitmoji, or trunk-based development, diff the skill against current practice before enabling it. Commit format is one of the cheapest things to agree on and one of the most entrenched to change.

Security rules need a scope decision, not blanket activation. spatie-security spans application (SSL, CSRF, HTTP methods, automated authorization tests, hashed passwords, encrypted API keys), database (isolated users, restricted hosts), server (SSH password auth disabled, unattended upgrades, firewall), and human process (1Password, 2FA, signed commits). The server and human-process rules are not something an agent can act on mid-PR and will just burn context. Enable it for review-oriented sessions and for code that touches auth, credentials, or authorization tests.

Two distribution channels drift. Composer pins; npx skills add takes latest. Standardize on Composer for Laravel repos and treat npx as a fallback for contributors without PHP tooling. Otherwise two developers get two different rulebooks from the same repository.

PSR-2 is cited alongside PSR-1 and PSR-12. PSR-2 is superseded by PSR-12, which is the operative standard and which Pint already enforces. Don't spend time reconciling the mention; just don't let an agent cite PSR-2 as justification for something Pint disagrees with.

Diagnosing "the agent ignores the skill" — work the list in order. (1) Is the skill file actually present under vendor/ or your agent's skills directory? (2) Did boost:install install for your agent, or a different one you also have configured? (3) Did you restart the editor or agent session? (4) Ask the agent to quote a rule verbatim. If it can't, it isn't loaded. If it can and still deviates, that's a model-following issue — the fix is a more specific prompt naming the file and the section, not reinstalling.

Watch the context budget. Loading all four reference documents into every session is expensive and dilutes attention. Enable the skills you actually use, and name the reference section you need instead of inviting wholesale reading.

Don't let the skill become the only home for these conventions. Humans need the prose version. Link spatie.be/guidelines in onboarding docs so institutional knowledge isn't locked inside a vendor/ directory that gets wiped on the next composer install.

The extension point is the filesystem. There is no config, no rules engine, no per-rule toggle, no way to say "everything except the trait rule." Customization means editing or replacing markdown files, and any edit you make to a file under vendor/ disappears on the next update. That's the whole case for forking if you disagree with more than a line or two.

Maturity check before betting on it as a standard. ~98 stars, 0 dependents, a handful of releases, and no published roadmap for testing, accessibility, or infrastructure coverage. This is a well-maintained content artifact from a respected source — not a widely-adopted industry standard. The mitigation is that forking is trivial and MIT-licensed, so vendor it if you need to, and accept upfront that you may end up owning a fork.