커스텀 커맨드 프론트매터 설정

YAML 프론트매터는 커스텀 커맨드 Markdown 파일 첫머리에 --- 로 감싸 적는 메타데이터 영역으로, 프롬프트 본문만으로는 담을 수 없는 커맨드의 동작 설정을 얹는 곳입니다. 도구 실행 시 확인 프롬프트 생략, 전용 모델 지정, 인수 힌트 표시처럼 커맨드를 더 매끄럽고 안전하게 만드는 설정이 여기에 들어갑니다.

커맨드 파일을 만드는 기본 절차는 커스텀 커맨드 입문에서 다뤘습니다. 이 글에서는 그 파일 위에 얹는 설정 항목을 하나씩 살펴봅니다.

핵심 요약

• 프론트매터는 Markdown 파일 첫머리에 --- 로 감싼 YAML 메타데이터 영역입니다.
• description 은 / 입력 시 후보 목록에 보이는 커맨드 설명을 정합니다.
• allowed-tools 는 확인 프롬프트 없이 쓸 도구를 사전 승인합니다. 차단 목록이 아닙니다.
• argument-hint 는 인수 형식을 후보 목록에 표시해 사용법을 알려 줍니다.
• 프론트매터는 선택 사항이라 없어도 본문이 그대로 프롬프트로 쓰입니다.

프론트매터는 어떻게 생겼나

기본 구조는 눈으로 보는 것이 가장 빠릅니다.

---
description: 커맨드의 설명문
allowed-tools: Bash(git:*), Read, Edit
argument-hint: [파일 경로]
---
여기에 프롬프트 본문을 씁니다

--- 두 줄 사이가 프론트매터이고, 그 아래가 Claude에게 전달되는 프롬프트 본문입니다. 프론트매터는 임의 설정이라 쓰지 않아도 파일 내용이 그대로 프롬프트로 쓰입니다. 다만 활용하면 더 유연하고 안전한 커맨드가 됩니다.

이 글에서 다루는 항목을 표로 정리하면 다음과 같습니다.

description — 후보 목록에 무엇이 보이나

description 은 커맨드 설명문을 정하는 항목입니다. / 를 입력했을 때 후보 목록에 함께 표시되므로 커맨드 목적을 한눈에 알 수 있습니다.

---
description: Hello World를 출력
---
터미널에서 Hello World를 출력해 주세요. echo 커맨드를 쓰세요.

이렇게 설정하면 후보 목록에 "Hello World를 출력"이 표시됩니다.

> /hello-world
  /hello-world     Hello World를 출력 (project)

description 을 생략하면 프롬프트 본문의 첫 줄이 설명으로 쓰입니다.

> /hello-world
  /hello-world     터미널에서 Hello World를 출력해 주세요. echo 커맨드를 쓰세요. (project)

위 예처럼 본문 첫 줄만 읽어도 알 수 있는 커맨드라면 생략해도 괜찮습니다. 하지만 본문이 길거나 절차가 복잡한 커맨드라면 description 을 명시해 두는 편이 좋습니다. 팀에 공유할 커맨드라면 더욱 그렇습니다.

allowed-tools — 어떤 도구를 확인 없이 쓰게 할까

allowed-tools 는 그 커맨드가 실행되는 동안 지정한 도구를 확인 프롬프트 없이 쓸 수 있게 하는 항목입니다. 핵심은 목록에 없는 도구가 금지되는 것이 아니라는 점입니다. 목록 밖의 도구도 통상적인 권한 설정(허용 규칙이나 그때그때 확인)에 따라 계속 호출할 수 있습니다.

특정 도구의 이용 자체를 막고 싶다면 allowed-tools 가 아니라 disallowed-tools 를 씁니다.

기본 작성법

---
allowed-tools: Read, Grep
---
프로젝트 내의 에러 로그를 검색해 주세요.

이 예에서는 Read와 Grep을 확인 없이 쓰도록 사전 승인했습니다. Edit이나 Bash처럼 승인하지 않은 도구도 호출은 가능하며, 실행 시 통상적인 권한 설정에 따라 확인을 요구받습니다(설정에 따라 확인 없이 실행되기도 합니다).

자주 쓰는 도구 지정 패턴

Bash(git add:*) 처럼 하위 명령까지 좁혀 지정할 수도 있습니다.

사전 승인의 장점과 주의점

가장 큰 장점은 그 커맨드에서 신뢰할 수 있는 도구의 확인 프롬프트를 생략할 수 있다는 점입니다. git 조작 전용 커맨드라면 Bash(git:*) 를 사전 승인해 두면 매번 확인에 시달리지 않습니다.

