Creare un agente personalizzato per Boost

Perché serve un agente personalizzato

Laravel Boost supporta di default i principali strumenti di AI coding come Claude Code, Cursor, Codex, GitHub Copilot (VS Code). Per adattarsi a strumenti interni, agenti AI emergenti o flussi di lavoro proprietari, però, devi implementare un agente personalizzato tramite l’estensione di Boost. Casi in cui un agente custom è utile:

Stai usando un IDE o uno strumento AI non supportato da Boost
Vuoi integrare Boost in un flusso di sviluppo interno o in una pipeline CI/CD proprietaria
L’agente richiede un formato di file di configurazione o una procedura di installazione specifica

Architettura di estensione di Boost

Classe base Agent

Tutti gli agenti estendono Laravel\Boost\Install\Agents\Agent. Questa classe astratta fornisce:

Rilevamento dell’agente (a livello di sistema e di progetto)
Installazione di server MCP (file-based e shell-command-based)
Hook di trasformazione delle linee guida (transformGuidelines)

Ci sono due metodi astratti obbligatori.

Metodo	Descrizione
`name()`	Identificatore interno dell’agente (es. `claude_code`)
`displayName()`	Nome mostrato in fase di installazione (es. `Claude Code`)
`systemDetectionConfig(Platform $platform)`	Configurazione di rilevamento dell’installazione a livello di sistema
`projectDetectionConfig()`	Configurazione di rilevamento dell’installazione a livello di progetto

I tre contract

Per abilitare selettivamente le funzionalità di Boost, implementi i contract che servono.

Contract	Ruolo
`SupportsGuidelines`	Path in cui scrivere il file di linee guida AI e trasformazione
`SupportsMcp`	Installazione della configurazione di server MCP
`SupportsSkills`	Path di installazione degli Agent Skills

Tutti e tre i contract sono opzionali. Puoi implementare solo le linee guida senza MCP, ad esempio.

Contract SupportsGuidelines

interface SupportsGuidelines
{
    // path del file in cui scrivere le linee guida AI
    public function guidelinesPath(): string;

    // se il file richiede un frontmatter
    public function frontmatter(): bool;

    // post-elaborazione del Markdown generato
    public function transformGuidelines(string $markdown): string;
}

guidelinesPath() restituisce il path del file in cui scrivere le linee guida generate. Per Claude Code è CLAUDE.md, per Cursor .cursor/rules/laravel-boost.mdc, adattandosi al formato che l’agente carica. transformGuidelines() è un hook per elaborare il Markdown dopo la generazione. Puoi aggiungere un header specifico dell’agente o convertirlo in un formato speciale. Il default nella classe base restituisce la stringa così com’è.

Contract SupportsMcp

interface SupportsMcp
{
    // se usare path assoluti nei comandi MCP
    public function useAbsolutePathForMcp(): bool;

    // restituisce il path dell'eseguibile PHP
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // restituisce il path di artisan
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // installa la configurazione del server MCP
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // installa la configurazione del server MCP tramite HTTP
    public function installHttpMcp(string $key, string $url): bool;
}

La classe base Agent ha già implementazioni di default per installMcp() e installHttpMcp(): nella maggior parte dei casi basta fare override di mcpInstallationStrategy() e mcpConfigPath(). Ci sono due strategie di installazione.

`McpInstallationStrategy`	Comportamento
`FILE`	Scrive la configurazione in un file JSON/TOML (default)
`SHELL`	Esegue un comando shell per registrare l’MCP
`NONE`	Salta l’installazione MCP

Contract SupportsSkills

interface SupportsSkills
{
    // path della directory in cui scrivere gli Agent Skills
    public function skillsPath(): string;
}

Restituisce il path della directory di skills letta dall’agente. Per Claude Code è .claude/skills, per Cursor .cursor/skills, e così via.

Creare un agente personalizzato

Implementiamo concretamente una classe di agente custom. Come esempio, un ipotetico “MyAgent” integrato in un flusso CI/CD proprietario.

Creare la classe dell'agente

Crea app/Boost/MyAgent.php.

<?php

declare(strict_types=1);

namespace App\Boost;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Contracts\SupportsMcp;
use Laravel\Boost\Contracts\SupportsSkills;
use Laravel\Boost\Install\Agents\Agent;
use Laravel\Boost\Install\Enums\McpInstallationStrategy;
use Laravel\Boost\Install\Enums\Platform;

class MyAgent extends Agent implements SupportsGuidelines, SupportsMcp, SupportsSkills
{
    public function name(): string
    {
        return 'my_agent';
    }

    public function displayName(): string
    {
        return 'MyAgent';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        return match ($platform) {
            Platform::Darwin, Platform::Linux => [
                'command' => 'command -v myagent',
            ],
            Platform::Windows => [
                'command' => 'cmd /c where myagent 2>nul',
            ],
        };
    }

