GitLab Duo CLI 사용자 정의

요약

GitLab Duo CLI는 다음과 같은 사용자 정의를 지원합니다. 훅을 사용해 GitLab Duo CLI 수명 주기의 특정 시점에 사용자 정의 명령을 실행합니다. 예를 들어 환경 정보를 수집하는 스크립트를 실행해 새 채팅 세션마다 추가 컨텍스트를 주입할 수 있습니다.

히스토리

사용자 수준 Agent Skills를 활성화하는 환경 변수와 옵션이 GitLab 19.0 릴리스 기간에 GitLab Duo CLI 8.83.0에서 실험 기능으로 도입되었습니다.

GitLab Duo CLI는 다음과 같은 사용자 정의를 지원합니다.

훅을 사용해 GitLab Duo CLI 수명 주기의 특정 시점에 사용자 정의 명령을 실행합니다.
사용자 정의 슬래시 명령어를 사용해 CLI를 워크플로나 사용 사례에 더 맞춥니다.
플러그인을 사용해 마켓플레이스에서 Agent Skills, 사용자 정의 슬래시 명령어, Model Context Protocol(MCP) 서버를 설치합니다.
GitLab Duo Agent Platform에 설정한 사용자 정의 지침을 사용해 워크플로, 코딩 표준, 프로젝트 요구 사항에 맞춥니다.

훅#

히스토리

GitLab 19.1 릴리스 기간에 GitLab Duo CLI 8.95.0에서 실험 기능으로 도입되었습니다.

훅을 사용해 GitLab Duo CLI 수명 주기의 특정 시점에 사용자 정의 명령을 실행합니다.

예를 들어 환경 정보를 수집하는 스크립트를 실행해 새 채팅 세션마다 추가 컨텍스트를 주입할 수 있습니다.

GitLab Duo CLI는 두 수준에서 훅을 지원합니다.

사용자 수준(전역): 모든 프로젝트에 적용됩니다.
프로젝트 수준: 특정 프로젝트에만 적용됩니다. 프로젝트 수준 훅은 체크아웃한 리포지터리의 임의 코드가 실행되는 것을 막기 위해 기본적으로 비활성화되어 있습니다.

사용자 수준과 프로젝트 수준 hooks.json 파일이 모두 있으면 CLI가 훅을 병합하고 사용자 수준 훅을 먼저 실행합니다.

Note

보안상의 이유로 민감한 환경 변수(GITLAB_TOKEN, GITLAB_OAUTH_TOKEN, CI_JOB_TOKEN)는 훅 프로세스에서 제외됩니다.

훅 실행#

훅이 실행되면 GitLab Duo CLI는 다음을 수행합니다.

세션 메타데이터가 담긴 JSON 객체를 명령의 표준 입력으로 전송합니다.

{
  "session_id": "abc-123",
  "cwd": "/path/to/project",
  "transcript_path": "",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

훅 프로세스에 환경 변수 DUO_SESSION_ID와 DUO_PROJECT_DIR를 설정합니다.
명령의 표준 출력을 세션의 추가 컨텍스트로 수집합니다.

훅은 표준 출력으로 일반 텍스트 또는 JSON 객체를 반환할 수 있습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Your context string here"
  }
}

훅이 0이 아닌 상태로 종료되거나 시간이 초과되면 경고로 기록되지만, 세션이 시작되는 것을 막지는 않습니다.

훅 만들기#

GitLab Duo CLI는 새 세션이 시작되거나 기존 세션이 다시 시작될 때 실행되는 SessionStart 이벤트를 지원합니다.

훅을 만들려면 다음을 수행합니다.

hooks.json 파일을 만듭니다.
- 사용자 수준 훅의 경우:
  - Linux 또는 macOS에서는 ~/.gitlab/duo/hooks.json에 파일을 만듭니다.
  - Windows에서는 %APPDATA%\GitLab\duo\hooks.json에 파일을 만듭니다.
- 프로젝트 수준 훅의 경우 프로젝트 루트에 파일을 만듭니다: <project>/.gitlab/duo/hooks.json.

파일에 훅을 정의합니다.

훅을 트리거해야 하는 SessionStart 이벤트 소스(startup 또는 resume)마다 matcher 그룹을 만듭니다.

각 matcher 그룹에는 선택적인 정규식 matcher 값과 명령 훅 배열이 있습니다.

필드	설명
`matcher`	선택 사항. 이벤트 소스(`SessionStart`의 경우 `startup` 또는 `resume`)에 대해 검사하는 정규식입니다. 모두 일치시키려면 생략합니다.
`hooks[].type`	`"command"`여야 합니다.
`hooks[].command`	실행할 셸 명령입니다.
`hooks[].timeout`	선택 사항. 초 단위 시간 제한입니다. 기본값: 30.

예를 들면 다음과 같습니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.my-coding-preferences.md",
            "timeout": 10
          }
        ]
     }
    ]
  }
}

프로젝트 수준 훅이 있으면 GitLab Duo CLI를 시작할 때 활성화합니다.

   glab duo cli --enable-project-hooks

   duo --enable-project-hooks

또는 환경 변수를 설정합니다.

export GITLAB_ENABLE_PROJECT_HOOKS=true

사용자 정의 슬래시 명령어#

히스토리

GitLab 19.2 릴리스 기간에 GitLab Duo CLI 9.2.0에서 도입되었습니다.

자주 사용하는 프롬프트를 위한 사용자 정의 슬래시 명령어를 만듭니다.

