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

# Boost의 커스텀 에이전트 만들기

> Laravel Boost의 확장 아키텍처를 심층 분석하고, SupportsGuidelines·SupportsMcp·SupportsSkills 컨트랙트를 구현한 커스텀 에이전트를 작성하는 방법을 해설합니다.

## 왜 커스텀 에이전트가 필요한가

Laravel Boost는 Claude Code, Cursor, Codex, GitHub Copilot(VS Code) 등 주요 AI 코딩 도구를 기본으로 서포트하고 있습니다. 그러나 사내 도구, 신흥 AI 에이전트, 독자 워크플로우에 대응하려면, Boost의 확장 기능을 사용해 커스텀 에이전트를 구현해야 합니다.

커스텀 에이전트가 도움이 되는 장면:

* Boost가 미대응인 IDE나 AI 도구를 사용하고 있음
* 사내 개발 워크플로우나 독자 CI/CD 파이프라인에 Boost를 통합하고 싶음
* 에이전트 고유의 설정 파일 형식이나 설치 절차가 있음

## Boost의 확장 아키텍처

### Agent 기저 클래스

모든 에이전트는 `Laravel\Boost\Install\Agents\Agent`를 상속합니다. 이 추상 클래스가 제공하는 기능:

* 에이전트의 검출(시스템 전체·프로젝트 단위)
* MCP 서버의 설치(파일 기반·셸 커맨드 기반)
* 가이드라인 변환 훅(`transformGuidelines`)

구현이 필수인 추상 메서드는 2개입니다.

| 메서드                                         | 설명                              |
| ------------------------------------------- | ------------------------------- |
| `name()`                                    | 에이전트의 내부 식별자(예: `claude_code`)  |
| `displayName()`                             | 설치 시에 표시되는 이름(예: `Claude Code`) |
| `systemDetectionConfig(Platform $platform)` | 시스템 전체에의 설치 검출 설정               |
| `projectDetectionConfig()`                  | 프로젝트 단위의 설치 검출 설정               |

### 3개의 컨트랙트

Boost의 기능을 선택적으로 활성화하기 위해, 이하의 컨트랙트를 필요한 만큼 구현합니다.

| 컨트랙트                 | 역할                        |
| -------------------- | ------------------------- |
| `SupportsGuidelines` | AI 가이드라인 파일의 쓰기 경로와 변환 처리 |
| `SupportsMcp`        | MCP 서버 설정의 설치             |
| `SupportsSkills`     | Agent Skills의 설치 경로       |

<Info>
  3개의 컨트랙트는 모두 임의입니다. 가이드라인만 서포트하고 MCP는 불필요, 라는 구현도 가능합니다.
</Info>

### SupportsGuidelines 컨트랙트

```php theme={null}
interface SupportsGuidelines
{
    // AIガイドラインを書き出すファイルパス
    public function guidelinesPath(): string;

    // ガイドラインファイルにフロントマターが必要か
    public function frontmatter(): bool;

    // 生成されたガイドラインのMarkdownを後処理する
    public function transformGuidelines(string $markdown): string;
}
```

`guidelinesPath()`는 생성한 가이드라인을 쓸 파일 경로를 반환합니다. Claude Code라면 `CLAUDE.md`, Cursor라면 `.cursor/rules/laravel-boost.mdc`처럼, 에이전트가 로드하는 형식에 맞춥니다.

`transformGuidelines()`는 생성 후의 Markdown을 가공하는 훅입니다. 에이전트 고유의 헤더를 추가하거나, 특수한 포맷으로 변환할 수 있습니다. `Agent` 기저 클래스에 구현된 기본은 그대로 문자열을 반환합니다.

### SupportsMcp 컨트랙트

```php theme={null}
interface SupportsMcp
{
    // MCPコマンドに絶対パスを使うか
    public function useAbsolutePathForMcp(): bool;

    // PHP実行ファイルのパスを返す
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // artisanのパスを返す
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // MCPサーバー設定をインストールする
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // HTTP経由のMCPサーバー設定をインストールする
    public function installHttpMcp(string $key, string $url): bool;
}
```

`Agent` 기저 클래스가 `installMcp()`와 `installHttpMcp()`의 기본 구현을 가지고 있으므로, 많은 경우에는 `mcpInstallationStrategy()`와 `mcpConfigPath()`를 오버라이드하는 것만으로 충분합니다.

설치 전략은 2종류가 있습니다.

