Claude Code로 재사용 가능한 워크플로우 만들기──SKILL.md 설계의 3원칙

스킬이 늘어나면 「오작동(誤発火)」한다

Claude Code의 하네스(Harness)를 본격적으로 사용하기 시작하면 어떤 문제에 부딪히게 된다.

"주간 보고서를 부탁했는데, 일일 보고서 생성 스킬이 작동했다"

"Git 커밋을 부탁했더니, 한동안 잠들어 있던 Git 관리 스킬이 작동했다"

스킬이 1~2개일 때는 이런 문제가 발생하지 않는다. 5개, 10개로 늘어나는 단계에서는 유사한 용도의 스킬들이 충돌하기 시작한다. 이것은 "프롬프트(Prompt)를 정성스럽게 쓰면 해결되는" 문제가 아니다. 스킬 설계에 구조적인 결함이 있는 것이다.

이 기사에서는 하네스로 스킬을 설계할 때의 3원칙을 설명한다.

TL;DR

• commands/는 단순한 프롬프트 전달, skills/는 다단계 워크플로우(Workflow)
• description만이 발화(Trigger) 판정에 사용된다. 본문 및 frontmatter의 다른 필드는 발화에 영향을 주지 않는다.
• description에는 「What + When + 네거티브 트리거(Negative Trigger)」의 세 가지 요소를 반드시 포함한다.

원칙 1: commands/ 와 skills/ 를 구분해서 사용하기

먼저 혼동하기 쉬운 개념을 정리한다. Claude Code의 하네스에는 두 종류의 「스킬 저장소」가 있다.

commands/ ── Claude Code 공식 slash command

commands/ 디렉토리에 둔 Markdown 파일은 /명령어명으로 호출할 수 있는 공식 기능이다. 사용자가 명시적으로 호출하며, 자동으로 발화되지 않는다.

.claude/
└── commands/
├── navi.md # /navi 로 호출
...

적합한 경우:

• 짧은 단일 프롬프트를 전달하기만 하는 것
• 사용자가 의도적으로 호출하는 조작

skills/ ── 하네스 독자적인 워크플로우 정의

skills/ 디렉토리는 하네스 독자적인 메커니즘이다. SKILL.md 파일에 frontmatter로 설정을 가지며, Claude가 문맥을 읽고 자동으로 참조한다.

.claude/
└── skills/
├── weekly-report/
...

적합한 경우:

• allowed-tools로 사용할 수 있는 도구를 제한하거나 확장하고 싶은 경우
• 여러 단계로 구성된 워크플로우(Workflow)
• 외부 도구(API, 스크립트)를 호출하는 경우

판단 기준은 간단하다.

"allowed-tools가 필요한가? 다단계인가?" ── 둘 중 하나라도 Yes라면 skills/가 유일한 선택이다.

원칙 2: description이 전부다

SKILL.md의 구조를 살펴보자.

---
name: 주간 보고서 생성
description: >
...

여기서 중요한 사실이 있다.

발화 판정의 주요 시그널(Signal)은 description이다. 본문은 스킬 실행 시의 절차로서 읽히지만, "어떤 스킬을 선택할지"의 판단에는 직접적인 영향을 주지 않는다.

name 필드는 사람이 읽기 위한 라벨이다. model이나 allowed-tools는 스킬 실행 시의 설정이다. Claude가 어떤 스킬을 사용해야 할지 판정할 때, description이 가장 중요한 시그널이 된다.

description이 빈약하면 "어떤 스킬을 호출할지"에 대한 판단이 흔들린다. 역으로 말하면, description을 정성스럽게 작성하는 것이 오작동을 방지하는 최대의 대책이다.

description의 세 가지 요소

적절한 description에는 반드시 다음 세 가지 요소가 포함되어야 한다.

요소	역할	예시
What (무엇을 하는가)	스킬의 기능을 간결하게 기술	"주간 진척 보고서를 생성한다"
When (언제 사용하는가)	발화해야 하는 문맥·상황을 기술	"사용자가 이번 주 요약이나 주간 보고서에 대해 이야기할 때"
트리거 워드 (Trigger Word)	발화를 일으키는 키워드를 열거	"주간 보고서·이번 주 요약·주보라고 말했을 때"

글자 수는 50~200자 정도가 적절하다. 너무 짧으면 구분이 안 되고, 너무 길면 노이즈가 된다.

원칙 3: 네거티브 트리거를 반드시 넣을 것

