사용자 정의 명령

사용자 정의 명령 (Custom Commands)

프롬프트를 보내거나, URL을 열거나, 에이전트를 전환하는 슬래시 명령을 정의해요.

출처: 문서

본문

슬래시 명령이란 무엇인가? (What Slash Commands Are)

슬래시 명령은 사용자가 전체 프롬프트를 타이핑하는 대신 TUI(/df, /deploy, /plan)나 CLI(docker agent run agent.yaml /df)에서 타이핑하는 이름 있는 단축키예요. 모든 에이전트는 commands: 아래에 자신만의 명령을 선언할 수 있고, 최상위 commands: 그룹은 여러 에이전트가 복제 없이 같은 집합을 공유하게 해줘요.

에이전트가 바쁜 동안 큐에 쌓이는 일반 채팅 메시지와 달리, 슬래시 명령(내장 및 이름 있는 모두)은 응답 중에도 즉시 실행돼요.

명령은 세 가지 형태로 나뉘어요:

Important 프론트엔드별로 동작이 달라요 (Behavior differs by frontend) url 과 agent 는 전체 TUI에서만 완전히 존중돼요. 전체 TUI는 agent 보다 url 을 먼저 확인해요(URL 명령은 브라우저를 열고 거기서 멈추고; 에이전트 전환 명령은 지침을 보내기 전에 전환해요). lean TUI는 두 필드를 특별 취급하지 않아요 — 명령의 확장된 텍스트만 해석해 채팅 메시지로 보내요. 그래서 URL 전용 명령은 슬래시 뒤의 후행 텍스트를(보통 아무것도 없어 브라우저를 열지 않음) 조용히 보내고, 에이전트 전환 명령은 대상 대신 현재 에이전트에 지침을 보내요. CLI(docker agent run agent.yaml /command)는 전체 TUI처럼 에이전트를 전환하지만 열 브라우저가 없어서 url 은 효과가 없어요. HTTP API(POST /api/sessions/:id/agent/:agent)는 서버 측에서 에이전트 전환 명령을 해석해요: 메시지 내용이 agent 필드가 설정된 슬래시 명령으로 시작하면 활성 에이전트가 전환되고 턴이 돌기 전에 메시지가 다시 쓰여요. 프롬프트 전용 및 URL 명령은 서버 측에서 해석되지 않고 모델로 변경 없이 전달돼요.

프롬프트 명령 (Prompt Commands)

가장 단순한 형태: 현재 에이전트로 보내지는 지침이 되는 문자열 값.

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A system administrator assistant.
    instruction: You are a system administrator.
    commands:
      df: "Check how much free space I have on my disk"
      logs: "Show me the last 50 lines of system logs"
      greet: "Say hello to ${env.USER}"

더 제어하려면 instruction: 필드가 있는 객체 형태를, 완성 대화상자와 도움말 텍스트에 표시되는 선택적 description: 과 함께 사용해요:

commands:
  deploy:
    description: "Deploy the application to staging"
    instruction: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}"

명령은 환경 변수 보간용 JavaScript 템플릿 리터럴 구문(${env.VAR})을 지원하며, 선택적 || 기본값과 삼항 표현식이 있어요 — 에이전트의 instruction 과 description 과 같은 구문이에요. 정의되지 않은 변수는 빈 문자열로 확장돼요. 전체 그림은 Variable Expansion in Config Fields 참고.

프롬프트 명령은 슬래시 뒤에 타이핑된 텍스트를 참조하고 도구를 호출할 수도 있는데, ${env.VAR} 와 같은 ${...} 확장 엔진을 사용해요:

• ${args[0]}, ${args[1]}, … — 개별 위치 인자 (공백으로 토큰화; 따옴표가 붙은 하위 문자열은 공백을 유지).
• ${args} 또는 ${args.join(" ")} — 전체 인자 목록.
• ${tool_name({key: value, ...})} — 에이전트 도구를 호출하고 그 출력을 인라인. JS 표현식은 도구 명령보다 먼저 평가되므로, 도구 출력이 JS로 재평가되지 않아요.
• !tool_name(key=value) — 같은 도구 호출 인라인을 위한 레거시 bang 구문; ${tool_name({...})} 옆에 여전히 지원.

