Claude Code Skills에서 왜 그런 설계를 하는가 — 명명(Naming)·입도(Granularity)·description 설계의

이 기사는 playpark Blog에서 전재되었습니다.

• Skill 명명 시 외부 서비스명을 붙여서는 안 되는 이유
• Skill을 분할하지 않고 통합 측으로 몰아주는 판단 기준
• description을 「사양서」가 아니라 「발화 확률의 조정치」로서 설계하는 이유

Claude Code Skills를 50개 이상 운용하다 보면, SKILL.md의 작성 방식은 통일되어 있는데도 「사용하기 불편함」이 남는 상황이 발생합니다. 발화하지 않거나, 호출할 때 망설여지거나, 규약 위반이 인지하지 못한 채 혼입되는 경우입니다.

원인은 「작성 방식」이 아니라 「설계 판단」에 있습니다. 본 기사에서는 명명(Naming)·입도(Granularity)·description의 3가지 관점에서, 왜 그렇게 설계하는지에 대한 판단 기준을 해설합니다.

Skill의 명명에는 3가지 접근 방식이 있습니다.

접근 방식	장점	단점
외부 서비스명 접두사 (ig-post)	직관적이며 용도를 즉시 알 수 있음	서비스 변경·확장에 따라 명명과 내용이 모순됨
기능 기반 (동사 + 범용 대상)	서비스 변화에 강함	처음에는 추상적으로 느껴질 수 있음
내부 구현 상세 (json-merge-runner)	구현이 명확함	호출 측에서 용도를 추측할 수 없음

동영상 공지 계열의 Skill에서 외부 서비스명 접두사를 채택했던 시기가 있었습니다. 기능은 동작했지만, 다른 플랫폼으로의 확장이 필요해졌을 때 명명과 내용이 모순되었습니다.

(Skill 명): 특정 서비스 전용임을 시사
(실제 내용): 복수 플랫폼 대응 로직

새로운 멤버가 "왜 이 이름에 다른 플랫폼의 처리가 들어있나요?"라고 물어옵니다. 답변에 막히는 순간이 개명 판단의 신호입니다.

기능 기반의 명명을 선택하는 이유:

• 서비스 측의 변화(사양 변경·폐지·상위 호환)에 영향을 받지 않음
• description을 통해 발화시키는 것을 전제로 하므로, Skill 명은 짧고 용도가 전달되면 충분함
• 리네임(Rename) 비용은 빠를수록 낮음. Skill 수가 늘어날수록 의존하는 곳도 늘어나기 때문에, 망설여진다면 빨리 개명할 것

설계	장점	단점
책임(Responsibility)별 분할 (게시/스케줄/동기화)	설계상의 정리 정돈	사용하는 측의 선택 부하가 증가함
통합 + 서브 커맨드(Sub-command) 구성	호출하는 측의 인지 부하가 낮아짐	SKILL.md가 비대해지기 쉬움

SNS 게시 계열의 Skill을 3개로 나누었던 시기가 있었습니다. 설계상으로는 깔끔했지만, 실제 운용에서는 "게시 쪽인가, 스케줄 쪽인가, 동기화 쪽인가"를 매번 판단해야 했습니다. 3개의 Skill이 내부적으로 서로를 호출하기 때문에 기점도 모호해졌습니다.

통합 측으로 몰아주는 이유:

• Skill을 나누는 비용은 사용하는 측이 지불함. "어느 것을 호출해야 했더라"를 매번 판단하는 부하는 설계상의 정리 정돈이 미흡하여 발생하는 전가임
• 서브 커맨드 (post / schedule / sync)로 기능을 흡수하면, 발화의 단일성과 기능의 다양성을 양립할 수 있음

통합 Skill
├─ post 서브 커맨드 → 게시 실행
├─ schedule 서브 커맨드 → 게시 예약
...

나누어야 할 판단 기준: 명확하게 다른 발화 조건을 가질 때만. 「게시」와 「분석」처럼 호출하는 장면도 입력도 출력도 다른 것은 나눈다. 「게시」와 「게시 스케줄」처럼 동일한 목적 내에서 시간축만 다른 것은 서브 커맨드로 흡수한다.

description 필드를 사양서로서 작성하면 발화에 문제가 생깁니다.

문제가 발생한 예:

(초기 description): Investigates complex bugs through hypothesis-driven multi-agent analysis
(실제 호출): "이 버그 조사해줘" (일본어)
(결과): 발화하지 않음

AI의 트리거(Trigger) 판정은 의미 매칭(Semantic Matching)입니다. 영어의 "bug investigation을 기대하는 Skill"로 보이기 때문에, 일본어의 "버그 조사해줘"와 의미적으로 대응하지 않습니다.

개선 후의 description 설계 원칙:

description: |
Agent Team을 사용한 협업형 멀티 에이전트 (multi-agent) 버그 조사.
사용 시점: (1) 근본 원인이 불분명한 복잡한 버그, (2) 간헐적/재현하기 어려운 이슈,
...

설계 요소	이유
영어·일본어 키워드를 모두 나열	양쪽 언어에서의 트리거 (trigger) 확률이 안정됨
Use when을 불렛 포인트로 명시	유사한 용도의 다른 Skill과의 충돌이 감소
Accepts args를 기술	인자 (argument)가 포함된 호출 시 Skill 측이 확신을 갖기 쉬움

상황	판단 기준
새로운 Skill의 명명	기능 기반. 외부 서비스명은 회피
...

이 기사에서는 명명(Naming)·입도(Granularity)·description의 설계 판단 이유를 해설했습니다.

【Claude Code】Skills 운용에서 효과를 본 판단 - 명명·입도·description 튜닝의 실전 지식 에서는 더욱:

• 폴백 (Fallback) 설계 (gh pr review --approve → --comment로의 Graceful Degradation)
• 실패 로그가 30일간 0건이었던 버그의 기술적 원인 (hook의 payload schema 오독 + bash의 조용한 실패)
• lint 스크립트를 통한 규약의 기계적 검증과 CI 도입 방법

playpark LLC - 업무 자동화·AI 활용·Web 개발