세 가지 요소 중 가장 간과하기 쉬운 것이 **네거티브 트리거(Negative Trigger)**다.

"Do NOT use for ..."로 시작하는 부정형 문장을 description의 말미에 반드시 넣는다.

왜 필요한가

스킬이 1개일 때는 문제가 발생하지 않는다. 여러 스킬이 공존하는 순간, 유사한 문맥에서 여러 스킬이 후보가 된다. Claude는 그때 description을 비교하여 "어느 것을 사용해야 할지"를 판단한다.

네거티브 트리거 (Negative Trigger)가 없다면, 그 판단은 모호해진다.

나쁜 예와 좋은 예

# ❌ 나쁜 예: 네거티브 트리거 없음
description: >
주간 진척 보고서를 생성한다.
...

# ✅ 좋은 예: 네거티브 트리거 있음
description: >
주간 진척 보고서를 생성한다.
...

네거티브 트리거로 "무엇에 사용하지 않는지"의 경계를 명시함으로써, 유사한 용도의 스킬과의 경계가 확정된다.

실제 오작동 (Mis-firing) 패턴

구체적인 오작동 패턴을 보여준다.

Before (네거티브 트리거 없음)

사용자: "오늘 요약 만들어줘"
→ 주간 보고서 스킬이 발화 (주간 진척 보고서를 생성하려고 시도함)
※ 사용자의 의도는 "오늘 = 일일 보고서"였으나, "요약"이라는 키워드가 주간과 겹침

After (네거티브 트리거 있음)

# 주간 보고서 스킬의 description
description: >
주간 진척 보고서를 생성한다.
...

두 스킬이 서로에게 "상대방에게 맡기는 영역"을 선언함으로써, Claude는 문맥으로부터 올바른 스킬을 선택할 수 있게 된다.

SKILL.md의 실제 구조

SKILL.md의 프런트매터 (frontmatter)에서 사용할 수 있는 주요 필드를 정리한다.

---
name: 스킬의 이름 (사람이 읽는 용도. 발화 판정에 사용되지 않음)
description: >
...

model 필드는 Bloom 분류 (Bloom's Taxonomy L1~L6)에 기반하여 선택한다. "절차서가 있는가? Yes → haiku / No → sonnet 이상"이 간이 판정의 기준이다. 자세한 내용은 "Claude Code로 여러 모델을 구분하여 사용하기──Bloom 분류에 의한 모델 라우팅 설계"에서 해설하고 있다.

일일 보고서 생성·정형 포맷 출력과 같이 절차대로 진행되는 처리는 haiku로 충분하다. 코드 리뷰나 설계 검토가 포함되는 스킬은 sonnet으로 설정한다.

allowed-tools로 스킬이 사용할 수 있는 도구를 제한하는 것도 안전 설계의 일부다. "이 스킬은 Read와 Write만 가능하다"라고 적으면, Bash를 호출하는 오작동을 방지할 수 있다.

요약: SKILL.md 설계의 3원칙

• commands/ 와 skills/ 를 구분하여 사용한다
  수동 호출의 단순한 프롬프트 전달은 commands/. 여러 단계(multi-step)·외부 도구·allowed-tools가 필요하다면 skills/.

• description에 세 가지 요소를 넣는다
  "What (무엇을 하는가) + When (언제 사용하는가) + 트리거 워드"를 50~200자 내외로 정리한다. 본문은 발화 판정에 사용되지 않는다.

• 네거티브 트리거를 반드시 작성한다
  "Do NOT use for ..."로 스킬이 담당하지 않는 영역을 명시한다. 스킬이 늘어날수록, 이 경계 선언이 오작동을 방지하는 유일한 수단이 된다.

스킬을 추가할 때마다 "이 스킬과 유사한 용도의 기존 스킬이 있는가?"를 확인하고, 있다면 서로 네거티브 트리거로 경계를 명시한다. 이것을 습관화하는 것만으로도, 스킬이 20개로 늘어나도 오작동하지 않는 하네스 (Harness)를 만들 수 있다.

하네스 설계의 전체 모습은 "Claude Code 하네스 엔지니어링 실전 Playbook"에서 해설하고 있다.

감상이나 "이 케이스는 어떻게 하나요?"와 같은 질문은 댓글로 편하게 남겨주시면 감사하겠습니다. '좋아요'도 큰 힘이 됩니다.

저자 코멘트

Discussion