Building Reusable AI Agent Skills with Laravel Boost: From Guidelines to Production

AI agents become more useful when they understand your application’s conventions.

Laravel Boost provides that context for coding agents. It supplies Laravel-aware tools, version-specific documentation, guidelines, and targeted skills. The result is more accurate code with less repeated explanation.

This tutorial shows how to build a reusable code-review skill. You will define it for Boost, load it only when needed, and reuse its instructions inside a production Laravel AI SDK agent.

The examples use a Laravel application running PHP 8.1 or later. Check the Laravel Boost documentation for the latest framework and package support.

Boost context: Guidelines vs. Skills

Laravel Boost provides two context layers.

Guidelines load upfront. They establish broad rules for the application and its installed packages. They can describe Laravel conventions, testing expectations, package versions, and general architectural preferences.

Skills load on demand. They contain focused instructions for a specific task or domain. Examples include Livewire development, Pest testing, Tailwind CSS, or a custom code-review workflow.

Context type	Loading model	Best use
Guidelines	Upfront	Broad Laravel and project conventions
Skills	On demand	Detailed patterns for a specific task
Project rules	When paths match	Application-specific decisions

This distinction keeps the agent’s context lean. A support-triage skill does not need to occupy the context window during a database migration. A code-review skill does not need to load while building a Blade view.

Smaller context also improves accuracy. The agent sees fewer unrelated instructions and more relevant examples. It can focus on the task instead of sorting through a large instruction document.

Boost also provides an MCP server and a documentation API. Agents can inspect routes, schemas, logs, configuration, and application versions. They can search Laravel documentation that matches the packages installed in your project.

Install Boost as a development dependency:

composer require laravel/boost --dev
php artisan boost:install

The installer generates the files required by your selected coding agents. You can refresh them later with:

php artisan boost:update

Define a reusable skill: Code review

Custom application skills live in .ai/skills. Create a directory for the skill and add a SKILL.md file:

.ai/
└── skills/
    └── code-review/
        └── SKILL.md

Use YAML frontmatter for the skill name and description. The description helps the coding agent decide when the skill applies.

---
name: code-review
description: Review Laravel PHP changes for security, correctness, performance, and test coverage.
---

# Code Review

## When to use this skill

Use this skill when reviewing a pull request, patch, diff, or proposed Laravel code change.

## Review order

1. Check authorization and tenant boundaries.
2. Check validation and input handling.
3. Check database queries and eager loading.
4. Check queue behavior and retry safety.
5. Check tests for success and failure paths.
6. Check logging and sensitive data exposure.

## Laravel conventions

- Prefer form requests for non-trivial validation.
- Use policies or gates for authorization.
- Use Eloquent relationships instead of repeated queries.
- Avoid putting business logic in controllers.
- Use queued jobs for slow external API calls.
- Add Pest tests for behavior that changes.

## Output format

Return findings grouped by severity:

- Critical
- High
- Medium
- Low
- Informational

Each finding must include the file, line or method, problem, and recommended fix.

Do not report style preferences as defects.

A good skill has one clear job. It should define when the agent should use it, what patterns matter, and what output you expect.

Keep examples short. Skills are not replacement documentation. They are high-signal instructions that point the agent toward the right implementation.

Register skills with Boost

Boost discovers application skills from .ai/skills/{skill-name}/SKILL.md.

After creating the file, update Boost:

php artisan boost:update

Boost will install the skill for the configured agents. The skill becomes available to agents such as Cursor, Claude Code, Codex, Gemini CLI, and GitHub Copilot, depending on your project setup.

You can also ship skills from a third-party package. Place them at:

resources/boost/skills/{skill-name}/SKILL.md

For example:

resources/boost/skills/
└── support-triage/
    └── SKILL.md

When a project installs the package and runs Boost installation, the package skill can be discovered and installed.

This file-based approach makes skills portable. You can version them with your package and improve them alongside your PHP code. Teams can also install shared skills with Boost’s skill command:

php artisan boost:add-skill owner/repository

Use the official Agent Skills format when publishing skills for reuse.

Load a skill conditionally at runtime

Boost skills are designed for coding agents. The Laravel AI SDK runs agents inside your application. These are related, but distinct, concerns.

A coding agent uses Boost to understand your codebase while developing it. A runtime agent uses the Laravel AI SDK to process requests, jobs, or events after deployment.

You can reuse the same skill content in both places. The simplest approach is an application-level registry that loads a skill only when a task requires it.

Create a small service:

<?php

namespace App\Ai;

class SkillRegistry
{
    public function register(string $name, string $path): void
    {
        config(["ai.skills.$name" => $path]);
    }

    public function load(string $name): string
    {
        $path = config("ai.skills.$name");

        abort_unless($path && is_file($path), 500, "Unknown AI skill: {$name}");

        $contents = file_get_contents($path);

        return preg_replace('/\A---.*?---\s*/s', '', $contents);
    }

    public function loadIf(string $name, bool $condition): string
    {
        return $condition ? $this->load($name) : '';
    }
}

Register the service in a service provider:

use App\Ai\SkillRegistry;

public function boot(SkillRegistry $skills): void
{
    $skills->register(
        'code-review',
        base_path('.ai/skills/code-review/SKILL.md'),
    );
}

