Crear un agente personalizado de Boost

Por qué necesitas un agente personalizado

Laravel Boost soporta de forma predeterminada las principales herramientas de codificación con IA, como Claude Code, Cursor, Codex y GitHub Copilot (VS Code). Sin embargo, si quieres dar soporte a herramientas internas, agentes de IA emergentes o flujos de trabajo propios, tendrás que implementar un agente personalizado utilizando el mecanismo de extensión de Boost. Situaciones en las que resulta útil un agente personalizado:

Usas un IDE o herramienta de IA que Boost no soporta.
Quieres integrar Boost en un flujo de desarrollo interno o en un pipeline de CI/CD propio.
El agente tiene un formato de archivo de configuración o unos pasos de instalación específicos.

Arquitectura de extensión de Boost

Clase base Agent

Todos los agentes extienden Laravel\Boost\Install\Agents\Agent. Esta clase abstracta ofrece:

Detección del agente (a nivel de sistema y a nivel de proyecto).
Instalación del servidor MCP (basada en archivos o en comandos de shell).
Hook de transformación de guidelines (transformGuidelines).

Los métodos abstractos que hay que implementar son dos:

Método	Descripción
`name()`	Identificador interno del agente (por ejemplo, `claude_code`).
`displayName()`	Nombre que se muestra durante la instalación (por ejemplo, `Claude Code`).
`systemDetectionConfig(Platform $platform)`	Configuración para detectar la instalación a nivel de sistema.
`projectDetectionConfig()`	Configuración para detectar la instalación a nivel de proyecto.

Los tres contratos

Para habilitar las funciones de Boost de manera selectiva, implementa solo los contratos que necesites.

Contrato	Función
`SupportsGuidelines`	Ruta de salida y proceso de transformación del archivo de guidelines de IA.
`SupportsMcp`	Instalación de la configuración del servidor MCP.
`SupportsSkills`	Ruta de instalación de los Agent Skills.

Los tres contratos son opcionales. También puedes implementar solo el soporte de guidelines sin MCP, por ejemplo.

Contrato SupportsGuidelines

interface SupportsGuidelines
{
    // Ruta del archivo donde se escriben las guidelines de IA
    public function guidelinesPath(): string;

    // Si el archivo de guidelines necesita frontmatter
    public function frontmatter(): bool;

    // Post-procesamiento del Markdown de las guidelines generadas
    public function transformGuidelines(string $markdown): string;
}

guidelinesPath() devuelve la ruta del archivo donde se escribirán las guidelines generadas. Se ajusta al formato que el agente carga: CLAUDE.md para Claude Code, .cursor/rules/laravel-boost.mdc para Cursor, etc. transformGuidelines() es un hook para procesar el Markdown ya generado. Puedes añadir cabeceras propias del agente o convertirlo a un formato especial. La implementación por defecto en la clase base Agent devuelve la cadena sin cambios.

Contrato SupportsMcp

interface SupportsMcp
{
    // Usar rutas absolutas en los comandos MCP
    public function useAbsolutePathForMcp(): bool;

    // Devuelve la ruta del ejecutable de PHP
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // Devuelve la ruta de artisan
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // Instala la configuración del servidor MCP
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // Instala la configuración de un servidor MCP a través de HTTP
    public function installHttpMcp(string $key, string $url): bool;
}

Como la clase base Agent ya ofrece implementaciones por defecto de installMcp() e installHttpMcp(), en la mayoría de los casos basta con sobrescribir mcpInstallationStrategy() y mcpConfigPath(). Hay dos estrategias de instalación:

`McpInstallationStrategy`	Comportamiento
`FILE`	Escribe la configuración en un archivo JSON/TOML (por defecto).
`SHELL`	Ejecuta un comando de shell para registrar el MCP.
`NONE`	Omite la instalación del MCP.

Contrato SupportsSkills

interface SupportsSkills
{
    // Ruta del directorio donde se escriben los Agent Skills
    public function skillsPath(): string;
}