| `McpInstallationStrategy` | 동작                       |
| ------------------------- | ------------------------ |
| `FILE`                    | JSON/TOML 파일에 설정을 쓴다(기본) |
| `SHELL`                   | 셸 커맨드를 실행하여 MCP를 등록한다    |
| `NONE`                    | MCP 설치를 스킵한다             |

### SupportsSkills 컨트랙트

```php theme={null}
interface SupportsSkills
{
    // Agent Skillsを書き出すディレクトリパス
    public function skillsPath(): string;
}
```

에이전트가 로드하는 스킬 디렉토리의 경로를 반환합니다. Claude Code라면 `.claude/skills`, Cursor라면 `.cursor/skills`처럼 에이전트의 사양에 맞춥니다.

## 커스텀 에이전트의 작성

실제로 독자 에이전트 클래스를 구현합니다. 여기서는 독자의 CI/CD 워크플로우에 짜넣어진 가상 에이전트 "MyAgent"를 예로 합니다.

<Steps>
  <Step title="에이전트 클래스를 작성한다">
    `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() は Agent 基底クラスのデフォルト (false) を使用
        // transformGuidelines() も基底クラスのデフォルト（そのまま返す）を使用

        // --- SupportsMcp ---

        // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
        // installMcp(), installHttpMcp() はすべて Agent 基底クラスが実装済み

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

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

        // --- SupportsSkills ---

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

    <Info>
      `systemDetectionConfig()`와 `projectDetectionConfig()`는 Boost가 에이전트를 시스템·프로젝트에서 자동 검출하기 위해 사용합니다. `boost:install` 실행 시에 대상 에이전트를 자동적으로 후보로서 표시합니다.
    </Info>
  </Step>

  <Step title="에이전트를 등록한다">
    `App\Providers\AppServiceProvider`의 `boot` 메서드에 커스텀 에이전트를 등록합니다.

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

    등록 후, `php artisan boost:install`을 실행하면 MyAgent가 선택지에 표시됩니다.
  </Step>

  <Step title="동작을 확인한다">
    ```shell theme={null}
    php artisan boost:install
    ```

    설치 대상의 에이전트를 선택하는 화면에서 MyAgent가 표시됩니다. 선택하면 `MYAGENT.md`, `.myagent.json`, `.myagent/skills/`가 생성됩니다.
  </Step>
</Steps>

## 가이드라인의 커스터마이즈

### guidelinesPath의 설정

에이전트에 따라 가이드라인 파일의 로드 장소는 다릅니다.

```php theme={null}
// 単一ファイルとして出力する場合
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}
```

설정 파일에서 덮어쓸 수 있게 하면 유연성이 높아집니다.

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

### 프런트매터가 필요한 에이전트

Cursor의 `.cursor/rules/*.mdc`처럼 프런트매터가 필요한 포맷에는 `frontmatter()`에서 `true`를 반환합니다.

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

### 가이드라인의 후처리

`transformGuidelines()`를 사용하여 생성 후의 Markdown을 가공할 수 있습니다.

```php theme={null}
public function transformGuidelines(string $markdown): string
{
    // エージェント独自のヘッダーを追加する
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}
```

## 커스텀 AI 가이드라인의 추가

프로젝트 고유의 룰을 Boost의 가이드라인에 추가하려면, `.ai/guidelines/` 디렉토리에 Blade 파일을 배치합니다.

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

파일 예:

```php theme={null}
## プロジェクト固有のルール

このプロジェクトでは以下の規約に従うこと:

- モデルは必ず `App\Models\` 名前空間に配置する
- すべてのAPIエンドポイントは `App\Http\Controllers\Api\` 以下に作成する
- DBトランザクションは `DB::transaction()` を使いサービスクラス内に閉じ込める

@verbatim
<code-snippet name="サービスクラスのトランザクション例" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim
```

`boost:install`을 실행하면, 이 가이드라인이 Boost 내장의 가이드라인과 자동적으로 결합되어 출력됩니다.

### 내장 가이드라인의 오버라이드

Boost의 내장 가이드라인과 같은 경로에 커스텀 파일을 두면, 그쪽이 우선됩니다.

```
# Boostの "Inertia React v2 Form Guidance" をオーバーライドする
.ai/guidelines/inertia-react/2/forms.blade.php
```

## 커스텀 스킬의 추가

### SKILL.md의 작성

`.ai/skills/{스킬명}/SKILL.md`에 스킬을 정의합니다.

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

`SKILL.md`는 YAML 프런트매터와 Markdown 지시로 구성합니다.

````markdown theme={null}
---
name: creating-invoices
description: 請求書（Invoice）の作成・更新・送信に関する処理を実装する際に使うスキル。
---

# 請求書作成スキル

## このスキルを使う場面

請求書モデルの作成、請求書のPDF生成、メール送信を実装するときに使います。

## ファイル構造

- `app/Models/Invoice.php` — 請求書モデル
- `app/Services/InvoiceService.php` — ビジネスロジック
- `app/Jobs/SendInvoiceEmail.php` — メール送信ジョブ

## 実装パターン

### 請求書の作成

```php
// $items はコントローラーや他のサービスから渡された配列
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);
````

### 請求書のPDF生成

PDFは `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>
  스킬은 "필요할 때만 로드하는" 설계입니다. 항상 필요한 정보는 가이드라인에, 태스크 고유의 상세한 패턴은 스킬로 나눔으로써, AI의 컨텍스트 사용량을 최적화할 수 있습니다.
</Tip>

### 내장 스킬의 오버라이드

Boost의 내장 스킬과 같은 이름으로 커스텀 스킬을 만들면 덮어써집니다.

```
# livewire-development スキルをカスタマイズする
.ai/skills/livewire-development/SKILL.md
```

## 서드파티 패키지에의 Boost 대응 추가

자체 패키지에 Boost 서포트를 추가하려면, 패키지의 `resources/boost/` 디렉토리에 설정 파일을 배치합니다.

### 가이드라인의 추가

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

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

このパッケージは [機能の概要] を提供します。

### 基本的な使い方

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

### 스킬의 추가

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

```markdown theme={null}
---
name: mypackage-development
description: MyPackageの機能を実装するスキル。
---

# MyPackage Development

## このスキルを使う場面
MyPackageを使った機能実装時に使います。

## 主な機能

- 機能1: ...
- 機能2: ...
```

패키지 사용자가 `php artisan boost:install`을 실행하면, 이 가이드라인과 스킬이 자동적으로 검출되어 설치 대상으로서 표시됩니다.

## 실전 예: 독자 CI/CD 에이전트용 커스텀 에이전트

사내의 CI/CD 파이프라인에 짜넣어진 가상 에이전트 "PipelineAgent"의 완전한 구현 예입니다. 이 에이전트는 가이드라인만 서포트하며, MCP와 스킬은 서포트하지 않습니다.

```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
    {
        // CI環境変数で存在を検出する
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // プロジェクトルートの設定ファイルで検出する
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // CI/CDエージェントが読み込む規約のパス
        return '.pipeline/CODING_GUIDELINES.md';
    }

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

    public function transformGuidelines(string $markdown): string
    {
        // パイプライン用のメタデータヘッダーを追加する
        $timestamp = now()->toIso8601String();

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

`AppServiceProvider`에 등록합니다:

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

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

CI 환경에서는 이하의 커맨드로 가이드라인만을 생성할 수 있습니다:

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

## 참고 링크

<Card title="ClaudeCode.php — 공식 구현 예" icon="github" href="https://github.com/laravel/boost/blob/main/src/Install/Agents/ClaudeCode.php">
  Boost에 동봉되어 있는 ClaudeCode 에이전트의 완전한 구현을 소스 코드로 확인할 수 있습니다.
</Card>

<Card title="Agent Skills" icon="book" href="https://agentskills.io/what-are-skills">
  SKILL.md의 포맷 사양과 베스트 프랙티스를 참조할 수 있습니다.
</Card>

<Card title="Laravel Boost Custom Agent for GitHub Copilot CLI" icon="github" href="/ko/packages/laravel-boost-copilot-cli">
  Copilot CLI와 Testbench 양대응의 공개 패키지 구현 예
</Card>

<Card title="Laravel Boost Custom Agent for PhpStorm with GitHub Copilot" icon="github" href="/ko/packages/laravel-boost-phpstorm-copilot">
  PhpStorm의 GitHub Copilot 플러그인용 공개 패키지 구현 예
</Card>


## Related topics

- [AI SDK의 커스텀 프로바이더 만들기](/ko/advanced/ai-sdk-custom-provider.md)
- [커스텀 에이전트](/ko/packages/laravel-copilot-sdk/custom-agents.md)
- [Laravel Agent Detector — AI 에이전트 감지 패키지](/ko/blog/agent-detector-introduction.md)
- [Laravel Boost](/ko/boost.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/ko/packages/laravel-boost-phpstorm-copilot.md)