GitLab Duo CLI는 두 수준에서 사용자 정의 슬래시 명령어를 지원합니다.

사용자 수준: 모든 프로젝트에 적용됩니다.
프로젝트 수준: 특정 프로젝트에만 적용됩니다.

사용자 수준 명령어와 프로젝트 수준 명령어의 이름이 같으면 프로젝트 수준 명령어가 우선합니다. 사용자 정의 슬래시 명령어는 기본 제공 슬래시 명령어나 Agent Skills 슬래시 명령어를 재정의할 수 없습니다.

사용자 정의 슬래시 명령어 만들기#

사용자 정의 슬래시 명령어를 만들려면 Markdown 파일을 만듭니다.

파일 이름이 명령어 이름이 되고, 파일 콘텐츠가 프롬프트가 됩니다.

예를 들어 daily.md라는 파일은 /daily 명령어를 만듭니다.

commands 디렉터리를 만듭니다.
- 프로젝트 수준 명령어의 경우 프로젝트 루트에 디렉터리를 만듭니다: <project>/.agents/commands/.
- 사용자 수준 명령어의 경우 다음 위치 중 하나를 사용합니다.
  - 다른 GitLab Duo 사용자 정의 파일과 함께 명령어를 보관하려면:
    - Linux 또는 macOS에서는 ~/.gitlab/duo/commands/에 디렉터리를 만듭니다.
    - Windows에서는 %APPDATA%\GitLab\duo\commands\에 디렉터리를 만듭니다.
    - GLAB_CONFIG_DIR 또는 XDG_CONFIG_HOME을 설정했다면 $GLAB_CONFIG_DIR/commands/ 또는 $XDG_CONFIG_HOME/gitlab/duo/commands/를 사용합니다. 둘 다 설정했다면 GLAB_CONFIG_DIR가 우선합니다.
  - 다른 AI 도구와 명령어를 공유하려면:
    - Linux 또는 macOS에서는 ~/.agents/commands/에 디렉터리를 만듭니다.
    - Windows에서는 %USERPROFILE%\.agents\commands\에 디렉터리를 만듭니다.
그 디렉터리에 Markdown 파일을 만듭니다. 파일 이름으로 명령어 이름을 사용합니다. 명령어 이름은 문자 또는 숫자로 시작해야 하며, 문자, 숫자, 하이픈, 밑줄만 포함할 수 있습니다.
파일에 프롬프트를 추가합니다.
선택 사항. 파일 맨 위의 YAML front matter에 description 필드를 추가합니다. 이 설명은 슬래시 명령어 메뉴에서 명령어 옆에 표시됩니다.

예를 들어 daily.md에 정의한 /daily 명령어는 다음과 같습니다.
```
---
description: Prepare a daily report
---

Use `glab todo list` to fetch my open TODO items. Give me a concise morning report ranked by priority.
```
GitLab Duo CLI를 다시 시작합니다. CLI는 시작할 때 사용자 정의 슬래시 명령어를 검색합니다.

사용자 정의 슬래시 명령어 사용#

대화형 모드에서는 프롬프트에 슬래시 명령어를 입력하고 Enter를 누릅니다. GitLab Duo CLI는 파일 콘텐츠를 프롬프트로 전송합니다.

명령어 이름 뒤에 입력한 텍스트는 프롬프트 끝에 추가됩니다.

추가 텍스트를 사용해 사용자 정의 슬래시 명령어의 동작을 조정합니다.

예를 들면 /daily prioritize my milestone deliverables입니다.

플러그인#

히스토리

GitLab 19.3 릴리스 기간에 GitLab Duo CLI 9.10.0에서 실험 기능으로 도입되었습니다.
GitLab 19.4 릴리스 기간에 GitLab Duo CLI 9.15.0에서 Agent Plugins 사양 지원이 도입되었습니다.

플러그인을 사용해 GitLab Duo CLI에 기능을 추가합니다.

플러그인은 GitLab Duo CLI용 확장을 묶어 놓은 디렉터리입니다. 플러그인에는 Agent Skills, 사용자 정의 슬래시 명령어, MCP 서버를 묶을 수 있습니다.

마켓플레이스는 Git 리포지터리 또는 로컬 디렉터리에 있는, 사용할 수 있는 플러그인의 카탈로그입니다. marketplace.json 파일에는 사용할 수 있는 플러그인과 그 위치가 나열됩니다.

플러그인을 사용하려면 해당 플러그인이 있는 마켓플레이스를 등록한 다음, 그 마켓플레이스에서 플러그인을 설치합니다. 플러그인은 <plugin>@<marketplace> 형식으로 식별됩니다.

기존 커뮤니티 플러그인 생태계와의 호환을 위해 GitLab Duo CLI는 .claude-plugin/marketplace.json 파일도 읽습니다. 기존 플러그인 마켓플레이스는 수정 없이 GitLab Duo CLI에서 동작합니다.

GitLab Duo CLI는 AI 에이전트 구성 요소를 패키징하기 위한 개방형 벤더 중립 표준인 Agent Plugins 사양을 따르는 플러그인도 지원합니다.

사전 요구 사항:

GitLab Duo CLI를 설정합니다.
Git 리포지터리에서 마켓플레이스를 추가하려면 Git.

마켓플레이스 등록#

플러그인을 설치하려면 먼저 해당 플러그인이 있는 마켓플레이스를 등록해야 합니다.

플러그인을 처음 사용할 때 GitLab Duo CLI는 공식 GitLab 마켓플레이스인 gitlab-duo-plugins를 자동으로 등록합니다. 이 마켓플레이스를 제거하면 GitLab Duo CLI는 다시 등록하지 않습니다.

