/review를 쓰다가 물어본 적이 있습니다. 이거 “코드 리뷰해줘”라고 직접 치는 거랑 뭐가 다르냐고. 돌아온 답이 이랬어요.
“까놓고 보면 잘 만들어진 프롬프트야.”
스킬 파일을 처음 봤을 때 솔직히 감이 안 왔습니다. .md 파일이잖아요. CLAUDE.md도 .md, 커맨드도 .md, 스킬도 .md. 뭔가 내부적으로 특별한 메커니즘이 있을 줄 알았는데, 본질은 그냥 구조화된 프롬프트 템플릿이었습니다.
그런데 “그냥 프롬프트네” 하고 넘기기엔, 쓰면 쓸수록 이게 에이전트 행동을 설계하는 핵심 부품이더군요. 대화 중에 제가 이렇게 되물은 적이 있습니다.
“이 작업을 할 때 이러한 방식으로 처리하면 좋겠다?”
“어 정확해. 그게 스킬의 본질이야.”
스킬은 딱 두 부분입니다. when(description), “이런 작업이 오면”. how(본문), “이렇게 처리해”. 이 단순한 구조에서 네 가지 속성이 나옵니다. 이 글은 그 네 가지로 스킬을 다시 설명해보는 글입니다.
하나, 에이전트의 행동을 제약할 수 있다
저는 그동안 규칙이란 규칙은 죄다 CLAUDE.md에 넣어왔습니다. 항상 떠 있으니까 항상 지켜지겠지, 하고요. 근데 실제로는 대화가 길어질수록 특정 규칙이 무시되는 일이 생겼습니다. “있긴 한데 까먹는” 패턴이죠. CLAUDE.md는 매 메시지마다 읽히긴 하지만, 파일이 길어질수록 개별 규칙에 대한 모델의 attention이 희석됩니다. 멀리 묻혀서 다른 내용들과 경쟁하는 거예요.
스킬은 이 지점이 다릅니다. 본문이 트리거되는 그 순간, 작업 바로 옆에 새로 주입됩니다. 경쟁 없이, 지금 필요한 시점에, 딱 앞에 떠오르는 것이죠. 그래서 “긴 세션에서 까먹는” 실패 모드에는 스킬이 확실히 강합니다. 특정 작업에서 에이전트가 반드시 따라야 하는 절차를 스킬로 박아두면, 그 작업을 할 때의 행동이 그 절차로 묶입니다.
다만 공짜는 아닙니다. 누락의 성격이 바뀌어요. CLAUDE.md의 “들쭉날쭉 적용됨”에서, 스킬의 “발동 자체가 실패하면 통째로 안 나옴”으로. description이 작업이랑 매칭이 안 되면 그 케이스는 100% 누락입니다. 컨벤션은 적어도 떠 있긴 했으니까, description이 약하면 오히려 컨벤션보다 나쁠 수도 있습니다.
둘, 재사용 가능하다
스킬을 만들 타이밍을 물었더니 신호는 하나였습니다. “어 이거 Claude한테 매번 똑같은 설명 또 치고 있네” 싶은 마찰. 그게 느껴지는 순간이 스킬로 만들 타이밍이고, 안 느껴지면 안 만들어도 됩니다.
/review의 가치가 정확히 여기 있었습니다. 품질 좋은 리뷰 프롬프트를 직접 잘 짜서 매번 똑같이 칠 수 있으면 거의 차이가 없어요. 다만 직접 칠 땐 그때그때 빠뜨리는 항목이 생깁니다. 스킬은 그 잘 짠 프롬프트를 한 단어로, 일관되게, 버전관리되는 형태로 쓰게 해줍니다. 한 번 파일로 만들어두면 매번 똑같은 체크리스트가 돌고, git에 남고, 고치면 다음부터 고쳐진 대로 돕니다.
셋, 필요할 때 자동 호출된다
커맨드도 .md, 스킬도 .md라 헷갈리는데, 핵심 차이는 누가 발동시키냐입니다. 커맨드는 제가 /이름을 직접 쳐야 발동합니다. 수동이고, 예측 가능하죠. 스킬은 Claude가 지금 하는 작업 맥락에 맞으면 자동으로 발동합니다. 제가 안 불러도 알아서 씁니다.
그래서 스킬은 description이 절반 이상을 먹고 들어갑니다. 커맨드는 제가 직접 치니까 when이 필요 없지만, 스킬은 “지금 이게 해당되는 상황이다”를 Claude가 스스로 매칭해야 하거든요. 트리거 조건이 모호하면 정작 필요할 때 발동하지 않거나, 엉뚱한 순간에 끼어듭니다.
“주식 관련”이라고 쓰면 발동이 들쭉날쭉해집니다. “P&L 계산이나 손익 관련 로직을 작성/수정할 때”라고 쓰면 딱 그때 나옵니다. when을 얼마나 또렷하게 쓰느냐가 스킬 품질을 좌우합니다.
넷, 만들긴 쉽다
“만들어줘” 하면 진짜 만들어줍니다. 스킬은 결국 마크다운 파일이라, Claude Code한테 프롬프트로 시키면 frontmatter부터 본문 절차까지 다 짜줍니다.
대신 만들어주는 거랑 제대로 되는 거는 별개입니다. 본문 절차는 잘 뽑아도, “언제 발동할지”는 제 의도를 정확히 알아야 잘 쓰거든요. 그래서 초안을 받고 when 부분만 검수해서 다듬는 식이 좋습니다. 생성이 거의 공짜가 되면서, 병목은 생성이 아니라 명세와 검증으로 옮겨갔습니다. 이 스킬이 언제 떠야 하는지, 실제로 잘 뜨는지는 여전히 제가 정하고 확인해야 하는 영역이에요.
정리하면
스킬은 “이런 작업이 오면(when) 이렇게 처리해(how)“를 파일 하나에 박아두는 겁니다. 전통적인 코드는 기계가 읽는 언어로 로직을 표현하지만, 스킬은 LLM이 읽는 자연어로 로직을 표현합니다. 실행 엔진이 다를 뿐, 둘 다 조건과 절차를 기술하는 행위예요. 그래서 네 속성이 성립합니다. 행동을 제약할 수 있고, 재사용되고, 필요할 때 자동으로 뜨고, 만들긴 쉽습니다.
CLAUDE.md가 과적재됐다 싶으면, 지금 가장 자주 누락되는 규칙 하나를 골라 스킬로 떼보세요. when을 “P&L 계산”처럼 구체적으로 쓰고, 같은 작업을 몇 번 돌려서 발동하는지 확인하면 됩니다. description이 약하면 컨벤션보다 나빠질 수 있다는 것만 기억하고요.