스킬의 비밀 — 자연어가 로직이 되는 순간
/review는 사실 잘 만든 프롬프트야 — 에이전트 행동을 설계하는 4가지 레버
예상: 스킬이 뭔가 특별한 게 있겠지
처음에 Claude Code 스킬 파일을 봤을 때 솔직히 “이게 뭐지?”라는 반응이었습니다. .md 파일이잖아요. CLAUDE.md도 .md, 커맨드도 .md, 스킬도 .md. 다 비슷해 보이는데 뭐가 다른 건지 감이 안 왔어요.
그러다 /review를 쓰면서 궁금해졌습니다. 이게 “코드 리뷰해줘”라고 직접 치는 것과 무슨 차이냐고 물어봤을 때 돌아온 답이 핵심을 찌르더군요.
“까놓고 보면 잘 만들어진 프롬프트야.”
예상과 달랐습니다. 뭔가 내부적으로 특별한 메커니즘이 있을 줄 알았는데, 본질은 그냥 잘 구조화된 프롬프트 템플릿이었어요. /review의 가치는 “그 잘 짠 프롬프트를 한 단어로, 일관되게, 버전관리되는 형태로” 쓴다는 데 있는 것이지, 마법 같은 건 없었습니다.
실제는 달랐다: CLAUDE.md에 다 때려넣으면 누락이 난다
저는 그동안 규칙이나 컨벤션을 죄다 CLAUDE.md에 넣어왔습니다. 처음엔 그게 맞는 것 같았어요. 항상 떠 있으니까 항상 지켜지겠지, 하고요.
근데 실제로는 달랐습니다. 대화가 길어질수록 특정 규칙이 무시되는 일이 생겼어요. “있긴 한데 까먹는” 패턴이었죠. 원인은 간단했습니다. CLAUDE.md는 매 메시지마다 읽히긴 하지만, 파일이 길어질수록 개별 규칙에 대한 모델의 attention이 희석됩니다. 멀리 묻혀서 다른 내용들과 경쟁하는 거예요.
그래서 스킬이 왜 필요한지를 이해하게 됐습니다. 스킬 본문은 트리거되는 그 순간, 작업 바로 옆에 새로 주입됩니다. 경쟁 없이, 지금 필요한 시점에, 딱 앞에 떠오르는 것이죠.
왜 그런가: “이 작업을 할 때 이렇게 처리하면 좋겠다”가 전부
대화를 이어가다 어느 순간 스킬의 구조를 직접 추론해봤습니다.
“이 작업을 할 때 이러한 방식으로 처리하면 좋겠다?”
돌아온 답이 인상적이었어요. “어 정확해. 그게 스킬의 본질이야.”
스킬은 딱 두 부분으로 이루어집니다.
- when(description) — “이런 작업이 오면”
- how(본문) — “이렇게 처리해”
그리고 여기서 제가 놓쳤던 게 있었는데, description이 절반 이상을 먹고 들어간다는 점입니다. 트리거 조건이 모호하면 정작 필요할 때 발동하지 않거나, 엉뚱한 순간에 끼어듭니다.
커맨드는 제가 직접 /이름을 치니까 when이 필요 없지만, 스킬은 Claude가 스스로 “지금 이게 해당되는 상황이다”를 매칭해야 합니다. 그래서 when을 어떻게 쓰느냐가 스킬 품질의 거의 전부예요.
“주식 관련”(X) vs “P&L 계산이나 손익 관련 로직을 작성/수정할 때”(O) — 이 차이가 스킬이 제대로 터지느냐 아니냐를 결정합니다.
자연어가 로직이 되는 방식
이걸 깨닫고 나서 한 가지가 보였습니다. 전통적인 코드는 기계가 읽는 언어로 로직을 표현하지만, 스킬은 LLM이 읽는 언어(자연어)로 로직을 표현합니다. 실행 엔진이 다를 뿐, 둘 다 “조건 + 절차”를 기술하는 행위입니다.
그래서 스킬을 잘 만드는 것은 코드를 잘 짜는 것과 구조적으로 같습니다. 조건(when)이 명확하고, 절차(how)가 구체적이면, 그 자연어 명세가 곧 로직이 되는 거예요.
4개 레버, 각자 다른 축
스킬 하나만 이해하면 끝이 아닙니다. 이번 대화에서 정리된 게 4개 레버 전체였어요.
- CLAUDE.md — 항상 떠 있는 ambient 컨텍스트. 모든 작업에 상시 적용되는 보편 규칙. 짧고 보편적인 것만 넣어야 희석이 안 됩니다.
- 스킬 — 작업이 매칭될 때 자동 발동. 선택적이지만 필요할 때 반드시 나와야 하는 절차.
- 커맨드 — 제가 직접
/이름칠 때 실행. 의도적으로 “지금 이거 해”가 필요한 순간. - 훅 — 모델 판단 없이 결정론적으로 실행되는 쉘 명령어. “절대 빠지면 안 되는” 규칙용.
이 구분을 모르면 죄다 CLAUDE.md에 때려넣고 “왜 자꾸 까먹지”가 됩니다. 알고 나면 어느 레버를 어디에 쓸지가 곧 에이전트 설계예요.
다만 한 가지 트레이드오프는 인지하고 써야 합니다. 스킬로 빼면 누락의 성격이 바뀝니다. CLAUDE.md의 “들쭉날쭉 적용됨”에서 스킬의 “발동 자체 실패하면 통째로 안 나옴”으로요. description이 약하면 오히려 컨벤션보다 나쁠 수도 있습니다.
앞으로는: when을 구체적으로 쓰는 게 전부
에이전트 행동을 설계한다는 게 결국 이겁니다. “이 행동이 항상 필요한가 / 자동으로 떠야 하나 / 절대 빠지면 안 되나”를 구분하고, 거기에 맞는 레버를 당기는 것.
CLAUDE.md가 과적재됐다고 느끼는 분들께 드리는 제안은 하나입니다. 지금 가장 자주 누락되는 규칙 하나를 골라서 스킬로 분리해보세요. when 조건을 최대한 구체적으로 — “P&L 계산”처럼. 한 번 발동되는 걸 확인하는 순간, 자연어로 로직을 짠다는 게 무슨 말인지 몸으로 이해됩니다.
다음 편 ->: 에이전트가 내 말을 안 듣는다면 — 4레버 방법론 심화: build-plan 스킬로 개발 시간을 단축하는 법 · 배경: AI랑 한 대화가 사라지는 게 아까워서 세컨드 브레인을 만들었다