DEV Community

Cover image for How Laravel AI Skills Work
Sumeet Shroff
Sumeet Shroff

Posted on

How Laravel AI Skills Work

#ai #webdev #programming #tutorial

How Laravel AI Skills Work

If you have already installed Laravel Boost and run boost:install, you have noticed that a set of markdown files appeared in your project under .boost/. What you may not have explored yet is the Skills system — the mechanism that lets AI agents load domain-specific knowledge on demand rather than loading everything into context on every prompt. This post walks through how Skills work mechanically, how to install and write them, and where they differ from Guidelines.

Prerequisites and Version Requirements

  • Laravel 10, 11, 12, or 13
  • PHP 8.1 or higher (PHP 8.4 is required only for the separate laravel/ai SDK — not for Boost itself)
  • Laravel Boost v2.0 or later (composer require laravel/boost --dev)
  • An MCP-capable AI agent: Claude Code, Cursor, Windsurf, GitHub Copilot, or Codex CLI

Boost v2.0 (released January 26, 2026) introduced the Skills system. If you are on v1.x, update first.

composer update laravel/boost --dev
php artisan boost:install
Enter fullscreen mode Exit fullscreen mode

Running boost:install again on an existing project is safe — it merges without overwriting existing customisations.

Guidelines vs Skills: The Core Distinction

Before touching Skills, the distinction between Guidelines and Skills matters:

Guidelines Skills
When loaded Every agent session On demand only
Purpose Core project conventions Domain-specific knowledge
Example Coding style, auth patterns Livewire v4 component syntax
Risk of overuse Low (small, always relevant) Context bloat if always on

Guidelines live in .boost/guidelines/ and are loaded by the MCP server on every connection. Skills live in .boost/skills/ and are loaded only when the agent needs them — either by explicit request or by agent reasoning.

A common mistake is putting everything into Guidelines. If your project uses Livewire, Pest, Inertia, Tailwind, and Filament, loading all their conventions on every prompt adds thousands of tokens to every request even when the task has nothing to do with UI.

How Skills Are Installed

Auto-detection at boost:install

When you run php artisan boost:install, Boost inspects your composer.json and package.json. If it detects a known package, it downloads and installs the matching skill automatically. For example:

  • livewire/livewire detected → Livewire skill installed
  • pestphp/pest detected → Pest skill installed
  • inertiajs/inertia-laravel detected → Inertia skill installed

This means most projects get the right skills without manual work.

Adding Skills Manually

Skills are fetched from GitHub repositories. The public directory at skills.laravel.cloud lists 100+ community and official skills. To add one:

# From the public directory (shorthand)
php artisan boost:add-skill laravel/livewire-skill

# From any GitHub URL
php artisan boost:add-skill https://github.com/owner/repo

# From a local path (useful when writing your own)
php artisan boost:add-skill ./my-custom-skill
Enter fullscreen mode Exit fullscreen mode

Since Boost v2.4.0, the boost:add-skill command runs a security audit step before installing any remotely fetched skill. It checks the skill's manifest and content against known patterns before writing files to your project.

After installing, a new markdown file appears in .boost/skills/. The agent reads this file when it determines the skill is relevant to the current task.

Anatomy of a Skill File

A skill is a single markdown file with a structured format. Here is a stripped-down example of what the Livewire skill looks like conceptually:

---
name: Livewire v4
version: 1.0.0
triggers:
  - livewire
  - wire:model
  - Volt
  - AlpineJS integration
---

## Livewire v4 Component Syntax

Use class-based components with the `#[Layout]` attribute instead of `$layout` property.
Enter fullscreen mode Exit fullscreen mode


php

[Layout('layouts.app')]

class Dashboard extends Component
{
public string $search = '';

public function render(): View
{
    return view('livewire.dashboard');
}
Enter fullscreen mode Exit fullscreen mode

}


## Common Mistakes

- Do NOT use `$this->emit()` — it was removed in v3. Use `$this->dispatch()` instead.
- Do NOT use the v2 `mount()` lifecycle hook pattern for dependency injection.
Enter fullscreen mode Exit fullscreen mode


markdown

The frontmatter triggers array tells the MCP server which keywords in a task prompt should cause this skill to be loaded. When an agent prompt contains "wire:model" or "Volt", the Livewire skill is pulled into context automatically.

Writing a Custom Skill

Any project-specific domain can become a skill. Suppose your Laravel application has a custom multi-tenant architecture where every query must scope to tenant_id. Without a skill, agents will sometimes generate queries that miss the scope. With a skill, the convention is explicit.

Create .boost/skills/multi-tenant.md:

---
name: Multi-Tenant Scoping
version: 1.0.0
triggers:
  - tenant
  - TenantScope
  - ScopedByTenant
  - team
---

## Required: Always Scope Queries to Current Tenant