Devuelve la ruta del directorio de skills que carga el agente. Se ajusta a lo que espera el agente: .claude/skills para Claude Code, .cursor/skills para Cursor, etc.

Crear un agente personalizado

Vamos a implementar una clase de agente propia. Usaremos como ejemplo un agente ficticio llamado «MyAgent» integrado en un flujo de CI/CD propio.

Crea la clase del 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 el valor por defecto de la clase base Agent (false)
    // transformGuidelines() también usa el valor por defecto (devuelve el texto tal cual)

    // --- SupportsMcp ---

    // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
    // installMcp() e installHttpMcp() los implementa la clase base Agent

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

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

    // --- SupportsSkills ---

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

Boost usa systemDetectionConfig() y projectDetectionConfig() para detectar el agente en el sistema y en el proyecto. Al ejecutar boost:install, mostrará el agente como candidato automáticamente.

Registra el agente

Registra el agente personalizado en el método boot de App\Providers\AppServiceProvider.

<?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);
    }
}

Después del registro, php artisan boost:install mostrará MyAgent entre las opciones.

Comprueba el funcionamiento

php artisan boost:install

En la pantalla de selección de agente aparecerá MyAgent. Al seleccionarlo, se generarán MYAGENT.md, .myagent.json y .myagent/skills/.

Personalizar las guidelines

Configurar guidelinesPath

Cada agente lee las guidelines desde una ubicación diferente.

// Si quieres emitirlas en un único archivo
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}

Si permites sobrescribirlo desde el archivo de configuración, ganarás flexibilidad.

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

Agentes que requieren frontmatter

