Plugin Directories

Plugin Directory는 스킬, 훅, MCP 서버, 커스텀 에이전트, LSP 설정 등을 하나의 디렉터리에 모아서 로드하는 구조입니다. 재사용 가능한 기능 세트를 앱이나 저장소에 동봉하려는 경우에 사용합니다. Laravel 버전에서는 SessionConfig 또는 ResumeSessionConfig의 pluginDirectories로 지정할 수 있습니다.

사용처

여러 확장 기능을 하나의 능력 팩으로 배포
저장소에 플러그인을 동봉하여 모두가 같은 설정을 사용하도록 함
Marketplace 공개 전 플러그인을 로컬에서 개발, 검증
설치된 플러그인을 로컬 checkout으로 일시적으로 덮어쓰기

MCP 서버 1개, 훅 1개, 커스텀 에이전트 1개뿐이라면 mcpServers, hooks, customAgents에 직접 지정하는 편이 단순합니다. Plugin Directory는 관련된 여러 기능을 한꺼번에 배포하려는 경우에 적합합니다.

디렉터리 구성

Copilot CLI는 각 플러그인 디렉터리에서 plugin.json 또는 루트 바로 아래의 SKILL.md를 찾습니다.

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에도 배치할 수 있습니다. 스킬, 훅, MCP, 에이전트 등은 각각 독립된 로더를 가지므로 필요한 것만 포함시키면 충분합니다.

Laravel에서 로드하기

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: '이 변경사항을 플러그인의 리뷰 방침으로 확인해줘',
    );

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

배열 형식으로도 지정할 수 있습니다.

Copilot::run(
    prompt: 'README를 개선해줘',
    config: [
        'pluginDirectories' => [
            base_path('plugins/docs-writer'),
        ],
    ],
);

`cli_args`와의 차이

공식 SDK에서는 런타임 기동 시의 --plugin-dir 인자로 설명되는 경우가 있습니다. Laravel 버전에서는 세션 설정의 pluginDirectories를 사용하는 것이 기본입니다. 한편, CLI 프로세스 기동 자체에 인자를 전달하려면 config/copilot.php의 cli_args 또는 Copilot::useStdio()의 cli_args를 사용할 수 있습니다. 단, cli_args는 stdio로 SDK가 CLI를 기동하는 경우에만 유효하고, useTcp() 등 외부 runtime 접속 시에는 무시됩니다.

$stdioConfig = config('copilot');
$stdioConfig['cli_args'] = [
    '--plugin-dir',
    base_path('plugins/code-reviewer'),
];

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

일반적으로 pluginDirectories를 우선하세요. 세션 단위로 명시할 수 있고 다른 SessionConfig 설정과 같은 장소에서 관리할 수 있습니다.

재현성을 위한 운영

상대 경로보다 base_path() 등으로 절대 경로화
저장소에 동봉하는 플러그인은 버전 관리
Marketplace나 외부 배포 플러그인을 사용할 경우, 이용 버전을 문서화
프로덕션 환경에서는 사용자 입력으로부터 임의의 플러그인 경로를 직접 지정하지 않도록 함

참고

최신 정보는 GitHub 저장소를 참고하세요.