마켓플레이스를 등록하려면 다음을 수행합니다.

glab duo plugin marketplace add <source>

duo plugin marketplace add <source>

<source>는 다음 중 하나입니다.

소스 유형	형식	예시
Git 리포지터리	`git clone`이 허용하는 URL입니다. 선택적으로 `#<ref>`를 붙여 브랜치나 태그를 고정할 수 있습니다.	`https://gitlab.com/group/marketplace.git#stable`
로컬 디렉터리	절대 경로 또는 상대 경로입니다. `~`는 홈 디렉터리로 확장됩니다.	`~/marketplaces/internal`

예를 들면 다음과 같습니다.

glab duo plugin marketplace add https://gitlab.com/example-group/example-marketplace.git

glab duo plugin marketplace add ~/marketplaces/internal

duo plugin marketplace add https://gitlab.com/example-group/example-marketplace.git

duo plugin marketplace add ~/marketplaces/internal

GitLab Duo CLI는 marketplace.json 파일의 name 필드로 마켓플레이스를 식별합니다.

마켓플레이스의 플러그인 자동 업데이트#

마켓플레이스에서 설치한 플러그인을 자동으로 업데이트하려면 --auto-update 옵션과 함께 마켓플레이스를 등록합니다.

glab duo plugin marketplace add <source> --auto-update

duo plugin marketplace add <source> --auto-update

GitLab Duo CLI가 시작되면 이 마켓플레이스에서 설치한 플러그인을 확인 없이 백그라운드에서 업데이트합니다. 플러그인이 업데이트되면 GitLab Duo CLI가 새 버전을 로드하도록 다시 시작하라고 안내합니다.

등록된 마켓플레이스 나열#

등록한 마켓플레이스를 나열하려면 다음을 수행합니다.

glab duo plugin marketplace list

duo plugin marketplace list

GitLab Duo CLI는 마켓플레이스마다 다음을 표시합니다.

마켓플레이스 소스.
마켓플레이스를 마지막으로 업데이트한 시점.
마켓플레이스가 보유한 플러그인 수.
마켓플레이스에 자동 업데이트가 활성화되어 있는지 여부.

사용 가능한 마켓플레이스 플러그인 나열#

마켓플레이스가 제공하는 플러그인을 나열하려면 다음을 수행합니다.

glab duo plugin marketplace show <name>

duo plugin marketplace show <name>

GitLab Duo CLI는 플러그인마다 버전, 설명, 설치되어 있다면 설치 위치를 표시합니다.

마켓플레이스 업데이트#

마켓플레이스의 카탈로그를 소스에서 새로 고치려면 다음을 수행합니다.

glab duo plugin marketplace update <name>

duo plugin marketplace update <name>

마켓플레이스 제거#

등록한 마켓플레이스를 제거하려면 다음을 수행합니다.

glab duo plugin marketplace remove <name>

duo plugin marketplace remove <name>

Warning

마켓플레이스를 제거하면 그 마켓플레이스에서 설치한 모든 플러그인도 함께 제거됩니다.

플러그인 설치 및 관리#

플러그인을 설치할 때 범위를 선택합니다. 범위에 따라 GitLab Duo CLI가 업데이트하는 구성 파일과 설치가 적용되는 대상이 결정됩니다.

범위	구성 파일	용도
`user`(기본값)	`<config dir>/plugins.json`	모든 프로젝트에 사용할 플러그인.
`project`	프로젝트의 `.gitlab/duo/plugins.json`	팀에서 공유하는 플러그인. 이 파일을 리포지터리에 커밋합니다.
`local`	프로젝트의 `.gitlab/duo/plugins.local.json`	프로젝트별 개인 플러그인. 이 파일을 `.gitignore`에 추가합니다.

<config dir>는 Linux와 macOS에서는 ~/.gitlab/duo, Windows에서는 %APPDATA%\GitLab\duo입니다.

등록한 마켓플레이스에서 플러그인을 설치하려면 다음을 수행합니다.

glab duo plugin install <plugin>@<marketplace> [--scope user|project|local]

duo plugin install <plugin>@<marketplace> [--scope user|project|local]

--scope를 지정하지 않으면 GitLab Duo CLI는 user 범위를 사용합니다.

예를 들면 다음과 같습니다.

glab duo plugin install my-plugin@my-marketplace

glab duo plugin install my-plugin@my-marketplace --scope project

duo plugin install my-plugin@my-marketplace

duo plugin install my-plugin@my-marketplace --scope project

설치 후 활성화 상태#

플러그인을 설치하면 GitLab Duo CLI는 해당 범위의 구성 파일에 플러그인의 활성화 여부를 기록합니다. GitLab Duo CLI는 초기 상태를 정할 때 다음을 우선순위 순으로 사용합니다.

대상 범위 또는 더 넓은 범위에서 해당 플러그인에 대해 이전에 기록한 활성화 또는 비활성화 설정. 예를 들어 플러그인을 비활성화하고 제거한 다음 다시 설치하면 플러그인은 비활성화 상태로 유지됩니다.
플러그인의 마켓플레이스 카탈로그 항목에 있는 defaultEnabled 값.
플러그인의 plugin.json 매니페스트에 있는 defaultEnabled 값.

이 중 어느 것도 설정되어 있지 않으면 플러그인은 활성화됩니다.

설치된 플러그인 나열#

설치한 플러그인을 나열하려면 다음을 수행합니다.