Every Eloquent model that stores tenant data MUST use the `ScopedByTenant` trait:
Enter fullscreen mode Exit fullscreen mode


php
use App\Traits\ScopedByTenant;

class Invoice extends Model
{
use ScopedByTenant;
}


The trait adds a global scope that appends `WHERE tenant_id = ?` using `auth()->user()->tenant_id`.

Never write raw `where('tenant_id', ...)` clauses — always rely on the trait.

## Migrations

Every tenant-scoped table must include:
Enter fullscreen mode Exit fullscreen mode


php
$table->foreignId('tenant_id')->constrained()->cascadeOnDelete();

Enter fullscreen mode Exit fullscreen mode


php

Push this to a GitHub repo and register it with:

php artisan boost:add-skill https://github.com/your-org/multi-tenant-skill
Enter fullscreen mode Exit fullscreen mode

Now any agent working on invoice queries will have the scoping rule in context.

How the MCP Server Loads Skills at Runtime

The Laravel Boost MCP server exposes a set of tools to AI agents. After Skills are installed, the search-docs tool and the agent's context window include skill content when the agent's current task matches the skill's triggers.

The remaining core MCP tools in Boost v2.3.0+ are:

  • application-info — PHP/Laravel version, installed packages, Eloquent models
  • browser-logs — browser console errors and logs
  • database-connections — list configured DB connections
  • database-query — execute SQL queries on your app DB
  • database-schema — inspect table structure
  • get-absolute-url — resolve named routes to full URLs
  • last-error — read the most recent application error
  • read-log-entries — parse laravel.log in PSR-3 and JSON formats
  • search-docs — search versioned Laravel ecosystem docs (17,000+ pieces of knowledge)

Note: list-artisan-commands, list-routes, tinker, get-config, list-available-env-vars, and list-available-config-keys were removed as MCP tools in v2.3.0. Agents needing this information should run CLI equivalents directly (php artisan list, php artisan route:list, php artisan config:show).

Verification: Confirming a Skill Is Active

After installing a skill, verify it is being loaded by the MCP server:

# List installed skills
ls .boost/skills/

# Inspect a skill's triggers
head -15 .boost/skills/livewire.md
Enter fullscreen mode Exit fullscreen mode

In your AI agent, prompt it with a task that should trigger the skill:

Create a Livewire component for a searchable product list.
Enter fullscreen mode Exit fullscreen mode

If the skill is active, the agent will generate Livewire v4 syntax. Without the skill, agents that are not trained on v4 may generate v2 syntax using the removed $this->emit() API — a silent but breaking difference.

For custom skills you author, test by checking that the agent's generated code respects your documented conventions before merging any AI-assisted PR.

Common Mistakes and Limitations

1. Not running boost:install before adding skills.
The boost:install command sets up the Guidelines infrastructure and the .boost/ directory that skills extend. Running boost:add-skill on a project without this setup will fail.

2. Putting everything into Guidelines.
If you have Guidelines files that cover Livewire, Tailwind, Pest, Inertia, and your custom architecture all at once, agents load all of that on every request — even for a simple queue job task. Move domain-specific content to Skills.

3. Expecting Skills to work without an MCP-capable agent.
Boost and Skills require the AI agent to support MCP. If your team uses a tool without MCP support, the Skills system provides no benefit — the markdown files sit unused.

4. Installing community skills without review.
The skills.laravel.cloud directory is community-contributed. The v2.4.0 security audit step reduces risk, but always read the skill content before installing it in a project that handles sensitive data. A malicious skill could instruct the agent to generate code that bypasses authorization.

5. Assuming Boost is production-safe.
Boost is a --dev dependency. The database-query MCP tool executes arbitrary SQL against your configured database. Never install Boost in production or on a server reachable from untrusted networks.

Tradeoffs: Skills vs Embedding Context Directly

Some teams bypass the Skills system by including conventions in their agent's system prompt or in a project-level CLAUDE.md / .cursorrules file. This works but has limits:

  • Hard-coded system prompts cannot be updated per project without agent reconfiguration
  • .cursorrules / CLAUDE.md files load regardless of task relevance
  • Skills can be versioned, shared across teams via GitHub, and updated independently of your codebase

For solo developers, the difference is minimal. For teams where multiple developers use the same AI agent configuration, centralising conventions in versioned Skills that live in the repo is the more maintainable approach.

Further Reading

The Skills system is one layer of the broader Laravel Boost and AI ecosystem. For the full picture — including the Laravel AI SDK, Prism PHP, LarAgent, MCP tool reference, and version compatibility matrix — see the parent guide: Laravel Boost and AI Skills: Agentic Development for Laravel.

If you need Laravel development in Mumbai, Mumbai Web Designer builds production-grade Laravel applications.

Top comments (0)