Para formatos que requieren frontmatter, como .cursor/rules/*.mdc de Cursor, devuelve true desde frontmatter().

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

Post-procesamiento de las guidelines

Puedes procesar el Markdown generado con transformGuidelines().

public function transformGuidelines(string $markdown): string
{
    // Añadir una cabecera propia del agente
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}

Añadir guidelines personalizadas de IA

Para añadir reglas específicas del proyecto a las guidelines de Boost, coloca archivos Blade en el directorio .ai/guidelines/.

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

Ejemplo de archivo:

## Reglas específicas del proyecto

En este proyecto se deben seguir estas convenciones:

- Los modelos siempre deben colocarse en el namespace `App\Models\`.
- Todos los endpoints de la API se crean bajo `App\Http\Controllers\Api\`.
- Las transacciones de BD se aíslan dentro de clases de servicio usando `DB::transaction()`.

@verbatim
<code-snippet name="Ejemplo de transacción en una clase de servicio" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim

Cuando ejecutes boost:install, esta guideline se combinará automáticamente con las guidelines integradas de Boost y se generará el archivo resultante.

Sobrescribir las guidelines integradas

Si colocas un archivo personalizado en la misma ruta que una guideline integrada de Boost, esta última tendrá prioridad.

# Sobrescribe la "Inertia React v2 Form Guidance" de Boost
.ai/guidelines/inertia-react/2/forms.blade.php

Añadir skills personalizadas

Crear SKILL.md

Define la skill en .ai/skills/{nombre-de-la-skill}/SKILL.md.

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

SKILL.md se compone de un frontmatter YAML y de las instrucciones en Markdown.

---
name: creating-invoices
description: Skill que se utiliza al implementar el procesamiento de creación, actualización y envío de facturas (Invoice).
---

# Skill de creación de facturas

## Cuándo usar esta skill

Cuando se implementa la creación del modelo de factura, la generación del PDF de la factura y el envío por correo.

## Estructura de archivos

- `app/Models/Invoice.php` — modelo Invoice
- `app/Services/InvoiceService.php` — lógica de negocio
- `app/Jobs/SendInvoiceEmail.php` — job de envío por correo

## Patrones de implementación

### Crear una factura

```php
// $items es un array pasado desde el controlador u otro servicio
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);

Generar el PDF de la factura

El PDF se genera 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());

Las skills están diseñadas para «cargarse solo cuando son necesarias». Al colocar la información imprescindible en las guidelines y los patrones detallados específicos de cada tarea en las skills, optimizas el uso del contexto de la IA.

Sobrescribir skills integradas

Si creas una skill personalizada con el mismo nombre que una integrada de Boost, la sobrescribirás.

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

Añadir soporte de Boost a paquetes de terceros

Para añadir soporte de Boost a un paquete propio, coloca los archivos de configuración en el directorio resources/boost/ del paquete.

Añadir guidelines

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

## MyPackage

Este paquete ofrece [resumen de la funcionalidad].

### Uso básico

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

Añadir skills

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

---
name: mypackage-development
description: Skill para implementar funcionalidades de MyPackage.
---

# MyPackage Development

## Cuándo usar esta skill
Se utiliza al implementar funcionalidades con MyPackage.

## Funciones principales

- Función 1: ...
- Función 2: ...

Cuando el usuario del paquete ejecute php artisan boost:install, estas guidelines y skills se detectarán automáticamente y aparecerán como candidatas para la instalación.

Ejemplo práctico: agente personalizado para un agente de CI/CD propio

Ejemplo completo de un agente ficticio llamado «PipelineAgent» integrado en el pipeline de CI/CD interno. Este agente solo soporta guidelines; no soporta MCP ni skills.

<?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
    {
        // Detecta su presencia mediante una variable de entorno de CI
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // Detecta con un archivo de configuración en la raíz del proyecto
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // Ruta de las convenciones que carga el agente de CI/CD
        return '.pipeline/CODING_GUIDELINES.md';
    }

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

    public function transformGuidelines(string $markdown): string
    {
        // Añade una cabecera de metadatos para el pipeline
        $timestamp = now()->toIso8601String();

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

Regístralo en AppServiceProvider:

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

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

En el entorno de CI puedes generar solo las guidelines con el siguiente comando:

php artisan boost:install --agent=pipeline_agent

Enlaces de referencia

ClaudeCode.php — ejemplo de implementación oficial

Puedes revisar en el código fuente la implementación completa del agente ClaudeCode incluido con Boost.

Agent Skills

Consulta la especificación del formato de SKILL.md y las buenas prácticas.

Laravel Boost Custom Agent for GitHub Copilot CLI

Ejemplo de implementación de paquete público compatible con Copilot CLI y Testbench.

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

Ejemplo de implementación de paquete público para el plugin de GitHub Copilot de PhpStorm.

​Por qué necesitas un agente personalizado

​Arquitectura de extensión de Boost

​Clase base Agent

​Los tres contratos

​Contrato SupportsGuidelines

​Contrato SupportsMcp

​Contrato SupportsSkills

​Crear un agente personalizado

​Personalizar las guidelines

​Configurar guidelinesPath

​Agentes que requieren frontmatter

​Post-procesamiento de las guidelines

​Añadir guidelines personalizadas de IA

​Sobrescribir las guidelines integradas

​Añadir skills personalizadas

​Crear SKILL.md

​Generar el PDF de la factura

​Sobrescribir skills integradas

​Añadir soporte de Boost a paquetes de terceros

​Añadir guidelines

​Añadir skills

​Ejemplo práctico: agente personalizado para un agente de CI/CD propio

​Enlaces de referencia

ClaudeCode.php — ejemplo de implementación oficial

Agent Skills

Laravel Boost Custom Agent for GitHub Copilot CLI

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

Por qué necesitas un agente personalizado

Arquitectura de extensión de Boost

Clase base Agent

Los tres contratos

Contrato SupportsGuidelines

Contrato SupportsMcp

Contrato SupportsSkills

Crear un agente personalizado

Personalizar las guidelines

Configurar guidelinesPath

Agentes que requieren frontmatter

Post-procesamiento de las guidelines

Añadir guidelines personalizadas de IA

Sobrescribir las guidelines integradas

Añadir skills personalizadas

Crear SKILL.md

Generar el PDF de la factura

Sobrescribir skills integradas

Añadir soporte de Boost a paquetes de terceros

Añadir guidelines

Añadir skills

Ejemplo práctico: agente personalizado para un agente de CI/CD propio

Enlaces de referencia