> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear un agente personalizado de Boost

> Profundiza en la arquitectura de extensión de Laravel Boost y aprende a crear agentes personalizados implementando los contratos SupportsGuidelines, SupportsMcp y SupportsSkills.

## 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.                                    |

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

### Contrato SupportsGuidelines

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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.

<Steps>
  <Step title="Crea la clase del agente">
    Crea `app/Boost/MyAgent.php`.

    ```php theme={null}
    <?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';
        }
    }
    ```

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Registra el agente">
    Registra el agente personalizado en el método `boot` de `App\Providers\AppServiceProvider`.

    ```php theme={null}
    <?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.
  </Step>

  <Step title="Comprueba el funcionamiento">
    ```shell theme={null}
    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/`.
  </Step>
</Steps>

## Personalizar las guidelines

### Configurar guidelinesPath

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

```php theme={null}
// 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.

```php theme={null}
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()`.

```php theme={null}
public function frontmatter(): bool
{
    return true;
}
```

### Post-procesamiento de las guidelines

Puedes procesar el Markdown generado con `transformGuidelines()`.

```php theme={null}
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:

```php theme={null}
## 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.

````markdown theme={null}
---
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`:

```php theme={null}
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());
```

<Tip>
  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.
</Tip>

### 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
```

```php theme={null}
## 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
```

```markdown theme={null}
---
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 theme={null}
<?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`:

```php theme={null}
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:

```shell theme={null}
php artisan boost:install --agent=pipeline_agent
```

## Enlaces de referencia

<Card title="ClaudeCode.php — ejemplo de implementación oficial" icon="github" href="https://github.com/laravel/boost/blob/main/src/Install/Agents/ClaudeCode.php">
  Puedes revisar en el código fuente la implementación completa del agente ClaudeCode incluido con Boost.
</Card>

<Card title="Agent Skills" icon="book" href="https://agentskills.io/what-are-skills">
  Consulta la especificación del formato de SKILL.md y las buenas prácticas.
</Card>

<Card title="Laravel Boost Custom Agent for GitHub Copilot CLI" icon="github" href="/es/packages/laravel-boost-copilot-cli">
  Ejemplo de implementación de paquete público compatible con Copilot CLI y Testbench.
</Card>

<Card title="Laravel Boost Custom Agent for PhpStorm with GitHub Copilot" icon="github" href="/es/packages/laravel-boost-phpstorm-copilot">
  Ejemplo de implementación de paquete público para el plugin de GitHub Copilot de PhpStorm.
</Card>


## Related topics

- [Laravel Agent Detector — Paquete de detección de agentes de IA](/es/blog/agent-detector-introduction.md)
- [Agentes personalizados](/es/packages/laravel-copilot-sdk/custom-agents.md)
- [Crear un proveedor personalizado del AI SDK](/es/advanced/ai-sdk-custom-provider.md)
- [Laravel Boost](/es/boost.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/es/packages/laravel-boost-phpstorm-copilot.md)