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

# Plugin Directories

> 介紹如何使用 Plugin Directory 一次載入 Skills、Hooks、MCP、Custom Agents 等擴充功能。

## Plugin Directories

Plugin Directory 是一種機制,可將 Skills、Hooks、MCP 伺服器、Custom Agents、LSP 設定等整合到單一目錄中一次載入。適合用於將可重用的功能組合封裝並隨應用程式或儲存庫發佈。

在 Laravel 版中,可透過 `SessionConfig` 或 `ResumeSessionConfig` 的 `pluginDirectories` 指定。

## 使用場景

* 將多個擴充功能作為單一能力包發佈
* 將 plugin 隨儲存庫一併發佈,讓所有成員使用相同設定
* 在上架 Marketplace 之前,於本機開發與驗證 plugin
* 使用本機 checkout 暫時覆寫已安裝的 plugin

若只需要 1 個 MCP 伺服器、1 個 Hook 或 1 個 Custom Agent,直接指定到 `mcpServers`、`hooks`、`customAgents` 反而更為簡單。Plugin Directory 適合用於一次發佈多個相關功能。

## 目錄結構

Copilot CLI 會從每個 plugin 目錄中尋找 `plugin.json` 或位於根目錄下的 `SKILL.md`。

```text theme={null}
my-plugin/
├── plugin.json
├── SKILL.md
├── hooks.json
├── .mcp.json
├── agents/
│   └── code-reviewer.md
└── skills/
    └── lint-fix/
        └── SKILL.md
```

`plugin.json` 也可以放在 `.github/plugin.json` 或 `.github/plugin/plugin.json`。Skills、Hooks、MCP、Agents 等各自擁有獨立的 loader,只需包含需要的項目即可。

## 從 Laravel 載入

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session): void {
    $response = $session->sendAndWait(
        prompt: '請依照 plugin 的審查方針檢視此變更',
    );

    dump($response->content());
}, config: new SessionConfig(
    pluginDirectories: [
        base_path('plugins/code-reviewer'),
        base_path('plugins/lint-fix'),
    ],
));
```

也可以使用陣列形式指定。

```php theme={null}
Copilot::run(
    prompt: '請改善 README',
    config: [
        'pluginDirectories' => [
            base_path('plugins/docs-writer'),
        ],
    ],
);
```

## 與 `cli_args` 的差異

在官方 SDK 中,有時會將其說明為 runtime 啟動時的 `--plugin-dir` 參數。Laravel 版基本上使用 Session 設定的 `pluginDirectories`。

另一方面,若要對 CLI 程序啟動本身傳入參數,可使用 `config/copilot.php` 的 `cli_args` 或 `Copilot::useStdio()` 的 `cli_args`。但 `cli_args` 僅在 SDK 透過 stdio 啟動 CLI 時有效,連線至外部 runtime(例如 `useTcp()`)時會被忽略。

```php theme={null}
$stdioConfig = config('copilot');
$stdioConfig['cli_args'] = [
    '--plugin-dir',
    base_path('plugins/code-reviewer'),
];

Copilot::useStdio($stdioConfig)->start(fn (CopilotSession $session) => ...);
```

通常請優先使用 `pluginDirectories`。它可以在 Session 層級明確指定,並與其他 `SessionConfig` 設定集中管理。

## 為了可重現性

* 相較於相對路徑,建議使用 `base_path()` 等轉為絕對路徑
* 隨儲存庫發佈的 plugin 應納入版本控管
* 使用 Marketplace 或外部發佈的 plugin 時,請將使用版本記錄於文件中
* 在正式環境中,請勿允許使用者輸入直接指定任意的 plugin 路徑

## 參考

* [SessionConfig](/zh-TW/packages/laravel-copilot-sdk/session-config)
* [Custom Agents](/zh-TW/packages/laravel-copilot-sdk/custom-agents)
* [MCP](/zh-TW/packages/laravel-copilot-sdk/mcp)
* [Hooks](/zh-TW/packages/laravel-copilot-sdk/hooks)
* [Skills](/zh-TW/packages/laravel-copilot-sdk/skills)

<Info>
  最新資訊請參閱 [GitHub 儲存庫](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [SessionConfig](/zh-TW/packages/laravel-copilot-sdk/session-config.md)
- [laravel/agent-skills — Laravel 官方 AI Agent 技能集](/zh-TW/blog/agent-skills-introduction.md)
- [Streaming Events](/zh-TW/packages/laravel-copilot-sdk/streaming-events.md)
- [Laravel PAO — 針對 AI Agent 的輸出最佳化工具](/zh-TW/blog/pao-introduction.md)
- [2026 年 3 月 Laravel 更新](/zh-TW/blog/changelog/202603.md)