직접 만든 스킬이 호출되지 않는 문제: Claude Code의 description으로 자동 실행 활성화하기

Claude Code의 스킬을 20개 정도 만들었습니다. 그중 절반 정도는 한동안 "만들었는데 한 번도 자동으로 호출되지 않은 채" 방치되어 있었습니다. 이 기사는 스킬이 알아서 실행되기 위한 description 작성법을 저의 실수로부터 정리한 것입니다. 이 글을 다 읽으면 트리거 단어(Trigger words)를 배치하는 방법과 "너무 많이 넣어서 폭발(오작동)하는" 경계, 비슷한 스킬끼리 충돌하는 것을 방지하는 작성법을 알 수 있습니다.

미리 말씀드리자면, 스킬의 내용보다 description의 몇 줄이 더 효과적이었습니다.

스킬은 "내용"이 아니라 "설명문"으로 선택된다

전제부터 말씀드리겠습니다. Claude Code의 스킬(Agent Skill)은 SKILL.md 상단에 적는 description을 보고 자동으로 선택됩니다. 무언가를 요청하면 Claude가 등록된 모든 스킬의 description을 비교하여, "이것은 report의 차례구나"라고 판단하여 실행합니다.

즉, 내용(STEP 구성이나 구현 등)을 아무리 공들여 만들어도 description이 약하면 영원히 호출되지 않습니다. 호출되지 않으면 제로(0)입니다.

이 부분을 처음에 완전히 간과했습니다.

첫 번째 실패: description이 "설명"이 되어 있었다

가장 처음 만든 것이 실험 리포트 생성 스킬입니다. description을 다음과 같이 작성했습니다.

---
name: report
description: 실험 리포트를 생성하는 스킬입니다.
...

정중하게 "~하는 스킬입니다"라고 적고 이것으로 만족하고 있었습니다.

그런데 "실험 리포트 만들어"라고 입력해도 호출되지 않았습니다. "고찰을 써줘"라고 해도 호출되지 않았습니다. 손으로 직접 /report라고 입력하면 작동하지만, 그러면 스킬로 만든 의미가 퇴색됩니다.

이유는 지금은 알 수 있습니다. description이 너무 짧아서 저의 말투와 맞지 않았던 것입니다. "실험 리포트를 생성한다"라고만 적어두면, "고찰 써줘", "그래프를 포함해서 정리해줘"와 같은 다른 표현을 포착할 수 없습니다. Claude 측에 "이것이 트리거다"라는 단서가 너무 적었습니다.

설명문을 쓰고 있다고 생각했지만, 검색 키워드를 쓰고 있지 않았던 것입니다.

해결 방법: 본문 + 트리거 단어 리스트의 2단계 구성

수정한 뒤의 description은 이것입니다. 현재 report 스킬에 들어있는 내용입니다.

---
name: report
description: >
...

구조는 2단계입니다.

전반부는 본문입니다. 무엇을 하는 스킬인지, 무엇을 출력하는지(Word(.docx))를 평범하게 적습니다. 이는 사람이 읽고 이해하기 위함이기도 합니다.

후반부는 호출 키워드입니다. 제가 실제로 입력할 법한 구절을 괄호 안에 나열합니다. "고찰 써줘"와 같이 평소에 툭 던지는 말투를 그대로 넣습니다.

이 후반부를 추가했더니 호출되기 시작했습니다. "고찰 써줘"라고 하면 report가 실행됩니다. 전에는 무반응이었는데 말이죠.

효과가 있었던 이유는 트리거 단어를 저의 어휘로 작성했기 때문이라고 생각합니다. 교과서적인 정식 명칭이 아니라, 피곤할 때 입력하는 거친 말투. "실험 결과 정리해줘" 같은 것 말이죠. 그런 쪽이 실제 입력에 더 가깝습니다.

너무 많이 넣으면, 이번에는 폭발한다

의욕이 앞서서 다른 스킬에 트리거 단어를 잔뜩 집어넣던 시기가 있었습니다. "정리해", "정리해줘", "만들어"와 같은 범용 용어를 넣었습니다.

그랬더니 반대였습니다. 관련 없는 상황에서 멋대로 실행되기 시작했습니다. 파일을 조금 정리하고 싶을 뿐인데 sort가 나오거나, 가볍게 메모를 정리하고 싶을 뿐인데 무거운 의사록 스킬이 실행되기도 했습니다.

방해되었습니다.

트리거 단어는 적으면 호출되지 않고, 많으면 폭발합니다. 그 사이에 적절한 대역이 있습니다. 현재 제가 주의하고 있는 점은 다음과 같습니다.

• "정리해", "만들어", "정리해줘"와 같이 한 단어만으로 의미가 너무 넓은 단어는 단독으로 넣지 않습니다. "의사록 만들어", "예산표 만들어"와 같이 대상과 세트로 넣습니다.
• 해당 스킬 고유의 표현을 우선시합니다. "Whisper 돌려줘"라거나 "m4a를 텍스트로"와 같이 다른 것과 거의 겹치지 않는 단어는 안전합니다.
• 망설여지면 넣지 않습니다. 나중에 "호출되지 않았네"라고 깨달은 뒤에 추가하는 것이, 폭발을 수정하는 것보다 쉽습니다.

이 부분의 밸런스는 솔직히 아직 다 맞추지 못해서, 사용하면서 깎거나 더하고 있습니다. 몇 번 호출되었는지 측정한 것은 아니므로, 여기는 완전히 체감에 의존하고 있습니다.

가장 애를 먹었던 것은, 비슷한 스킬 간의 구분