glab duo plugin list

duo plugin list

설치된 플러그인은 범위별로 묶여 표시되며, 목록에는 각 플러그인의 활성화 여부가 나타납니다.

플러그인 활성화 또는 비활성화#

플러그인을 활성화, 비활성화, 제거할 때는 이름만으로 지정할 수 있습니다. 같은 이름의 플러그인이 여러 마켓플레이스에서 설치되어 있으면 전체 <plugin>@<marketplace> 식별자를 사용합니다.

설치된 플러그인을 활성화하거나 비활성화하려면 다음을 수행합니다.

glab duo plugin enable <plugin> [--scope user|project|local]
glab duo plugin disable <plugin> [--scope user|project|local]

duo plugin enable <plugin> [--scope user|project|local]
duo plugin disable <plugin> [--scope user|project|local]

여러 범위에서 플러그인을 활성화하거나 비활성화하면 가장 구체적인 범위가 우선합니다. local, project, user 순입니다.

플러그인 업데이트#

플러그인을 마켓플레이스에서 제공하는 최신 버전으로 업데이트하려면 다음을 수행합니다.

glab duo plugin update <plugin>@<marketplace>

duo plugin update <plugin>@<marketplace>

업데이트는 해당 플러그인이 설치된 모든 범위에 적용됩니다.

플러그인 제거#

플러그인을 제거하려면 다음을 수행합니다.

glab duo plugin uninstall <plugin> [--scope user|project|local]

duo plugin uninstall <plugin> [--scope user|project|local]

제거하면 구성에서 플러그인이 삭제됩니다.

설치된 플러그인 사용#

플러그인을 설치하고 활성화하면 GitLab Duo CLI는 다음에 시작할 때 그 플러그인이 묶고 있는 모든 항목을 검색합니다.

스킬은 다른 Agent Skills와 같은 방식으로 사용할 수 있게 됩니다.
사용자 정의 슬래시 명령어는 슬래시 명령어 메뉴에 표시됩니다. 기본 제공 슬래시 명령어, Agent Skills 슬래시 명령어, 직접 만든 사용자 정의 슬래시 명령어가 이름이 같은 플러그인 명령어보다 우선합니다.
MCP 서버는 직접 구성한 MCP 서버와 함께 로드되며, 같은 방식으로 도구 승인이 필요합니다. 서버의 출처를 알 수 있도록 GitLab Duo CLI는 서버 이름 앞에 플러그인 이름을 붙입니다.

마켓플레이스 만들기#

마켓플레이스를 만들려면 Git 리포지터리 또는 로컬 디렉터리의 루트에 marketplace.json 파일을 추가합니다. 예를 들면 다음과 같습니다.

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "A short description of the plugin."
    }
  ]
}

plugins의 각 항목은 source를 마켓플레이스 루트에 대한 상대 경로로 설정해야 하며, 경로는 ./로 시작해야 합니다.

플러그인 만들기#

플러그인은 선택적인 plugin.json 매니페스트와 그 플러그인이 묶는 확장(스킬, 사용자 정의 슬래시 명령어, MCP 서버)을 담은 디렉터리입니다.

plugin.json 매니페스트는 다음 필드를 지원합니다.

필드	필수 여부	설명
`name`	예	플러그인의 이름입니다.
`version`	아니요	플러그인의 버전입니다.
`description`	아니요	플러그인에 대한 짧은 설명입니다.
`defaultEnabled`	아니요	설치 시 플러그인이 기본적으로 활성화되는지 여부입니다.

예를 들면 다음과 같습니다.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A short description of the plugin.",
  "defaultEnabled": true
}

기존 커뮤니티 플러그인과의 호환을 위해 GitLab Duo CLI는 .claude-plugin/plugin.json에서도 매니페스트를 읽습니다.

플러그인에 확장을 묶으려면 다음을 수행합니다.

스킬: 플러그인의 skills/<skill-name>/ 디렉터리에 SKILL.md 파일을 추가합니다. SKILL.md 파일 형식은 스킬 만들기를 참고합니다.
사용자 정의 슬래시 명령어: 플러그인의 commands/ 디렉터리에 Markdown 파일을 추가합니다. 파일 이름이 명령어 이름이 되고, 파일 형식은 사용자 정의 슬래시 명령어와 같습니다.
MCP 서버:
- 권장: 플러그인 루트에 Agent Plugins 사양에서 정의한 형식으로 mcp.json 파일을 추가합니다. 플러그인 내부의 파일을 참조할 때는 ${PLUGIN_ROOT} 변수를 사용하고, 플러그인 업데이트 후에도 유지되는 쓰기 가능한 디렉터리에는 ${PLUGIN_DATA} 변수를 사용합니다.
- 기존 커뮤니티 플러그인과의 호환을 위해 대신 .mcp.json 파일을 MCP 구성 형식과 같은 형식으로 추가할 수도 있습니다. 플러그인 내부의 파일을 참조할 때는 ${DUO_PLUGIN_ROOT} 변수를 사용합니다.
플러그인에 mcp.json과 .mcp.json이 모두 있으면 GitLab Duo CLI는 mcp.json만 사용합니다.

예를 들어 스킬, 사용자 정의 슬래시 명령어, MCP 서버를 묶은 플러그인 하나가 있는 마켓플레이스 리포지터리는 다음과 같습니다.

my-marketplace/
├── marketplace.json
└── plugins/
    └── my-plugin/
        ├── plugin.json
        ├── mcp.json
        ├── commands/
        │   └── my-command.md
        └── skills/
            └── my-skill/
                └── SKILL.md