    public function projectDetectionConfig(): array
    {
        return [
            'files' => ['.myagent.json'],
        ];
    }

    // --- SupportsGuidelines ---

    public function guidelinesPath(): string
    {
        return 'MYAGENT.md';
    }

    // frontmatter() usa il default della classe base Agent (false)
    // anche transformGuidelines() usa il default (restituisce la stringa)

    // --- SupportsMcp ---

    // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
    // installMcp(), installHttpMcp() sono già implementati nella classe base

    public function mcpInstallationStrategy(): McpInstallationStrategy
    {
        return McpInstallationStrategy::FILE;
    }

    public function mcpConfigPath(): string
    {
        return '.myagent.json';
    }

    // --- SupportsSkills ---

    public function skillsPath(): string
    {
        return '.myagent/skills';
    }
}

systemDetectionConfig() e projectDetectionConfig() servono a Boost per rilevare automaticamente l’agente a livello di sistema e di progetto. All’esecuzione di boost:install l’agente compare fra i candidati.

Registrare l'agente

Nel metodo boot di App\Providers\AppServiceProvider registri l’agente custom.

<?php

namespace App\Providers;

use App\Boost\MyAgent;
use Illuminate\Support\ServiceProvider;
use Laravel\Boost\Boost;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Boost::registerAgent('my_agent', MyAgent::class);
    }
}

Dopo la registrazione, con php artisan boost:install MyAgent compare tra le scelte.

Verifica del funzionamento

php artisan boost:install

Nella schermata di selezione dell’agente MyAgent viene mostrato. Selezionandolo vengono generati MYAGENT.md, .myagent.json e .myagent/skills/.

Personalizzare le linee guida

Impostare guidelinesPath

Ogni agente carica il file delle linee guida da un punto diverso.

// per generare un unico file
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}

Renderlo sovrascrivibile da file di configurazione aumenta la flessibilità.

public function guidelinesPath(): string
{
    return config('boost.agents.my_agent.guidelines_path', 'MYAGENT.md');
}

Agenti che richiedono frontmatter

