Claude Code의 Skills 생성 시 자주 하는 실수 5가지

Claude Code를 사용하기 시작하여 Skills를 직접 만들어 보았지만, "생각보다 잘 작동하지 않는다", "정밀도가 안정적이지 않다"라고 느낀 적이 없으신가요?

Skills 기능은 한 번 제대로 활용하면 개발 경험이 완전히 바뀌지만, 초기에는 몇 가지 "함정"에 빠지기 쉽습니다. 이 기사에서는 제가 실제로 시행착오를 겪으며 깨달은 자주 하는 실수 5가지를 정리했습니다. 다 읽고 나면 "아, 그래서 잘 안 됐던 거구나"라고 납득하게 될 것입니다.

Claude Code의 Skills 생성으로 고민하고 계신가요?

결론부터 말씀드리면, Skills가 제대로 작동하지 않는 원인의 대부분은 "언제・어디서・어떻게 사용할지에 대한 정의가 모호한 것"으로 귀결됩니다.

PREP법으로 정리하면 다음과 같습니다.

관점	내용
Point (결론)	Skills의 실패는 거의 "정의의 모호함"이 원인
Reason (이유)	Claude는 Skills의 description에 의존하여 트리거를 판단하기 때문
Example (예시)	description이 너무 넓으면 의도하지 않은 타이밍에 발화함
Point (재결론)	정의를 명확히 하는 것만으로도 정밀도가 극적으로 향상됨

Claude가 Skills를 선택할 때 의존하는 것은 거의 description 필드의 내용입니다. 사람이 README를 읽고 "이 도구를 사용하자"라고 판단하는 것과 마찬가지로, Claude도 description을 읽고 "이 Skill이 지금 상황에 맞다"라고 판단합니다.

즉, description이 모호하면 Claude가 올바르게 판단할 수 없는 것은 당연한 이야기입니다. 저는 이를 깨닫기 전, "어떻게든 작동할 것 같은 설명"을 적곤 했습니다. 그것이 가장 큰 실수였습니다.

description은 "어떤 파일이 관련될 때", "어떤 조작을 요구받았을 때", "무엇을 해서는 안 될 때"까지 명시해야 비로소 기능합니다. 30자 내외로 쓸 수 있는 description은 거의 확실히 불충분합니다.

가장 흔한 실수입니다.

❌ 나쁜 예

설명: "문서를 작성하는 스킬"

✅ 좋은 예

description: "Markdown 파일이나 기술 사양서 작성・편집을 수행하는 스킬. 사용자가 '문서를 써줘', 'README를 업데이트해줘'라고 말했을 때 사용합니다. 코드 생성이나 데이터 분석에는 사용하지 않습니다."

description은 트리거 조건・사용 상황・제외 조건의 3종 세트로 작성하는 것이 기본입니다.

항목	내용의 예
트리거 조건	"~파일이 포함될 때", "~라고 말했을 때"
...

SKILL.md를 "레시피"라고 생각하면 절차만 적기 쉽습니다. 하지만 Claude에게 SKILL.md는 "문맥의 보충 정보"이기도 합니다.

❌ 나쁜 예 (절차만)

파일을 읽는다

내용을 정형화한다

출력한다

✅ 좋은 예 (의도・주의점・예시를 포함)

목적

이 스킬은 ~라는 과제를 해결하기 위해 사용합니다.

절차

파일을 읽는다 (문자 인코딩에 주의)

내용을 정형화한다

출력한다

주의점

바이너리 파일에는 사용하지 않는다

출력 위치는 반드시 /mnt/user-data/outputs/로 한다

출력 예시

... (구체적인 예시)

◎ "왜 그렇게 하는지"에 대한 의도를 적으면, Claude가 응용 상황에서도 올바르게 작동해 줍니다.

"무엇이든 할 수 있는 스킬을 하나 만들자"라고 생각하면 실패합니다. 스킬의 입도(granularity)가 커질수록 description도 모호해지며, 정밀도가 떨어집니다.

설계	특징	결과
❌ 1개 스킬에 무엇이든 담기	description이 필연적으로 모호해짐	의도하지 않은 발화・오작동
...

저는 처음에 document-skill이라는 스킬에 README 작성・사양서 작성・회의록 작성을 모두 담았습니다. 예상대로 어떤 케이스에서도 어중간한 동작을 보였습니다.

Skills를 사용하여 파일을 생성하게 하면, 출력 위치가 매번 제각각이 되는 경우가 있습니다. 이는 SKILL.md에 출력 경로의 제약을 적지 않았기 때문입니다.

# ✅ SKILL.md에 반드시 적어야 할 항목
## 출력 위치
- 최종 결과물은 반드시 `/mnt/user-data/outputs/`에 저장한다
...

Claude Code에는 파일 시스템 규칙이 있습니다. 이를 명시하지 않으면 Claude가 "아마 여기겠지"라고 판단해 버립니다.

「이 스킬은 이럴 때 사용한다」를 작성할 때, 긍정적인 조건(Positive conditions)만 작성하기 쉽습니다. 하지만 실제로는 「유사한 다른 스킬」이 존재하는 경우, 어느 것을 사용해야 할지 망설이게 됩니다.

❌ 나쁜 예 (저지르기 쉬운 실수)

스킬 A의 설명: 「Python 코드를 작성하는 스킬」 스킬 B의 설명: 「데이터 분석 코드를 작성하는 스킬」

✅ 좋은 예 (혼선을 방지함)

스킬 A의 설명: 「범용적인 Python 스크립트를 작성하는 스킬. 데이터 분석·대화가 주 목적일 경우에는 데이터 분석 스킬을 사용할 것."

스킬 B의 설명: 「데이터 분석·그래프 작성을 전용으로 하는 Python 코드를 작성하는 스킬. pandas나 matplotlib 등의 분석 라이브러리를 사용하는 경우로 한정하여 사용함."

◎ 스킬 간의 「역할 분담(Separation of concerns)」을 시키려면, description에 다른 스킬에 대한 언급을 넣는 것이 효과적입니다.

실수	대책
❌ description이 모호함	트리거(Trigger)·상황·제외의 3종 세트로 작성
...

Skills를 잘 설계할 수 있다면, Claude Code의 사용 편의성이 정말 크게 달라집니다. 초기 설계에 약간의 시간을 투자하는 것만으로도 이후의 경험이 완전히 달라지므로, 꼭 시도해 보시기 바랍니다.