GitLab Duo CLI는 플러그인의 버전을 다음 우선순위 순으로 결정합니다.

플러그인의 plugin.json에 있는 version 필드.
마켓플레이스 marketplace.json의 플러그인 항목에 있는 version 필드.

어느 필드도 설정되어 있지 않으면 플러그인의 버전은 unknown입니다.

GitLab Duo CLI 사용자 정의

GitLab v19.4

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-09-18

요약

히스토리

사용자 수준 Agent Skills를 활성화하는 환경 변수와 옵션이 GitLab 19.0 릴리스 기간에 GitLab Duo CLI 8.83.0에서 실험 기능으로 도입되었습니다.

GitLab Duo CLI는 다음과 같은 사용자 정의를 지원합니다.

훅을 사용해 GitLab Duo CLI 수명 주기의 특정 시점에 사용자 정의 명령을 실행합니다.
사용자 정의 슬래시 명령어를 사용해 CLI를 워크플로나 사용 사례에 더 맞춥니다.
플러그인을 사용해 마켓플레이스에서 Agent Skills, 사용자 정의 슬래시 명령어, Model Context Protocol(MCP) 서버를 설치합니다.
GitLab Duo Agent Platform에 설정한 사용자 정의 지침을 사용해 워크플로, 코딩 표준, 프로젝트 요구 사항에 맞춥니다.

훅#

히스토리

GitLab 19.1 릴리스 기간에 GitLab Duo CLI 8.95.0에서 실험 기능으로 도입되었습니다.

훅을 사용해 GitLab Duo CLI 수명 주기의 특정 시점에 사용자 정의 명령을 실행합니다.

예를 들어 환경 정보를 수집하는 스크립트를 실행해 새 채팅 세션마다 추가 컨텍스트를 주입할 수 있습니다.

GitLab Duo CLI는 두 수준에서 훅을 지원합니다.

사용자 수준(전역): 모든 프로젝트에 적용됩니다.
프로젝트 수준: 특정 프로젝트에만 적용됩니다. 프로젝트 수준 훅은 체크아웃한 리포지터리의 임의 코드가 실행되는 것을 막기 위해 기본적으로 비활성화되어 있습니다.

사용자 수준과 프로젝트 수준 hooks.json 파일이 모두 있으면 CLI가 훅을 병합하고 사용자 수준 훅을 먼저 실행합니다.

Note

보안상의 이유로 민감한 환경 변수(GITLAB_TOKEN, GITLAB_OAUTH_TOKEN, CI_JOB_TOKEN)는 훅 프로세스에서 제외됩니다.

훅 실행#

훅이 실행되면 GitLab Duo CLI는 다음을 수행합니다.

세션 메타데이터가 담긴 JSON 객체를 명령의 표준 입력으로 전송합니다.

{
  "session_id": "abc-123",
  "cwd": "/path/to/project",
  "transcript_path": "",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

훅 프로세스에 환경 변수 DUO_SESSION_ID와 DUO_PROJECT_DIR를 설정합니다.
명령의 표준 출력을 세션의 추가 컨텍스트로 수집합니다.

훅은 표준 출력으로 일반 텍스트 또는 JSON 객체를 반환할 수 있습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Your context string here"
  }
}

훅이 0이 아닌 상태로 종료되거나 시간이 초과되면 경고로 기록되지만, 세션이 시작되는 것을 막지는 않습니다.

훅 만들기#

GitLab Duo CLI는 새 세션이 시작되거나 기존 세션이 다시 시작될 때 실행되는 SessionStart 이벤트를 지원합니다.

훅을 만들려면 다음을 수행합니다.

hooks.json 파일을 만듭니다.
- 사용자 수준 훅의 경우:
  - Linux 또는 macOS에서는 ~/.gitlab/duo/hooks.json에 파일을 만듭니다.
  - Windows에서는 %APPDATA%\GitLab\duo\hooks.json에 파일을 만듭니다.
- 프로젝트 수준 훅의 경우 프로젝트 루트에 파일을 만듭니다: <project>/.gitlab/duo/hooks.json.

파일에 훅을 정의합니다.

훅을 트리거해야 하는 SessionStart 이벤트 소스(startup 또는 resume)마다 matcher 그룹을 만듭니다.

각 matcher 그룹에는 선택적인 정규식 matcher 값과 명령 훅 배열이 있습니다.

필드	설명
`matcher`	선택 사항. 이벤트 소스(`SessionStart`의 경우 `startup` 또는 `resume`)에 대해 검사하는 정규식입니다. 모두 일치시키려면 생략합니다.
`hooks[].type`	`"command"`여야 합니다.
`hooks[].command`	실행할 셸 명령입니다.
`hooks[].timeout`	선택 사항. 초 단위 시간 제한입니다. 기본값: 30.

예를 들면 다음과 같습니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.my-coding-preferences.md",
            "timeout": 10
          }
        ]
     }
    ]
  }
}

프로젝트 수준 훅이 있으면 GitLab Duo CLI를 시작할 때 활성화합니다.

   glab duo cli --enable-project-hooks

   duo --enable-project-hooks

또는 환경 변수를 설정합니다.

export GITLAB_ENABLE_PROJECT_HOOKS=true

사용자 정의 슬래시 명령어#

히스토리

GitLab 19.2 릴리스 기간에 GitLab Duo CLI 9.2.0에서 도입되었습니다.