반대로 "커밋 전용 커맨드인데 멋대로 파일을 편집당했다" 같은 사고를 확실히 막고 싶다면, allowed-tools 로는 부족합니다. disallowed-tools 로 Edit이나 Write 자체를 금지해야 합니다. 커맨드 목적에 맞게 사전 승인 도구를 좁혀 두면 확인 프롬프트는 최소한으로 줄이면서 위험한 조작은 통상적인 확인 흐름에 남겨 둘 수 있습니다.

사전 승인을 빠뜨렸다고 해서 치명적인 일이 생기지는 않습니다. Read는 원래 확인이 필요 없는 도구라 목록에서 빠져도 파일 읽기와 리뷰는 문제없이 됩니다. 주의할 것은 Bash나 Edit처럼 통상 확인을 요구받는 도구입니다. 이것들을 빠뜨리면 커맨드 실행 중 확인 프롬프트에서 멈춰 자동화 흐름이 끊길 수 있습니다.

실무에서는 처음엔 allowed-tools 없이 동작을 확인하고, 확인 프롬프트가 번거롭게 느껴진 도구부터 하나씩 추가해 나가는 편이 좋습니다. 퍼미션 설정 전반은 퍼미션 설정 최적화에서 다룹니다.

argument-hint — 인수 형식을 어떻게 알려 주나

argument-hint 는 커맨드 인수에 관한 힌트를 후보 목록에 표시하는 항목입니다.

커스텀 커맨드는 실행할 때 파일 경로나 Pull Request 번호 같은 인수를 받을 수 있습니다. 그런데 시간이 지나면 어떤 인수를 넘겨야 했는지 잊기 쉽습니다. argument-hint 를 설정해 두면 인수 형식이 표시되니 사용법을 바로 떠올릴 수 있습니다.

---
description: 파일을 리네임
argument-hint: [old-path] [new-path]
---
옛 경로를 새 경로로 리네임해 주세요.

/rename 을 입력하면 [old-path] [new-path] 가 함께 표시되어 "경로 두 개를 넘겨야겠구나" 하고 바로 이해할 수 있습니다.

> /rename  [old-path] [new-path]
  /rename     파일을 리네임 (project)

argument-hint 는 어디까지나 표시용입니다. 넘어온 인수를 프롬프트 안에서 실제로 받는 방법은 $ARGUMENTS 로 인수 받기에서, 인수를 하나씩 나눠 받는 방법은 $0/$1/$2 로 여러 인수 다루기에서 다룹니다.

설정을 조합한 예 — 안전한 커밋 커맨드

실제로는 여러 항목을 조합해 씁니다. 아래는 커밋 절차만 확인 없이 진행하게 만든 커맨드입니다.

---
description: 변경을 스테이징하고 커밋
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*)
---
아래 절차로 커밋해 주세요.
1. git status 로 변경을 확인
2. git add . 로 전체 파일을 스테이징
3. git commit 으로 커밋

이 커맨드에서 각 항목이 하는 일은 다음과 같습니다.

• description: 후보 목록에서 목적을 바로 알 수 있습니다.
• allowed-tools: git status·add·commit 세 가지만 확인 없이 실행됩니다. Edit 등 다른 도구는 통상적인 확인 흐름 그대로입니다.

보충: 커스텀 슬래시 커맨드는 스킬과 같은 취급으로 통합됐습니다. 프론트매터에 disable-model-invocation: true 를 설정하면 Claude가 알아서 꺼내 쓰지 않고 사용자가 명시적으로 호출했을 때만 실행됩니다. 스킬 쪽 프론트매터 작성법은 SKILL.md 작성법을, 커맨드와 스킬의 역할 구분은 슬래시 명령어와 Skills를 참고하세요.

정리

• 프론트매터는 커맨드 파일 첫머리의 --- 블록이며, 없어도 동작하지만 있으면 동작을 세밀하게 제어할 수 있습니다.
• description 은 후보 목록 설명, argument-hint 는 인수 형식 힌트를 담당합니다.
• allowed-tools 는 확인 프롬프트를 생략할 도구의 사전 승인이고, 금지는 disallowed-tools 가 맡습니다.
• 처음엔 승인 없이 써 보고 번거로운 도구부터 하나씩 allowed-tools 에 추가하는 순서가 안전합니다.
• 인수를 실제로 받는 방법은 $ARGUMENTS 로 인수 받기에서 이어집니다.