클로드 스킬 description, 이렇게 쓰면 필요할 때 알아서 나옵니다

스킬의 description 한 줄이 작업을 부르는 기준이 됩니다.

스킬이 스스로 나오게 하려면

클로드 코드에서 스킬은 `.claude/skills/<이름>/SKILL.md` 파일로 둡니다. 그 파일 맨 위에 `---` 로 감싼 머리말이 있고, 거기에 `name` 과 `description` 을 적습니다.

처음엔 description 이 그냥 설명인 줄 알았습니다. 그런데 이게 단순 설명이 아닙니다. 클로드가 대화 중에 "지금 이 작업은 이 스킬이 필요하겠다"라고 판단하는 기준이 바로 이 description 입니다.

다시 말해 description 이 잘못 쓰여 있으면, 정작 필요할 때 스킬이 불려 나오지 않습니다. 반대로 필요 없는 순간에 튀어나오기도 합니다.

그래서 description 을 어떻게 쓰느냐가 스킬의 운명을 가릅니다.

제가 직접 여러 번 겪은 일입니다. 스킬을 열심히 만들어 놓고 "왜 안 불려 나오지?" 하고 헤맨 적이 많습니다.

description 에 들어가야 할 것 하나

description 에 들어가야 할 핵심은 "언제 쓰는지" 입니다. 무엇을 하는지가 아니라, 어떤 상황에서 쓰는지가 중요합니다.

예를 들어 "블로그 글을 쓴다"라고만 적으면, 클로드는 이 스킬이 블로그 글쓰기라는 큰 작업 전체에 해당한다고 생각합니다. 그러면 글쓰기 시작부터 끝까지 이 스킬을 붙잡고 갑니다.

그런데 실제로는 "키워드 조사"를 위한 스킬이라면, description 을 이렇게 바꿔야 합니다.

"블로그 주제가 정해졌을 때, 관련 키워드를 찾고 경쟁도를 가늠하는 데 쓴다."

이렇게 쓰면 클로드가 대화 중에 "아, 지금 키워드가 필요하겠구나" 하고 판단해서 스킬을 꺼냅니다.

처음엔 이 차이를 몰라서, description 에 "블로그 글쓰기"라고 적어 두고는 왜 이 스킬이 자꾸 글 전체를 맡으려는지 이해가 안 됐습니다.

구체적으로 적을수록 잘 나옵니다

description 은 구체적일수록 좋습니다. 막연한 말보다, 상황과 조건을 함께 적어야 합니다.

예를 들어 "홍보 문구를 만든다" 보다는 이렇게 쓰는 편이 낫습니다.

"제품이나 서비스 소개가 있을 때, SNS나 블로그에 쓸 짧은 홍보 문구를 여러 개 제안한다."

이렇게 하면 클로드가 "아, 지금 소개받았으니 홍보 문구가 필요하겠다" 하고 스킬을 꺼냅니다.

또 하나, description 에는 "누구를 위한 것인지"를 넣어도 도움이 됩니다. 예를 들어 "전문직 종사자를 위한" 같은 대상이 들어가면, 그 대상과 관련된 대화에서만 스킬이 나옵니다.

이렇게 하면 엉뚱한 상황에서 스킬이 나오는 걸 줄일 수 있습니다.

너무 길게 쓰면 오히려 안 됩니다

description 을 길게 쓰면 더 자세할 거라고 생각하기 쉽습니다. 그런데 실제로는 짧고 명확한 편이 잘 불려 나옵니다.

클로드가 description 전체를 읽고 판단하는데, 너무 길면 핵심을 놓칩니다. 마치 검색할 때 키워드가 너무 많으면 오히려 결과가 안 나오는 것과 비슷합니다.

그래서 저는 description 을 두세 문장, 길어야 네 문장으로 제한합니다. 그리고 그 안에 "언제, 무엇을, 어떻게"를 압축해서 넣습니다.

예를 들어 이런 식입니다.

"새 프로젝트 폴더를 시작할 때, 기본 폴더 구조와 파일을 만들어 주는 스킬. 프로젝트 이름을 받아서 초기 세팅을 한다."

짧지만 상황과 역할이 다 들어 있습니다.

실제로 잘 된 예와 안 된 예

제가 만든 스킬 중에 "블로그 초안 작성"이라는 게 있습니다. 처음 description 은 이랬습니다.

이렇게 하니 클로드가 블로그 글을 쓸 때마다 이 스킬을 꺼냈습니다. 그런데 문제는, 그 스킬이 "키워드부터 초안까지" 전부 하려고 했습니다. 그러다 보니 다른 스킬과 충돌하고, 결과물도 어정쩡했습니다.

그래서 description 을 이렇게 바꿨습니다.

"블로그 주제와 키워드가 정해졌을 때, 초안을 작성하는 스킬. 제목 후보와 개요, 본문 초안을 제공한다."

바꾸고 나니 클로드가 "이제 초안만 필요하겠다" 싶을 때만 스킬을 불러 씁니다. 훨씬 자연스러워졌습니다.

이런 경험을 몇 번 하면서, description 을 스킬 이름만큼 신경 써야 한다는 걸 배웠습니다.

스킬을 부르는 다른 방법, user-invocable

description 으로 자동으로 불려 나오게 하는 것 외에, 직접 부르는 방법도 있습니다. SKILL.md 머리말에 `user-invocable: true` 를 넣으면 `/스킬이름` 으로 언제든 직접 실행할 수 있습니다.

저는 자주 쓰는 스킬에는 이 옵션을 넣어 둡니다. 예를 들어 "고객 응대 문구 만들기" 같은 건 매번 말로 설명하기보다 `/응대문구` 하고 부르는 게 빠릅니다.

단, 모든 스킬에 이 옵션을 넣으면 목록이 지저분해집니다. 자주 쓰는 것만 직접 부르게 하고, 나머지는 description 으로 알아서 나오게 두는 게 좋습니다.

이 글은 제가 쓰는 시점의 클로드 코드 기준입니다. 버전에 따라 화면이 다를 수 있으니, 공식 안내를 확인해 보시면 됩니다.

그래도 안 나온다면, 여기를 확인하세요

가끔 description 을 잘 썼는데도 스킬이 안 나올 때가 있습니다. 그럴 때는 세 가지를 확인합니다.

첫째, 파일 위치가 맞는지 봅니다. `.claude/skills/<이름>/SKILL.md` 여야 합니다. 폴더 이름이 다르거나 SKILL.md 가 없으면 아예 인식이 안 됩니다.

둘째, description 에 오타가 없는지 봅니다. 오타 하나로 클로드가 다른 의미로 해석할 수 있습니다.

셋째, 대화 내용에 description 의 키워드가 실제로 등장하는지 봅니다. 클로드는 description 의 단어와 대화 내용이 매칭될 때 스킬을 꺼냅니다. 그러니 description 을 쓸 때는 실제로 손님이 말할 법한 단어를 넣는 게 중요합니다.

스킬을 만들었는데 왜 자꾸 안 나올까요?

description 에 "언제 쓰는지"를 실제 대화에서 나올 표현으로 바꿔 보세요. 그래도 안 되면 user-invocable 로 직접 부르는 방법

description 은 스킬의 이름표이자 호출 버튼입니다. 이 한 줄을 제대로 쓰는 게 스킬의 절반입니다.

#클로드스킬만들기 #클로드코드 #SKILL .md #description #스킬호출 #클로드코드스킬 #AI업무자동화 #마케팅스킬 #클로드사용법 #전주마케팅 #아비컴퍼니