자주 사용하는 프롬프트를 위한 사용자 정의 슬래시 명령어를 만듭니다.

GitLab Duo CLI는 두 수준에서 사용자 정의 슬래시 명령어를 지원합니다.

사용자 수준: 모든 프로젝트에 적용됩니다.
프로젝트 수준: 특정 프로젝트에만 적용됩니다.

사용자 정의 슬래시 명령어 만들기#

사용자 정의 슬래시 명령어를 만들려면 Markdown 파일을 만듭니다.

파일 이름이 명령어 이름이 되고, 파일 콘텐츠가 프롬프트가 됩니다.

예를 들어 daily.md라는 파일은 /daily 명령어를 만듭니다.

commands 디렉터리를 만듭니다.
- 프로젝트 수준 명령어의 경우 프로젝트 루트에 디렉터리를 만듭니다: <project>/.agents/commands/.
- 사용자 수준 명령어의 경우 다음 위치 중 하나를 사용합니다.
  - 다른 GitLab Duo 사용자 정의 파일과 함께 명령어를 보관하려면:
    - Linux 또는 macOS에서는 ~/.gitlab/duo/commands/에 디렉터리를 만듭니다.
    - Windows에서는 %APPDATA%\GitLab\duo\commands\에 디렉터리를 만듭니다.
    - GLAB_CONFIG_DIR 또는 XDG_CONFIG_HOME을 설정했다면 $GLAB_CONFIG_DIR/commands/ 또는 $XDG_CONFIG_HOME/gitlab/duo/commands/를 사용합니다. 둘 다 설정했다면 GLAB_CONFIG_DIR가 우선합니다.
  - 다른 AI 도구와 명령어를 공유하려면:
    - Linux 또는 macOS에서는 ~/.agents/commands/에 디렉터리를 만듭니다.
    - Windows에서는 %USERPROFILE%\.agents\commands\에 디렉터리를 만듭니다.
그 디렉터리에 Markdown 파일을 만듭니다. 파일 이름으로 명령어 이름을 사용합니다. 명령어 이름은 문자 또는 숫자로 시작해야 하며, 문자, 숫자, 하이픈, 밑줄만 포함할 수 있습니다.
파일에 프롬프트를 추가합니다.
선택 사항. 파일 맨 위의 YAML front matter에 description 필드를 추가합니다. 이 설명은 슬래시 명령어 메뉴에서 명령어 옆에 표시됩니다.

예를 들어 daily.md에 정의한 /daily 명령어는 다음과 같습니다.
```
---
description: Prepare a daily report
---

Use `glab todo list` to fetch my open TODO items. Give me a concise morning report ranked by priority.
```
GitLab Duo CLI를 다시 시작합니다. CLI는 시작할 때 사용자 정의 슬래시 명령어를 검색합니다.

사용자 정의 슬래시 명령어 사용#

대화형 모드에서는 프롬프트에 슬래시 명령어를 입력하고 Enter를 누릅니다. GitLab Duo CLI는 파일 콘텐츠를 프롬프트로 전송합니다.

명령어 이름 뒤에 입력한 텍스트는 프롬프트 끝에 추가됩니다.

추가 텍스트를 사용해 사용자 정의 슬래시 명령어의 동작을 조정합니다.

예를 들면 /daily prioritize my milestone deliverables입니다.

플러그인#

히스토리

GitLab 19.3 릴리스 기간에 GitLab Duo CLI 9.10.0에서 실험 기능으로 도입되었습니다.
GitLab 19.4 릴리스 기간에 GitLab Duo CLI 9.15.0에서 Agent Plugins 사양 지원이 도입되었습니다.

플러그인을 사용해 GitLab Duo CLI에 기능을 추가합니다.

플러그인은 GitLab Duo CLI용 확장을 묶어 놓은 디렉터리입니다. 플러그인에는 Agent Skills, 사용자 정의 슬래시 명령어, MCP 서버를 묶을 수 있습니다.

GitLab Duo CLI는 AI 에이전트 구성 요소를 패키징하기 위한 개방형 벤더 중립 표준인 Agent Plugins 사양을 따르는 플러그인도 지원합니다.

사전 요구 사항:

GitLab Duo CLI를 설정합니다.
Git 리포지터리에서 마켓플레이스를 추가하려면 Git.

마켓플레이스 등록#

플러그인을 설치하려면 먼저 해당 플러그인이 있는 마켓플레이스를 등록해야 합니다.

마켓플레이스를 등록하려면 다음을 수행합니다.

glab duo plugin marketplace add <source>

duo plugin marketplace add <source>

<source>는 다음 중 하나입니다.

소스 유형	형식	예시
Git 리포지터리	`git clone`이 허용하는 URL입니다. 선택적으로 `#<ref>`를 붙여 브랜치나 태그를 고정할 수 있습니다.	`https://gitlab.com/group/marketplace.git#stable`
로컬 디렉터리	절대 경로 또는 상대 경로입니다. `~`는 홈 디렉터리로 확장됩니다.	`~/marketplaces/internal`

예를 들면 다음과 같습니다.

glab duo plugin marketplace add https://gitlab.com/example-group/example-marketplace.git

glab duo plugin marketplace add ~/marketplaces/internal

duo plugin marketplace add https://gitlab.com/example-group/example-marketplace.git

duo plugin marketplace add ~/marketplaces/internal

GitLab Duo CLI는 marketplace.json 파일의 name 필드로 마켓플레이스를 식별합니다.

마켓플레이스의 플러그인 자동 업데이트#

