Guidelines Skills Laravel Package

Technical Evaluation

Architecture fit

This is not a library — it is a content artifact. 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), each a short SKILL.md (overview, activation triggers, scope, summary rules) plus a long references/ document that an AI agent reads on demand.

That means its architectural role is advisory upstream pressure on code generation, sitting beside — not inside — the enforcement layer:

It fits cleanly as a --dev dependency in Laravel repos where the team already uses a coding agent. It is a poor fit anywhere the expectation is "this makes our code compliant" — it cannot fail a build.

Integration feasibility

Genuinely low effort. Two install paths:

• Composer (recommended for Laravel): composer require laravel/boost --dev, composer require spatie/guidelines-skills --dev, php artisan boost:install, then select the Spatie guidelines and the agents you actually use. Updates are composer update spatie/guidelines-skills && php artisan boost:update.
• skills.sh (non-Composer contributors): npx skills add spatie/guidelines-skills. Effectively tracks latest.

No version constraints to negotiate against a Laravel runtime, no autoload conflicts, no migration. Pick one channel per repo — mixing a pinned Composer version with npx latest produces divergent agent behavior across machines with no visible cause.

Technical risk

• Zero enforcement. Nothing here blocks a merge. If a compliance narrative attaches to this package, it will be wrong. Linters and static analysis remain the source of truth.
• Silent behavior change on update. boost:update changes what your agent believes is correct with no failing build to alert you. Release 1.0.0 → 1.1.0 was literally "update packaged guidelines." Treat a guideline bump as a policy change and review the markdown diff.
• Undefined precedence. Spatie's branch naming, repo naming, and commit message conventions will collide with entrenched practice (Conventional Commits, gitmoji). Out of the box there is no stated ordering between the skill and your existing AGENTS.md.
• Formatter fight. The JS skill mandates four-space indent, 120-char width, single quotes. A prettier.config.js at two spaces / 80 makes agent and formatter disagree on every file.
• Maturity/coverage. ~98 stars, 0 dependents, two releases, no published roadmap. No coverage for testing conventions, accessibility, CI config, deployment, or infrastructure. The mitigation is that MIT + plain markdown makes forking trivial.
• Accuracy nits. The Laravel/PHP skill cites PSR-2 alongside PSR-1 and PSR-12; PSR-2 is superseded, PSR-12 is operative and Pint already enforces it.
• Context cost. Loading all four reference documents dilutes attention and burns budget.

Key questions

1. Which agents and editors are in scope, and does boost:install target the one each engineer actually runs?
2. Who owns the pin, the boost:update PR, and reading the guideline diff before merge?
3. Which skill rules are statically checkable and should be promoted to PHPStan rules or architecture tests within one quarter?
4. Are we tracking upstream or forking? A half-fork (some skills from vendor/, some local) is the worst configuration.
5. Does spatie-version-control conflict with our existing commit/branch discipline, and who arbitrates?
6. Do we standardize on Composer-only, and how do we handle contributors without PHP tooling?

Integration Approach

Stack fit

Direct fit for Laravel/PHP backends on a Laravel version supported by laravel/boost (the docs reference Laravel 13.x Boost). Secondary fit for JS/TS/Vue frontends via spatie-javascript, provided Prettier is realigned. spatie-security is useful as a review prompt but spans application, database, server, and Git signing — parts of it (SSH config, unattended upgrades, firewall) sit outside the repo and outside the agent's reach, so it acts as a checklist rather than something the agent executes.

Migration path

Purely additive — nothing to migrate. There is a deliberate fork decision at the outset:

• Track upstream: --dev dependency, update on the normal dependency cadence, review the resulting markdown diff as a change. Lower ownership cost, less control.
• Fork-and-own: copy skills/ into .ai/skills/ (or the agent's directory), delete what conflicts with house style, add missing skills (testing, accessibility, infra), drop the Composer dependency. Full control, you own a per-quarter review pass.

Decide once. Deferring the decision is itself a decision for the half-fork state.

Compatibility

• Pin the version in composer.lock; commit both composer.json and composer.lock.
• Align prettier.config.js to four spaces / 120 / single quotes, or edit the skill's references/ copy to match yours. Don't leave the mismatch live.
• Verify scope gates are respected: spatie-javascript explicitly excludes PHP/Laravel; spatie-laravel-php excludes JS/TS. In a monorepo that's a feature, but it means PHP work and Vue work should run in separate sessions or name the skill explicitly on ambiguous files.
• State precedence in one line at the top of AGENTS.md: project conventions override any spatie-* skill; where the file is silent, follow the skill; Laravel framework conventions override both.

Sequencing

1. Spike (day 1, one repo). Install via Composer + Boost, select spatie-laravel-php and spatie-security only. Ask for a small conventional artifact: PostsController with index/store/destroy, a StorePostRequest, and routes.
2. Read, don't skim. Read the four SKILL.md summaries (~10 minutes) before judging output. Then check the generated code against them: tuple route notation, camelCase route names, kebab-case URLs, typed properties, explicit return types including void, constructor property promotion, early returns without else, config() not env(), array validation rules.
3. Verify the skill is live. Ask the agent: "Which skills do you have loaded, and quote the first rule from spatie-laravel-php." If it can't, the install targeted the wrong agent or the editor needs a restart. An agent that silently didn't load the skill looks identical to one ignoring it.
4. Stand up the generate-then-verify loop. Agent writes code, then vendor/bin/pint --test, vendor/bin/phpstan analyse, npm run lint && npx prettier --check .. The skill should reduce findings volume; it never replaces the checks.
5. Adopt the reviewer prompt. "Review this diff against the spatie-laravel-php skill and list only violations of its stated rules. Don't suggest refactors outside the skill." Paste at every PR for a consistent, quotable pass.
6. Promote the checkable rules to CI. env() outside config/, missing return types, controller naming — encode these as PHPStan rules or architecture tests so they are enforced rather than suggested, and let the skill carry the stylistic residue.
7. Formalize the update ritual. Pin version; run boost:update as its own commit; read the markdown diff before merging.
8. Roll out to additional repos on the same channel, with the same precedence line and the same Prettier alignment.
9. Reassess at one quarter: fork-or-track, and which additional skills to author in the SKILL.md + references/ shape.

Operational Impact

Maintenance

Low but non-zero, and the shape depends on the fork decision. Tracking upstream: a version bump plus a markdown review on your normal dependency cadence, budgeted as a policy review rather than a patch bump. Fork-and-own: roughly one review pass per quarter plus the cost of authoring skills for the gaps (testing, accessibility, CI, deployment, infra). Either way the artifact is a vendor/ directory that is wiped and repopulated on composer install — which is why the human-readable guidelines at spatie.be/guidelines must be linked from onboarding docs so conventions aren't locked inside a dependency.

Support

No vendor SLA; MIT community project from a well-regarded source (Spatie, Freek Van der Herten). Issues route to GitHub. The practical support surface is an internal diagnostic checklist for "the agent ignores the skill":

1. Is the skill file actually present under vendor/ or the agent's skills directory?
2. Did boost:install install for your agent, or a different one?
3. Did you restart the editor/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, and the fix is a more specific prompt naming the file and section.

Scaling

Per-repo install is trivial; consistency across repos is the real scaling cost. That requires a single distribution channel, a standard precedence line, identical Prettier config, and a shared update cadence — otherwise each repo's agent drifts independently. Two further ceilings: context budget (enable only the skills you use; name the specific references/ section you need rather than inviting a wholesale read) and scope coverage (four skills, with no testing/accessibility/infra equivalents — those are yours to write).

Failure modes

Ramp-up

Fast for individuals: ~15 minutes to a real adoption decision, ~10 minutes to read the four SKILL.md summaries, roughly one sprint to a validated pilot with CI gates identified. Team-level ramp is dominated by convention agreement, not tooling — commit format, branch naming, and JS formatting are the entrenched items, and spatie-version-control should be diffed against current practice before it is enabled anywhere. Onboarding hand-off: point new hires at the skill files in vendor/ and at spatie.be/guidelines for the prose version — written conventions inside the tool they already use beat a wiki page nobody opens.