instruction 이 ${args...} 플레이스홀더 중 어느 것도 사용하지 않으면, 슬래시 뒤에 타이핑된 텍스트가 자동으로 해석된 지침에 추가돼요.

commands:
  fix:
    description: "Fix a file, with optional extra options"
    instruction: "Fix the file ${args[0]} with options ${args[1]}"
  run:
    description: "Run a command with all the typed arguments"
    instruction: 'Run command with args: ${args.join(" ")}'
  lint:
    description: "Show the current lint output"
    instruction: 'Lint: ${shell({cmd: "task lint"})}'

# Run commands from the CLI too
$ docker agent run agent.yaml /df
$ docker agent run agent.yaml /greet
$ docker agent run agent.yaml /fix main.go --verbose
$ PROJECT_NAME=myapp ENV=production docker agent run agent.yaml /deploy

URL 명령 (URL Commands)

url 필드가 있는 명령은 에이전트에 프롬프트를 보내는 대신 사용자의 기본 브라우저에서 그 URL을 열어요. OS가 디스패치하는 법을 아는 어떤 URI 스킴이든 동작해요 — 표준 웹 URL과, 딥 링크용 docker-desktop:// 같은 커스텀 스킴 모두요.

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: An agent with handy URL shortcuts.
    instruction: You are a helpful assistant.
    commands:
      feedback:
        description: "Open the feedback site for this session"
        url: https://example.com/feedback?session={{session_id}}
      docs:
        description: "Open the documentation"
        url: https://docs.docker.com/
      desktop:
        description: "Open this session in Docker Desktop"
        url: docker-desktop://dashboard/session/{{session_id}}

{{session_id}} 토큰은 호출 시점에 현재 세션 ID로 대체돼요(URL을 깨뜨리거나 추가 쿼리 파라미터를 주입할 수 없도록 URL-쿼리 이스케이프됨). 그래서 명령이 대화에 범위가 한정된 무언가로 딥링크할 수 있게 해요. 이 토큰은 의도적으로 ${...} JS-확장 구문이 아닌 {{...}} 를 사용해요, 세션 ID가 디스패치 시점에만 알려지기 때문이에요.

URL은 OS 오프너에 넘기기 전에 검증돼요: 비어 있지 않은 스킴이 있는 파싱 가능한 URL이 요구되고, 플래그 같은 입력(- 로 시작하는 것)은 인자 주입을 막기 위해 거부돼요.

Note 전체 TUI 전용 (Full TUI only) URL 명령은 전체 TUI에서만 브라우저를 열어요. CLI와 lean TUI는 url 필드를 전혀 확인하지 않아서, 거기서 docker agent run agent.yaml /docs 는 브라우저를 열지 않아요 — 하지만 명령은 여전히 디스패치돼요: 해석된 텍스트(URL 전용 명령이라 보통 비어 있음)가 프롬프트로 보내져 모델 턴을 트리거할 수 있어요.

완전한 예제는 examples/url_commands.yaml 참고.

에이전트 전환 명령 (Agent-Switching Commands)

agent 필드가 있는 명령은 대화의 나머지 동안 활성 에이전트를 전환해요. /plan, /review, /deploy 가 각각 사용자를 올바른 전문가에게 라우팅하는 워크플로 단축키를 만드는 데 유용해요.

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Main assistant
    instruction: You are a project coordinator.
    sub_agents: [planner, reviewer]
    commands:
      # Switch to planner with a pre-filled prompt
      plan:
        agent: planner
        instruction: "Create a detailed plan for: ${args.join(' ')}"
      # Switch to reviewer; any text after /review is forwarded
      review:
        agent: reviewer

  planner:
    model: anthropic/claude-sonnet-4-5
    description: Planning specialist
    instruction: You create detailed project plans.

  reviewer:
    model: anthropic/claude-sonnet-4-5
    description: Code review specialist
    instruction: You review code and suggest improvements.