This registry is an application abstraction. Boost itself discovers skills through their documented filesystem locations. The registry lets your deployed AI agent reuse the same instructions without loading every skill into every request.

Use the skill with the Laravel AI SDK

The Laravel AI SDK represents an agent as a PHP class. The agent can define instructions, tools, conversations, and structured output.

Create a review agent that accepts skill instructions:

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Prompting\Promptable;

class CodeReviewAgent implements Agent
{
    use Promptable;

    public function __construct(
        private readonly string $skill,
    ) {
    }

    public function instructions(): string
    {
        return <<<INSTRUCTIONS
You are a careful Laravel code reviewer.

Follow these review instructions:

{$this->skill}

Review only the supplied change. Do not invent project requirements.
Explain uncertainty when the available code is incomplete.
INSTRUCTIONS;
    }
}

Now invoke it from a controller or service:

use App\Ai\Agents\CodeReviewAgent;
use App\Ai\SkillRegistry;

$skill = app(SkillRegistry::class)->load('code-review');

$response = (new CodeReviewAgent($skill))
    ->prompt($request->string('diff')->toString());

return response()->json([
    'review' => (string) $response,
]);

The skill is loaded for this review only. A different request can load support-triage, or no skill at all.

For structured output, implement HasStructuredOutput and define a JSON schema. This is useful when findings must be stored, displayed in a dashboard, or sent to another service.

The Laravel AI SDK documentation covers agents, tools, streaming, structured responses, and provider configuration.

Add tools: Vector search and application data

Skills define behavior. Tools provide capabilities.

A support-triage agent might need to search product documentation before classifying a ticket. Give it a tool that searches your knowledge base instead of placing the entire knowledge base in the prompt.

The Laravel AI SDK supports tools implemented as PHP classes. A tool defines its description, input schema, and handler. The handler can call an internal API, query Eloquent, or perform vector search.

For database-backed retrieval, the SDK provides the SimilaritySearch tool. You can also implement a custom tool around vector queries such as whereVectorSimilarTo. PostgreSQL with pgvector and MongoDB are common options for storing embeddings.

A simplified agent configuration looks like this:

use Laravel\Ai\Tools\SimilaritySearch;

public function tools(): iterable
{
    return [
        SimilaritySearch::usingModel(KnowledgeArticle::class),
    ];
}

The exact model and embedding configuration depend on your database setup. The important boundary remains the same. The agent decides when it needs context, and the tool retrieves only the relevant records.

This creates a practical retrieval-augmented generation flow:

1. A customer submits a question.
2. The support agent loads the support-triage skill.
3. The model calls vector search when documentation is needed.
4. Laravel returns the closest knowledge-base entries.
5. The agent classifies the ticket and proposes a response.

The agent does not need every article in its initial context. It receives focused results through a controlled tool.

Fit the agent into routes and queues

Use a route for short, interactive requests. Validate the input before invoking the model.

use App\Ai\Agents\CodeReviewAgent;
use App\Ai\SkillRegistry;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/api/code-reviews', function (
    Request $request,
    SkillRegistry $skills,
) {
    $data = $request->validate([
        'diff' => ['required', 'string', 'max:100000'],
    ]);

    $review = (new CodeReviewAgent(
        $skills->load('code-review'),
    ))->prompt($data['diff']);

    return response()->json([
        'review' => (string) $review,
    ]);
});

This also demonstrates how Laravel helps you build REST API with PHP. Routing, validation, authentication, queues, and responses stay in familiar application code.

Long reviews should run in a queue. A queued job prevents a large diff or external tool call from blocking the HTTP request.

<?php

namespace App\Jobs;

use App\Ai\Agents\CodeReviewAgent;
use App\Ai\SkillRegistry;
use Illuminate\Contracts\Queue\ShouldQueue;

class ReviewPullRequest implements ShouldQueue
{
    public function __construct(
        public readonly int $pullRequestId,
    ) {
    }

    public function handle(SkillRegistry $skills): void
    {
        $pullRequest = PullRequest::findOrFail($this->pullRequestId);

        $response = (new CodeReviewAgent(
            $skills->load('code-review'),
        ))->prompt($pullRequest->diff);

        $pullRequest->update([
            'review' => (string) $response,
            'reviewed_at' => now(),
        ]);
    }
}

Dispatch it after receiving a webhook:

ReviewPullRequest::dispatch($pullRequest->id);

Use retry limits and idempotent updates. Record provider failures without logging sensitive prompts or customer data. Add tests around skill selection, tool permissions, and job behavior.

Keep skills accurate in production

Treat skills like code.

Review them when Laravel or an ecosystem package changes. Remove instructions that no longer match your architecture. Keep version-specific behavior explicit when a package has multiple supported versions.

Use Boost’s documentation search during development. Its documentation API contains Laravel ecosystem knowledge tailored to installed packages and versions. The AI-assisted development guide explains how Boost combines this documentation with MCP tools and guidelines.

Your broader rules should stay in guidelines or project rules. Your task-specific instructions should stay in skills. This separation makes both easier to maintain.

Laravel Boost is one of the more useful additions to the modern set of PHP developer tools because it connects AI assistance to real application structure. Combined with the Laravel AI SDK, the same discipline extends from code generation to production workflows.

As agents become part of everyday Laravel applications, reusable skills will give teams a clear way to share context, control behavior, and ship reliable AI features without carrying the entire codebase into every prompt.