마켓플레이스에서 설치한 플러그인을 자동으로 업데이트하려면 --auto-update 옵션과 함께 마켓플레이스를 등록합니다.

glab duo plugin marketplace add <source> --auto-update

duo plugin marketplace add <source> --auto-update

등록된 마켓플레이스 나열#

등록한 마켓플레이스를 나열하려면 다음을 수행합니다.

glab duo plugin marketplace list

duo plugin marketplace list

GitLab Duo CLI는 마켓플레이스마다 다음을 표시합니다.

마켓플레이스 소스.
마켓플레이스를 마지막으로 업데이트한 시점.
마켓플레이스가 보유한 플러그인 수.
마켓플레이스에 자동 업데이트가 활성화되어 있는지 여부.

사용 가능한 마켓플레이스 플러그인 나열#

마켓플레이스가 제공하는 플러그인을 나열하려면 다음을 수행합니다.

glab duo plugin marketplace show <name>

duo plugin marketplace show <name>

GitLab Duo CLI는 플러그인마다 버전, 설명, 설치되어 있다면 설치 위치를 표시합니다.

마켓플레이스 업데이트#

마켓플레이스의 카탈로그를 소스에서 새로 고치려면 다음을 수행합니다.

glab duo plugin marketplace update <name>

duo plugin marketplace update <name>

마켓플레이스 제거#

등록한 마켓플레이스를 제거하려면 다음을 수행합니다.

glab duo plugin marketplace remove <name>

duo plugin marketplace remove <name>

Warning

마켓플레이스를 제거하면 그 마켓플레이스에서 설치한 모든 플러그인도 함께 제거됩니다.

플러그인 설치 및 관리#

플러그인을 설치할 때 범위를 선택합니다. 범위에 따라 GitLab Duo CLI가 업데이트하는 구성 파일과 설치가 적용되는 대상이 결정됩니다.

범위	구성 파일	용도
`user`(기본값)	`<config dir>/plugins.json`	모든 프로젝트에 사용할 플러그인.
`project`	프로젝트의 `.gitlab/duo/plugins.json`	팀에서 공유하는 플러그인. 이 파일을 리포지터리에 커밋합니다.
`local`	프로젝트의 `.gitlab/duo/plugins.local.json`	프로젝트별 개인 플러그인. 이 파일을 `.gitignore`에 추가합니다.

<config dir>는 Linux와 macOS에서는 ~/.gitlab/duo, Windows에서는 %APPDATA%\GitLab\duo입니다.

등록한 마켓플레이스에서 플러그인을 설치하려면 다음을 수행합니다.

glab duo plugin install <plugin>@<marketplace> [--scope user|project|local]

duo plugin install <plugin>@<marketplace> [--scope user|project|local]

--scope를 지정하지 않으면 GitLab Duo CLI는 user 범위를 사용합니다.

예를 들면 다음과 같습니다.

glab duo plugin install my-plugin@my-marketplace

glab duo plugin install my-plugin@my-marketplace --scope project

duo plugin install my-plugin@my-marketplace

duo plugin install my-plugin@my-marketplace --scope project

설치 후 활성화 상태#

대상 범위 또는 더 넓은 범위에서 해당 플러그인에 대해 이전에 기록한 활성화 또는 비활성화 설정. 예를 들어 플러그인을 비활성화하고 제거한 다음 다시 설치하면 플러그인은 비활성화 상태로 유지됩니다.
플러그인의 마켓플레이스 카탈로그 항목에 있는 defaultEnabled 값.
플러그인의 plugin.json 매니페스트에 있는 defaultEnabled 값.

이 중 어느 것도 설정되어 있지 않으면 플러그인은 활성화됩니다.

설치된 플러그인 나열#

설치한 플러그인을 나열하려면 다음을 수행합니다.

glab duo plugin list

duo plugin list

설치된 플러그인은 범위별로 묶여 표시되며, 목록에는 각 플러그인의 활성화 여부가 나타납니다.

플러그인 활성화 또는 비활성화#

설치된 플러그인을 활성화하거나 비활성화하려면 다음을 수행합니다.

glab duo plugin enable <plugin> [--scope user|project|local]
glab duo plugin disable <plugin> [--scope user|project|local]

duo plugin enable <plugin> [--scope user|project|local]
duo plugin disable <plugin> [--scope user|project|local]

여러 범위에서 플러그인을 활성화하거나 비활성화하면 가장 구체적인 범위가 우선합니다. local, project, user 순입니다.

플러그인 업데이트#

플러그인을 마켓플레이스에서 제공하는 최신 버전으로 업데이트하려면 다음을 수행합니다.

glab duo plugin update <plugin>@<marketplace>

duo plugin update <plugin>@<marketplace>

업데이트는 해당 플러그인이 설치된 모든 범위에 적용됩니다.

플러그인 제거#

플러그인을 제거하려면 다음을 수행합니다.

glab duo plugin uninstall <plugin> [--scope user|project|local]

duo plugin uninstall <plugin> [--scope user|project|local]

제거하면 구성에서 플러그인이 삭제됩니다.

설치된 플러그인 사용#

플러그인을 설치하고 활성화하면 GitLab Duo CLI는 다음에 시작할 때 그 플러그인이 묶고 있는 모든 항목을 검색합니다.