Per formati che richiedono un frontmatter (come i .cursor/rules/*.mdc di Cursor) restituisci true da frontmatter().

public function frontmatter(): bool
{
    return true;
}

Post-elaborazione delle linee guida

Con transformGuidelines() puoi elaborare il Markdown dopo la generazione.

public function transformGuidelines(string $markdown): string
{
    // aggiunge un header specifico dell'agente
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}

Aggiungere linee guida AI personalizzate

Per aggiungere regole specifiche del progetto alle linee guida di Boost, metti file Blade nella directory .ai/guidelines/.

.ai/
└── guidelines/
    ├── my-domain-rules.blade.php
    └── coding-standards.blade.php

Esempio di file:

## Regole specifiche del progetto

In questo progetto segui queste convenzioni:

- Colloca sempre i modelli nel namespace `App\Models\`
- Crea tutti gli endpoint API sotto `App\Http\Controllers\Api\`
- Racchiudi le transazioni DB con `DB::transaction()` all'interno delle service class

@verbatim
<code-snippet name="Esempio di transazione in una service class" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim

Eseguendo boost:install queste linee guida vengono unite automaticamente a quelle integrate in Boost.

Override delle linee guida integrate

Se metti un file personalizzato nello stesso path di una linea guida integrata di Boost, la tua ha la priorità.

# override della "Inertia React v2 Form Guidance" di Boost
.ai/guidelines/inertia-react/2/forms.blade.php

Aggiungere skills personalizzati

Creare SKILL.md

Definisci le skill in .ai/skills/{nome-skill}/SKILL.md.

.ai/
└── skills/
    └── creating-invoices/
        └── SKILL.md

SKILL.md è composto da un frontmatter YAML e da istruzioni Markdown.

---
name: creating-invoices
description: Skill da usare quando implementi la creazione, l'aggiornamento e l'invio di fatture (Invoice).
---

# Skill di creazione fatture

## Quando usare questa skill

Quando implementi il modello Invoice, la generazione PDF e l'invio email di una fattura.

## Struttura dei file

- `app/Models/Invoice.php` — modello Invoice
- `app/Services/InvoiceService.php` — logica di business
- `app/Jobs/SendInvoiceEmail.php` — job di invio email

## Pattern di implementazione

### Creare una fattura

```php
// $items è l'array passato dal controller o da un altro service
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);

Generare il PDF della fattura

Genera il PDF con barryvdh/laravel-dompdf:

use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Support\Facades\Storage;

$pdf = Pdf::loadView('invoices.pdf', ['invoice' => $invoice]);
Storage::put("invoices/{$invoice->id}.pdf", $pdf->output());

Le skill sono progettate per essere “caricate solo quando servono”. Metti in linee guida le informazioni sempre necessarie e nelle skill i pattern dettagliati specifici del task: ottimizzi l’uso della context dell’AI.

Override delle skill integrate

Creando una skill custom con lo stesso nome di una skill integrata di Boost, la sovrascrivi.

# personalizza la skill livewire-development
.ai/skills/livewire-development/SKILL.md

Aggiungere il supporto Boost a pacchetti di terze parti

Per aggiungere il supporto Boost al tuo pacchetto, metti i file di configurazione nella directory resources/boost/ del pacchetto.

Aggiungere linee guida

resources/
└── boost/
    └── guidelines/
        └── core.blade.php

## MyPackage

Questo pacchetto fornisce [panoramica delle funzionalità].

### Uso di base

@verbatim
<code-snippet name="Inizializzazione di MyPackage" lang="php">
$result = MyPackage::create([
    'option' => 'value',
]);
</code-snippet>
@endverbatim

Aggiungere skill

resources/
└── boost/
    └── skills/
        └── mypackage-development/
            └── SKILL.md

---
name: mypackage-development
description: Skill per implementare funzionalità con MyPackage.
---

# MyPackage Development

## Quando usare questa skill
Quando implementi funzionalità che usano MyPackage.

## Funzionalità principali

- Funzionalità 1: ...
- Funzionalità 2: ...

Quando gli utenti del pacchetto eseguono php artisan boost:install, queste linee guida e skill vengono rilevate automaticamente e proposte per l’installazione.

Esempio pratico: agente custom per pipeline CI/CD

Esempio completo di “PipelineAgent”, un agente virtuale integrato in una pipeline CI/CD interna. L’agente supporta solo le linee guida, non MCP e non skill.

<?php

declare(strict_types=1);

namespace App\Boost;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Install\Agents\Agent;
use Laravel\Boost\Install\Enums\Platform;

class PipelineAgent extends Agent implements SupportsGuidelines
{
    public function name(): string
    {
        return 'pipeline_agent';
    }

    public function displayName(): string
    {
        return 'Pipeline Agent (CI/CD)';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        // rileva la presenza tramite variabili d'ambiente di CI
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // rileva tramite un file di configurazione nella root del progetto
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // path delle regole che l'agente CI/CD legge
        return '.pipeline/CODING_GUIDELINES.md';
    }

    public function frontmatter(): bool
    {
        return false;
    }

    public function transformGuidelines(string $markdown): string
    {
        // aggiunge un header di metadati per la pipeline
        $timestamp = now()->toIso8601String();

        return "<!-- Generated by Laravel Boost at {$timestamp} -->\n\n{$markdown}";
    }
}

Registrazione in AppServiceProvider:

use App\Boost\PipelineAgent;
use Laravel\Boost\Boost;

public function boot(): void
{
    Boost::registerAgent('pipeline_agent', PipelineAgent::class);
}

In ambiente CI puoi generare solo le linee guida con:

php artisan boost:install --agent=pipeline_agent

Link di riferimento

ClaudeCode.php — esempio ufficiale

Codice sorgente completo dell’agente ClaudeCode incluso in Boost.

Agent Skills

Specifica del formato SKILL.md e best practice.

Laravel Boost Custom Agent for GitHub Copilot CLI

Esempio di pacchetto pubblicato che supporta sia Copilot CLI sia Testbench.

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

Esempio di pacchetto pubblicato per il plugin GitHub Copilot di PhpStorm.

​Perché serve un agente personalizzato

​Architettura di estensione di Boost

​Classe base Agent

​I tre contract

​Contract SupportsGuidelines

​Contract SupportsMcp

​Contract SupportsSkills

​Creare un agente personalizzato

​Personalizzare le linee guida

​Impostare guidelinesPath

​Agenti che richiedono frontmatter

​Post-elaborazione delle linee guida

​Aggiungere linee guida AI personalizzate

​Override delle linee guida integrate

​Aggiungere skills personalizzati

​Creare SKILL.md

​Generare il PDF della fattura

​Override delle skill integrate

​Aggiungere il supporto Boost a pacchetti di terze parti

​Aggiungere linee guida

​Aggiungere skill

​Esempio pratico: agente custom per pipeline CI/CD

​Link di riferimento

ClaudeCode.php — esempio ufficiale

Agent Skills

Laravel Boost Custom Agent for GitHub Copilot CLI

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

Perché serve un agente personalizzato

Architettura di estensione di Boost

Classe base Agent

I tre contract

Contract SupportsGuidelines

Contract SupportsMcp

Contract SupportsSkills

Creare un agente personalizzato

Personalizzare le linee guida

Impostare guidelinesPath

Agenti che richiedono frontmatter

Post-elaborazione delle linee guida

Aggiungere linee guida AI personalizzate

Override delle linee guida integrate

Aggiungere skills personalizzati

Creare SKILL.md

Generare il PDF della fattura

Override delle skill integrate

Aggiungere il supporto Boost a pacchetti di terze parti

Aggiungere linee guida

Aggiungere skill

Esempio pratico: agente custom per pipeline CI/CD

Link di riferimento