instruction 없이 agent 가 설정되면, 슬래시 명령 뒤에 타이핑된 어떤 텍스트든(예: /review fix the auth bug) 대상 에이전트에게 프롬프트로 전달돼요. 둘 다 설정되면 에이전트가 먼저 전환된 뒤 지침이 새 에이전트로 보내져요. 어느 경우든 대상은 팀에 정의된 어떤 에이전트든 될 수 있어요 — 현재 에이전트 자신의 sub_agents 중 하나만이 아니라요. 위의 sub_agents 는 planner 와 reviewer 가 우연히 위임 대상이기도 하기 때문에 보여준 것일 뿐, agent: 가 그것을 요구하기 때문은 아니에요.

에이전트 전환은 같은 세션에 머물러요 — 대상 에이전트가 전체 대화 기록을 보고, 사용자가 명시적으로 다시 전환해야 해요(자동 복귀 없음). 이것은 에이전트가 작업을 넘기는 다른 두 방법과 달라요:

깨끗한 결과와 함께 위임을 원하면 transfer_task(sub_agents 를 통해)를 사용하고, 대화의 나머지 동안 다른 에이전트가 되기를 원하면 에이전트 전환 명령을 사용하세요.

완전한 예제는 examples/agent_switching_commands.yaml 참고.

재사용 가능한 명령 그룹 (Reusable Command Groups)

에이전트 전반에 걸친 반복 명령 집합은 최상위 commands: 섹션으로 끌어올리고 use_commands: 로 이름으로 가져올 수 있어요 — MCP 서버용 mcps:, 공유 toolset용 toolsets: 과 같은 재사용 패턴이에요.

commands:
  ci:
    deploy: "Deploy the application"
    test: "Run the test suite"

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Lead developer
    instruction: You are the lead developer. Coordinate the team.
    use_commands: [ci] # reuse the "ci" command group
    commands:
      lint: "Run the linter" # inline command, merged in (wins on conflict)

  docs-writer:
    model: anthropic/claude-sonnet-4-5
    description: Documentation writer
    instruction: You write and maintain the project documentation.
    use_commands: [ci] # same group, reused without duplication

에이전트 자신의 인라인 commands: 항목은 이름 충돌 시 병합된 use_commands: 항목보다 우선해요. 동등한 skills: / use_skills: 패턴도 다루는 완전한 예제는 examples/shared-commands-skills.yaml 참고.

명령 숨기기 (Hiding Commands)

--disable-commands 를 사용해 TUI에서 특정 슬래시 명령을 숨기고 비활성화해요 — 내장된 것(/cost, /eval, /model, …)이나 자신의 이름 있는 명령. 쉼표로 구분된 목록을 받고, 선행 슬래시는 선택이며 일치는 대소문자를 구분하지 않아요.

$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model"

이것은 더 좁은 명령 표면을 가진 배포된 에이전트를 제공하는 데 유용해요 — 예를 들어 게시된 에이전트가 항상 의도한 모델로 실행되도록 /model 을 숨기는 것.

내장 명령 (Built-in Commands)

TUI는 에이전트가 정의하는 것과 함께 자체 슬래시 명령(/new, /compact, /sessions, /settings, …)을 제공해요. 전체 목록은 TUI 참조의 Slash Commands 참고.

명령 구성 참조 (Command Configuration Reference)

instruction 과 agent 는 결합할 수 있어요(에이전트가 먼저 전환된 뒤 지침이 새 에이전트로 보내짐). 전체 TUI에서 url 이 설정되면 agent 와 instruction 보다 우선해요 — 명령은 브라우저만 열어요; lean TUI와 CLI는 url 을 전혀 확인하지 않아서, URL 전용 명령은 대신 (보통 비어 있는) 해석된 텍스트를 프롬프트로 보내요. 위의 Behavior differs by frontend 참고. 단순 문자열 형태는 { instruction: "..." } 의 약칭이에요.

더 알아보기 (Learn more)