이것이 가장 힘들었습니다. 스킬이 늘어나면 비슷한 역할을 하는 것들이 반드시 충돌합니다.

제 경우에는 다음과 같은 조합입니다.

• report (실험 리포트) / preview-report

（수업 예습 리포트） / abroad-report

（유학·연수 보고） -
debug

（로직 원인 분류） / build-fix

（빌드·의존성·기동 실패 계열） -
review

（개별 코드 육안 리뷰） / verify

（정적 분석·테스트 일괄 실행）

「리포트 작성해줘」라고 말했을 때, report인지 preview-report인지. 「안 돌아가」라고 말했을 때 debug인지 build-fix인지. Claude가 망설이면, 잘못된 쪽이 실행됩니다.

대처법은, description 안에 상호 참조(역할 분담에 대한 주석)를 적는 것이었습니다.

# report의 description 일부
（수업 예습 리포트는 /preview-report, 유학·연수 보고는 /abroad-report）

# build-fix의 description 일부
（빌드/의존성/기동 실패 계열. 로직 기인 결함의 원인 분류는 /debug）

# debug의 description 일부
（빌드/의존성/기동 실패 시에는 /build-fix）

# review의 description 일부
（정적 분석/테스트 일괄 자동 실행은 /verify）

괄호 안에 「이것은 저것, 저것은 이것」이라고 경계선을 그어둔다. 그렇게 하면 Claude가 선택할 때 「아, 예습이라면 다른 스킬인가」라고 깨달을 수 있는 실마리가 됩니다.

사소합니다. 하지만 비슷한 스킬이 3개 나란히 있을 때는, 이 한 문장이 있고 없고에 따라 오작동이 줄어든 느낌이 있습니다. 서로가 서로를 가리키고 있는 상태로 만들어 두는 것. 이것은 효과가 있었습니다.

argument-hint와 STEP도 덤으로

description이 주인공이지만, SKILL.md에는 그 외에도 효과가 있는 항목들이 있습니다.

argument-hint. 스킬을 호출할 때 「무엇을 전달해야 하는가」에 대한 힌트입니다. 리포트 계열이라면 대상 폴더나 URL을 전달받기를 원한다는 내용을 적어둡니다. 이것이 있으면 실행된 후 Claude가 「그래서, 무슨 리포트요?」라고 매번 되묻지 않아도 될 때가 있습니다.

---
name: preview-report
description: 예습 리포트 생성 — ...（중략）
...

그리고 본문의 STEP 구성. description으로 올바르게 실행되더라도, 내용이 절차화되어 있지 않으면 동작이 흔들립니다. 저는 본문을 「STEP1: 입력 확인 → STEP2: 소재 수집 → STEP3: 생성 → STEP4: 출력 위치에 저장」과 같이 번호로 구분합니다. 이것은 자동 선택 자체와는 관계없지만, 실행 후의 안정성에 효과적입니다.

이 부분은 본론에서 벗어나므로 깊게 다루지는 않겠습니다. 주인공은 어디까지나 description입니다.

스킬을 만드는 스킬에 템플릿을 뱉게 하기

매번 이 description 구조(본문 + 트리거 단어 + 상호 참조)를 손으로 쓰는 것은 솔직히 귀찮습니다. 쓰는 것을 잊어버리면 또 「호출되지 않는 스킬」이 늘어납니다.

그래서 스킬을 만드는 스킬(skill-new) 쪽에서 이 템플릿을 자동으로 뱉어내도록 만들었습니다.

skill-new는 요구 사항을 전달하면 SKILL.md의 초안을 만드는 스킬입니다. 그 출력물에,

• 본문 (무엇을 하는가)
• **호출 키워드**：「...」, 「...」 등.
• argument-hint
• STEP 구성의 뼈대

를 처음부터 채워진 상태로 나오게 합니다. 트리거 단어는 요구 사항에서 추측한 후보를 넣어두고, 저는 그것을 삭제하거나 추가하기만 하면 되도록 합니다.

처음부터 쓰려고 하면 다시 「설명문」을 써버리게 됩니다. 첫 번째 실패의 재발입니다. 하지만 초안에 트리거 단어 칸이 처음부터 비어 있다면 채울 수밖에 없습니다. 시스템으로 강제한 것입니다.

게으른 방법이지만, 이런 것은 시스템 쪽으로 넘기는 편이 지속하기 좋습니다.

요약 대신, 자신을 위한 체크리스트

새로운 스킬을 만들었을 때, description에 대해 제가 확인하는 것은 이것입니다.

• 「~하는 스킬입니다」로만 끝나지 않았는가 (그것은 설명이지 트리거가 아니다)
• 평소에 쓰는 거친 말투를 괄호 안에 몇 개 넣어두었는가
• 「한꺼번에」와 같이 너무 넓은 단어를 단독으로 넣지 않았는가 (대상과 세트로 만들었는가)
• 비슷한 역할의 스킬이 있다면, 괄호 안에 역할 분담을 위한 상호 참조를 넣었는가
• 만든 후, 실제로 그럴듯한 말투로 입력해 보았을 때 제대로 호출되었는가

마지막의 "실제로 입력해서 테스트하기"가 결국 가장 확실했습니다. description의 좋고 나쁨은, 자신의 입에서 나온 말투로 호출되는지 여부로만 알 수 있습니다.

스킬은 호출되어야 비로소 스킬이 됩니다.

이 기사는 구현부터 집필까지 Claude Code와 대화하며 작성했습니다. 학부 2학년이라 용어 사용이 미숙한 부분이 있을 수 있으니, 지적해 주시면 감사하겠습니다.

Discussion