Molayo

© 2026 Molayo

Zenn헤드라인2026. 06. 15. 05:54

SKILL.md의 description을 잘못 작성하면 스킬이 영원히 호출되지 않는다

요약

Claude Code의 Skills 기능이 제대로 작동하지 않을 때, SKILL.md의 description 필드를 최적화하는 방법을 설명합니다. description을 단순 기능 설명이 아닌 사용자의 발화와 유사한 검색 쿼리 형태로 작성해야 함을 강조합니다.

핵심 포인트

  • description은 스킬 호출을 위한 '검색 쿼리' 역할을 수행함
  • 동사, 대상, 호출 키워드를 포함한 자연문 형태로 작성할 것
  • 사용자 발화와 시맨틱 유사성을 높이는 것이 핵심
  • 스킬 간 경합 발생 시 부정 조건을 추가하여 해결 가능
  • 프로젝트 메모리 저장 방식은 근본적인 해결책이 아님

스킬을 만들었는데, 호출되지 않는다

Claude Code의 Skills를 처음 만들었을 때, 이런 경험을 한 사람이 많을 것이다.

  • 「팩트 체크해줘」라고 부탁해도 다른 스킬이 동작한다
  • 「SEO 개선」이라고 말해도, 왠지 상관없는 스킬이 발화(trigger)된다
  • 만든 스킬이 마치 존재하지 않는 것처럼 무시된다

원인의 대부분은 SKILL.md 그 자체가 아니라, description 필드의 작성 방식에 있다.

description은 스킬의 「검색 쿼리(search query)」

Claude Code는 세션 시작 시, 모든 SKILL.md의 description만을 읽어 들여 목록을 메모리에 올린다. 사용자의 발화와 의미적으로 가까운 것을 선택하는 메커니즘으로 되어 있기 때문에, description은 「이 스킬을 호출해야 하는 상황」을 자연문으로 표현한 검색 쿼리로서 작성할 필요가 있다.

실제로 실수했던 사례를 솔직하게 적는다. blog-seo-improve의 description을 처음에는 이렇게 작성했었다.

# Bad: 기능 설명만 있고, 언제 호출해야 하는지 적혀 있지 않음
description: 'Improve SEO of blog articles'

「SEO 개선」이라고 부탁해도 전혀 동작하지 않는다. description을 이렇게 고쳐 쓴 순간, 딱 맞게 호출되기 시작했다.

# Good: 동사 + 대상 + 호출 키워드가 갖춰져 있음
description: 'GSC/GA 데이터를 기반으로 title/description/도입 섹션을 개선한다. 사용자가 「SEO 개선」 「CTR 개선」이라고 의뢰했을 때'

description을 작성할 때의 체크리스트는 딱 3가지뿐이다.

  • 동사로 시작할 것 (추출해줘, 분석한다, 개선한다)
  • 대상 오브젝트를 명시할 것 (MDX 기사, GitHub issue)
  • 사용자가 어떻게 부탁할지를 자연문으로 작성할 것 (~라고 말했을 때 / ~를 의뢰받았을 때)

왜 「동사 + 대상 + 호출 키워드」인가

「기능을 설명하면 된다」고 생각하기 쉽지만, Claude가 스킬을 선택하는 것은 기능 기반이 아니다. 사용자 발화와의 시맨틱(semantic)한 유사성으로 선택한다.

'Improve SEO of blog articles'는 기능에 대한 설명이지, 사용자가 실제로 말하는 단어가 아니다. 반면, 「사용자가 『SEO 개선』이라고 의뢰했을 때」라는 작성 방식은 사용자의 발화 그 자체가 description 안에 포함되어 있다. 일치하기 쉽다.

작성 방식선택될 확률이유
기능 설명만△사용자 발화와 괴리가 생기기 쉬움

경합(conflict)이 발생했을 경우에는, 부정 조건을 덧붙이는 것이 효과적이다. blog-mv-date(단일 기사 날짜 변경)와 blog-swap-dates(2개 기사의 날짜 교환)가 경합할 때, blog-mv-date의 description에 「2개 기사 교환에는 사용하지 않음」이라고 적은 것만으로 오작동이 멈췄다. 부정 조건을 처음부터 전부 적을 필요는 없다. 경합이 현저해진 뒤에 추가해도 충분하다.

「메모리 저장으로 해결했습니다」에 속지 마라

description을 수정하지 않고 방치하면, Claude가 다음과 같이 대답할 때가 있다.

앞으로 「이 숫자, 공식 소스와 맞아?」라고 말할 때는
blog-fact-check를 호출하도록 프로젝트 메모리에 저장해 두었습니다.

언뜻 보기에는 친절해 보인다. 하지만 이것은 근본적인 해결책이 아니다.

메모리에 「이렇게 말하면 이 스킬을 호출한다」라고 적는 것은 대증요법이며, 스킬 본체의 description이 적절하게 작성되어 있다면 불필요한 일이다. 메모리는 개별 프로젝트에 국한되고, 세션을 넘어가면 효과가 약해지며, 다른 멤버와는 공유되지 않는다.

나는 다음과 같이 대답하도록 하고 있다.

그거, 메모리 저장으로 근본적인 해결이 된 거야?
스킬 자체의 description에 호출 키워드가 들어있지 않은 게 원인 아니야?
SKILL.md 측을 수정하는 안도 내놓아서 비교하게 해줘.

이 한마디로 Claude는 description에 대한 추가 제안을 구체적으로 내놓는다. 거기서 비로소 「역시 스킬 본체의 문제였네요」라고 합의를 보고, diff 기반으로 수정이 이루어진다.

나는 이렇게 사용하고 있다

description에 관해서는, 지금은 이 규칙을 지키고 있다.

스킬을 만들면 우선 description만 다시 읽는다. 코드 예시보다 먼저. 실행 워드(起動ワード)가 자연문으로 들어가 있는지 확인한다. -
호출되지 않는다면 description을 수정한다. SKILL.md 본체를 에디터로 열기 전에, Claude에게 "왜 호출되지 않았는지"를 상담하여 description 수정안을 내놓게 한다. -
메모리 저장으로 회피하지 않는다. 스킬 수가 늘어나면 메모리에 구제 규칙(救済ルール)이 쌓여간다. 그것은 스킬 설계의 버그가 축적되고 있다는 신호다.

SKILL.md를 대충 만드는 것 자체는 나쁘지 않다. 하지만 description만큼은 처음부터 "사용자가 어떻게 요청할 것인가"를 의식하며 작성할 가치가 있다. 그 부분을 정성스럽게 쓰는 것만으로도 스킬의 호출 정밀도는 명확하게 달라진다.

원문 기사

이 기사는 skill.md란? 작성의 최단 경로와 운용 시 주의할 점의 핵심 부분을 재구성한 것입니다. 원문 기사에서는 다음과 같은 내용을 더 다루고 있습니다:

  • SKILL.md의 최소 구성과 최단 시간 내에 1개를 만드는 절차 (Claude에게 "skill화 해줘"라고 요청하는 방법)
  • 스킬 간의 충돌이 10개를 넘어가는 시점부터 발생하는 이유와, 오케스트레이터 (Orchestrator) 설계에서의 해결법
  • 300행을 초과한 SKILL.md를 references/로 분할하여 컨텍스트 소비를 줄이는 접근법
  • 프로젝트 고유값을 skill-config.json으로 분리하는 포터블 (Portable) 설계

이 기사는 playpark Blog로부터 전재되었습니다.

Discussion

AI 자동 생성 콘텐츠

본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0