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

# Einen eigenen Agenten für Boost erstellen

> Ein tiefer Blick in die Erweiterungsarchitektur von Laravel Boost und eine Anleitung zur Implementierung eines eigenen Agenten mit den Contracts SupportsGuidelines, SupportsMcp und SupportsSkills.

## Warum ein eigener Agent

Laravel Boost unterstützt gängige KI-Coding-Werkzeuge wie Claude Code, Cursor, Codex und GitHub Copilot (VS Code) von Haus aus. Für interne Werkzeuge, aufstrebende KI-Agenten oder eigene Workflows müssen Sie mit Boosts Erweiterungsmöglichkeiten einen eigenen Agenten implementieren.

Wann ein eigener Agent nützlich ist:

* Sie nutzen eine IDE oder ein KI-Werkzeug, das Boost nicht unterstützt.
* Sie möchten Boost in einen internen Entwicklungs-Workflow oder eine eigene CI/CD-Pipeline integrieren.
* Es gibt agentenspezifische Konfigurationsformate oder Installationsprozeduren.

## Boosts Erweiterungsarchitektur

### Basisklasse Agent

Jeder Agent erbt von `Laravel\Boost\Install\Agents\Agent`. Diese abstrakte Klasse liefert:

* Erkennung des Agenten (systemweit und projektspezifisch)
* Installation von MCP-Servern (dateibasiert und per Shell-Kommando)
* Hook zur Transformation von Guidelines (`transformGuidelines`)

Pflichtmethoden gibt es zwei:

| Methode                                     | Beschreibung                                          |
| ------------------------------------------- | ----------------------------------------------------- |
| `name()`                                    | Interner Bezeichner (z. B. `claude_code`)             |
| `displayName()`                             | Anzeigename in der Installation (z. B. `Claude Code`) |
| `systemDetectionConfig(Platform $platform)` | Konfiguration der systemweiten Erkennung              |
| `projectDetectionConfig()`                  | Konfiguration der projektbezogenen Erkennung          |

### Drei Contracts

Um Boost-Features selektiv zu aktivieren, implementieren Sie die passenden Contracts.

| Contract             | Aufgabe                                        |
| -------------------- | ---------------------------------------------- |
| `SupportsGuidelines` | Zielpfad und Nachbearbeitung von KI-Guidelines |
| `SupportsMcp`        | Installation der MCP-Server-Konfiguration      |
| `SupportsSkills`     | Installationspfad für Agent Skills             |

<Info>
  Alle drei Contracts sind optional. Sie können z. B. nur Guidelines, aber keine MCP-Unterstützung anbieten.
</Info>

### SupportsGuidelines-Contract

```php theme={null}
interface SupportsGuidelines
{
    // Zielpfad für die KI-Guidelines-Datei
    public function guidelinesPath(): string;

    // Benötigt die Datei Frontmatter?
    public function frontmatter(): bool;

    // Nachbearbeitung des Guidelines-Markdown
    public function transformGuidelines(string $markdown): string;
}
```

`guidelinesPath()` liefert den Pfad, in den die generierten Guidelines geschrieben werden. Beispielsweise `CLAUDE.md` für Claude Code oder `.cursor/rules/laravel-boost.mdc` für Cursor.

`transformGuidelines()` ist ein Hook, der das erzeugte Markdown weiter verarbeitet — etwa um einen agent-spezifischen Header zu setzen. Die Basisklasse `Agent` gibt in der Standardimplementierung die Zeichenkette unverändert zurück.

### SupportsMcp-Contract

```php theme={null}
interface SupportsMcp
{
    // Absolute Pfade in MCP-Kommandos verwenden?
    public function useAbsolutePathForMcp(): bool;

    // Pfad zur PHP-Executable
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // Pfad zu artisan
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // MCP-Serverkonfiguration installieren
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // HTTP-basierte MCP-Serverkonfiguration installieren
    public function installHttpMcp(string $key, string $url): bool;
}
```

Da `Agent` Standardimplementierungen von `installMcp()` und `installHttpMcp()` mitbringt, genügt in vielen Fällen das Überschreiben von `mcpInstallationStrategy()` und `mcpConfigPath()`.

Es gibt zwei Installationsstrategien:

| `McpInstallationStrategy` | Verhalten                                                      |
| ------------------------- | -------------------------------------------------------------- |
| `FILE`                    | Schreibt die Einstellungen in eine JSON-/TOML-Datei (Standard) |
| `SHELL`                   | Registriert MCP per Shell-Kommando                             |
| `NONE`                    | Überspringt die MCP-Installation                               |

### SupportsSkills-Contract

```php theme={null}
interface SupportsSkills
{
    // Zielverzeichnis für Agent Skills
    public function skillsPath(): string;
}
```

Gibt das Verzeichnis zurück, in das der Agent seine Skills schreibt — z. B. `.claude/skills` bei Claude Code oder `.cursor/skills` bei Cursor.

## Einen eigenen Agenten erstellen

Wir implementieren einen eigenen Agent. Als Beispiel dient ein fiktiver Agent „MyAgent", der in einen eigenen CI/CD-Workflow eingebunden ist.

<Steps>
  <Step title="Agent-Klasse erstellen">
    Legen Sie `app/Boost/MyAgent.php` an.

    ```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() nutzt den Default (false) der Basisklasse
        // transformGuidelines() nutzt ebenfalls den Default (unverändert zurückgeben)

        // --- SupportsMcp ---

        // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
        // installMcp() und installHttpMcp() sind in der Basisklasse Agent implementiert

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

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

        // --- SupportsSkills ---

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

    <Info>
      `systemDetectionConfig()` und `projectDetectionConfig()` verwendet Boost, um den Agenten automatisch zu erkennen — sowohl systemweit als auch im Projekt. Bei `boost:install` wird der Agent dann automatisch als Kandidat angezeigt.
    </Info>
  </Step>

  <Step title="Agenten registrieren">
    Registrieren Sie den Agenten in der `boot`-Methode des `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);
        }
    }
    ```

    Nach der Registrierung erscheint MyAgent bei `php artisan boost:install` in der Auswahl.
  </Step>

  <Step title="Ergebnis prüfen">
    ```shell theme={null}
    php artisan boost:install
    ```

    Auf der Auswahlseite erscheint MyAgent. Nach der Auswahl werden `MYAGENT.md`, `.myagent.json` und `.myagent/skills/` erzeugt.
  </Step>
</Steps>

## Guidelines anpassen

### guidelinesPath konfigurieren

Verschiedene Agenten lesen Guidelines an unterschiedlichen Orten.

```php theme={null}
// Ausgabe als einzelne Datei
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}
```

Über Config konfigurierbar zu machen erhöht die Flexibilität:

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

### Agenten, die Frontmatter erwarten

Formate wie `.cursor/rules/*.mdc` von Cursor verlangen Frontmatter — `frontmatter()` gibt `true` zurück.

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

### Guidelines nachbearbeiten

Mit `transformGuidelines()` bearbeiten Sie das erzeugte Markdown weiter.

```php theme={null}
public function transformGuidelines(string $markdown): string
{
    // Eigenen Header hinzufügen
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}
```

## Eigene KI-Guidelines hinzufügen

Um projektspezifische Regeln in die Boost-Guidelines aufzunehmen, legen Sie Blade-Dateien im Verzeichnis `.ai/guidelines/` ab.

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

Beispiel-Datei:

```php theme={null}
## Projekt-spezifische Regeln

In diesem Projekt gelten folgende Konventionen:

- Modelle liegen im Namensraum `App\Models\`
- Alle API-Endpoints befinden sich unter `App\Http\Controllers\Api\`
- Datenbank-Transaktionen kapseln wir mit `DB::transaction()` innerhalb von Service-Klassen

@verbatim
<code-snippet name="Transaktion in einer Service-Klasse" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim
```

Beim Ausführen von `boost:install` werden diese Guidelines automatisch mit den mitgelieferten kombiniert und ausgegeben.

### Eingebaute Guidelines überschreiben

Legen Sie eine eigene Datei am selben Pfad wie eine eingebaute Guideline ab, hat Ihre Vorrang.

```
# "Inertia React v2 Form Guidance" überschreiben
.ai/guidelines/inertia-react/2/forms.blade.php
```

## Eigene Skills hinzufügen

### SKILL.md erstellen

Legen Sie einen Skill unter `.ai/skills/{Skill-Name}/SKILL.md` ab.

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

`SKILL.md` besteht aus YAML-Frontmatter und Markdown-Anleitung.

````markdown theme={null}
---
name: creating-invoices
description: Skill für die Implementierung von Erstellung, Aktualisierung und Versand von Rechnungen.
---

# Skill „Rechnungserstellung"

## Wann diesen Skill verwenden

Beim Erstellen des Rechnungsmodells, der PDF-Erzeugung sowie beim Mailversand.

## Dateistruktur

- `app/Models/Invoice.php` — Rechnungsmodell
- `app/Services/InvoiceService.php` — Geschäftslogik
- `app/Jobs/SendInvoiceEmail.php` — Job zum Mailversand

## Implementierungsmuster

### Rechnung anlegen

```php
// $items ist ein Array, das aus Controller oder anderen Services übergeben wird
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);
````

### PDF-Erzeugung der Rechnung

PDFs werden mit `barryvdh/laravel-dompdf` erzeugt:

```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>
  Skills sind so entworfen, dass sie „nur bei Bedarf geladen werden". Wenn Sie stets benötigte Informationen in Guidelines und aufgabenspezifische Details in Skills packen, optimieren Sie den Kontextverbrauch der KI.
</Tip>

### Eingebaute Skills überschreiben

Legen Sie einen eigenen Skill mit demselben Namen an — er überschreibt den eingebauten.

```
# Skill livewire-development anpassen
.ai/skills/livewire-development/SKILL.md
```

## Boost-Unterstützung für Drittanbieter-Pakete ergänzen

Damit Ihr eigenes Paket Boost unterstützt, legen Sie Konfigurationsdateien im Verzeichnis `resources/boost/` ab.

### Guidelines hinzufügen

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

```php theme={null}
## MyPackage

Dieses Paket stellt [Feature-Übersicht] bereit.

### Grundlegende Verwendung

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

### Skills hinzufügen

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

```markdown theme={null}
---
name: mypackage-development
description: Skill zur Implementierung von Funktionen mit MyPackage.
---

# MyPackage Development

## Wann diesen Skill verwenden
Bei der Implementierung von Features, die MyPackage nutzen.

## Wichtige Funktionen

- Feature 1: …
- Feature 2: …
```

Führt der Nutzer Ihres Pakets `php artisan boost:install` aus, werden diese Guidelines und Skills automatisch erkannt und angeboten.

## Praxisbeispiel: eigener Agent für interne CI/CD

Vollständige Implementierung eines fiktiven Agenten „PipelineAgent", der nur Guidelines unterstützt (kein MCP, keine 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
    {
        // Erkennung über Umgebungsvariable
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // Erkennung anhand einer Konfigurationsdatei im Projekt-Root
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // Pfad, an dem der CI/CD-Agent seine Konventionen liest
        return '.pipeline/CODING_GUIDELINES.md';
    }

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

    public function transformGuidelines(string $markdown): string
    {
        // Metadaten-Header für die Pipeline anfügen
        $timestamp = now()->toIso8601String();

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

Registrieren Sie den Agenten im `AppServiceProvider`:

```php theme={null}
use App\Boost\PipelineAgent;
use Laravel\Boost\Boost;

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

In der CI-Umgebung erzeugen Sie damit ausschließlich Guidelines:

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

## Referenz-Links

<Card title="ClaudeCode.php — offizielles Referenzbeispiel" icon="github" href="https://github.com/laravel/boost/blob/main/src/Install/Agents/ClaudeCode.php">
  Vollständige Implementierung des mitgelieferten Claude-Code-Agenten im Quellcode.
</Card>

<Card title="Agent Skills" icon="book" href="https://agentskills.io/what-are-skills">
  Formatspezifikation und Best Practices für SKILL.md.
</Card>

<Card title="Laravel Boost Custom Agent for GitHub Copilot CLI" icon="github" href="/de/packages/laravel-boost-copilot-cli">
  Beispielpaket, das Copilot CLI und Testbench unterstützt.
</Card>

<Card title="Laravel Boost Custom Agent for PhpStorm with GitHub Copilot" icon="github" href="/de/packages/laravel-boost-phpstorm-copilot">
  Beispielpaket für das GitHub-Copilot-Plugin in PhpStorm.
</Card>


## Related topics

- [Einen eigenen Provider für das AI SDK erstellen](/de/advanced/ai-sdk-custom-provider.md)
- [Laravel Boost](/de/boost.md)
- [Laravel AI SDK](/de/ai-sdk.md)
- [Laravel Sentinel – Analyse der Route-Schutz-Middleware](/de/blog/sentinel-introduction.md)
- [Service-Provider](/de/service-providers.md)