스킬은 다른 Agent Skills와 같은 방식으로 사용할 수 있게 됩니다.
사용자 정의 슬래시 명령어는 슬래시 명령어 메뉴에 표시됩니다. 기본 제공 슬래시 명령어, Agent Skills 슬래시 명령어, 직접 만든 사용자 정의 슬래시 명령어가 이름이 같은 플러그인 명령어보다 우선합니다.
MCP 서버는 직접 구성한 MCP 서버와 함께 로드되며, 같은 방식으로 도구 승인이 필요합니다. 서버의 출처를 알 수 있도록 GitLab Duo CLI는 서버 이름 앞에 플러그인 이름을 붙입니다.

마켓플레이스 만들기#

마켓플레이스를 만들려면 Git 리포지터리 또는 로컬 디렉터리의 루트에 marketplace.json 파일을 추가합니다. 예를 들면 다음과 같습니다.

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "A short description of the plugin."
    }
  ]
}

plugins의 각 항목은 source를 마켓플레이스 루트에 대한 상대 경로로 설정해야 하며, 경로는 ./로 시작해야 합니다.

플러그인 만들기#

플러그인은 선택적인 plugin.json 매니페스트와 그 플러그인이 묶는 확장(스킬, 사용자 정의 슬래시 명령어, MCP 서버)을 담은 디렉터리입니다.

plugin.json 매니페스트는 다음 필드를 지원합니다.

필드	필수 여부	설명
`name`	예	플러그인의 이름입니다.
`version`	아니요	플러그인의 버전입니다.
`description`	아니요	플러그인에 대한 짧은 설명입니다.
`defaultEnabled`	아니요	설치 시 플러그인이 기본적으로 활성화되는지 여부입니다.

예를 들면 다음과 같습니다.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A short description of the plugin.",
  "defaultEnabled": true
}

기존 커뮤니티 플러그인과의 호환을 위해 GitLab Duo CLI는 .claude-plugin/plugin.json에서도 매니페스트를 읽습니다.

플러그인에 확장을 묶으려면 다음을 수행합니다.

스킬: 플러그인의 skills/<skill-name>/ 디렉터리에 SKILL.md 파일을 추가합니다. SKILL.md 파일 형식은 스킬 만들기를 참고합니다.
사용자 정의 슬래시 명령어: 플러그인의 commands/ 디렉터리에 Markdown 파일을 추가합니다. 파일 이름이 명령어 이름이 되고, 파일 형식은 사용자 정의 슬래시 명령어와 같습니다.
MCP 서버:
- 권장: 플러그인 루트에 Agent Plugins 사양에서 정의한 형식으로 mcp.json 파일을 추가합니다. 플러그인 내부의 파일을 참조할 때는 ${PLUGIN_ROOT} 변수를 사용하고, 플러그인 업데이트 후에도 유지되는 쓰기 가능한 디렉터리에는 ${PLUGIN_DATA} 변수를 사용합니다.
- 기존 커뮤니티 플러그인과의 호환을 위해 대신 .mcp.json 파일을 MCP 구성 형식과 같은 형식으로 추가할 수도 있습니다. 플러그인 내부의 파일을 참조할 때는 ${DUO_PLUGIN_ROOT} 변수를 사용합니다.
플러그인에 mcp.json과 .mcp.json이 모두 있으면 GitLab Duo CLI는 mcp.json만 사용합니다.

예를 들어 스킬, 사용자 정의 슬래시 명령어, MCP 서버를 묶은 플러그인 하나가 있는 마켓플레이스 리포지터리는 다음과 같습니다.

my-marketplace/
├── marketplace.json
└── plugins/
    └── my-plugin/
        ├── plugin.json
        ├── mcp.json
        ├── commands/
        │   └── my-command.md
        └── skills/
            └── my-skill/
                └── SKILL.md

GitLab Duo CLI는 플러그인의 버전을 다음 우선순위 순으로 결정합니다.

플러그인의 plugin.json에 있는 version 필드.
마켓플레이스 marketplace.json의 플러그인 항목에 있는 version 필드.

어느 필드도 설정되어 있지 않으면 플러그인의 버전은 unknown입니다.

GitLab Duo CLI 사용자 정의

훅#

훅 실행#

훅 만들기#

사용자 정의 슬래시 명령어#

사용자 정의 슬래시 명령어 만들기#

사용자 정의 슬래시 명령어 사용#

플러그인#

마켓플레이스 등록#

마켓플레이스의 플러그인 자동 업데이트#

등록된 마켓플레이스 나열#

사용 가능한 마켓플레이스 플러그인 나열#

마켓플레이스 업데이트#

마켓플레이스 제거#

플러그인 설치 및 관리#

설치 후 활성화 상태#

설치된 플러그인 나열#

플러그인 활성화 또는 비활성화#

플러그인 업데이트#

플러그인 제거#

설치된 플러그인 사용#

마켓플레이스 만들기#

플러그인 만들기#

관련 주제#

GitLab Duo CLI 사용자 정의

훅#

훅 실행#

훅 만들기#

사용자 정의 슬래시 명령어#

사용자 정의 슬래시 명령어 만들기#

사용자 정의 슬래시 명령어 사용#

플러그인#

마켓플레이스 등록#

마켓플레이스의 플러그인 자동 업데이트#

등록된 마켓플레이스 나열#

사용 가능한 마켓플레이스 플러그인 나열#

마켓플레이스 업데이트#

마켓플레이스 제거#

플러그인 설치 및 관리#

설치 후 활성화 상태#

설치된 플러그인 나열#

플러그인 활성화 또는 비활성화#

플러그인 업데이트#

플러그인 제거#

설치된 플러그인 사용#

마켓플레이스 만들기#

플러그인 만들기#

관련 주제#