Claude Code Skill 사용 경험 - 왜 user-invocable: false로 설계했나

들어가며

Claude Skill을 처음 만들 때는 보통 "이걸 어떻게 호출하지?"부터 생각하게 됩니다. 저도 처음에는 비슷했습니다. 그런데 디자인 시스템 관련 Skill을 정리하면서 방향이 조금 달라졌습니다. 제가 원한 것은 호출 가능한 기능 세트가 아니라, Claude가 언제 물어봐도 같은 기준으로 답하게 만드는 내부 판단 레이어였습니다.

그래서 `design-system-color`, `design-system-spacing`, `design-system-shape`, `design-system-typography` 같은 Skill을 만들면서 일부러 user-invocable: false를 넣었습니다. 이 글은 왜 그렇게 했는지, 그리고 그 선택이 디자인 시스템을 수정하거나 확장할 때 어떤 차이를 만들었는지에 대한 기록입니다.

왜 직접 호출 가능한 Skill로 만들지 않았나

겉으로 보기에는 Skill을 직접 호출할 수 있게 열어두는 편이 더 친절해 보입니다. 하지만 제 목적에는 오히려 반대였습니다. 사용자가 스킬 이름을 기억하고 명령어처럼 불러야 하는 구조보다, 그냥 자연스럽게 질문하면 Claude가 내부 기준을 참고해 답하는 구조가 더 맞았습니다.

특히 디자인 시스템은 단순히 질문에 답하는 주제가 아니라, 시간이 지나면서 계속 변경되고 보완되는 규칙 집합에 가깝습니다. "이 spacing token을 바꿔도 될까?", "새로운 semantic color를 추가할 때 기준이 뭐지?", "radius 규칙을 컴포넌트 전반에 어떻게 반영하지?" 같은 상황에서는 사용자가 스킬 이름을 떠올리는 것보다, Claude가 내부적으로 기준을 안정적으로 참조하는 편이 훨씬 중요했습니다.

직접 호출 중심

사용자가 스킬 이름과 사용법을 알아야 합니다. 결국 기능을 노출하는 쪽에 초점이 맞고, 질의 경험은 오히려 불필요하게 복잡해질 수 있습니다.

내부 기준 중심

사용자는 평소처럼 자연어로 질문하고, Claude만 내부적으로 Skill을 참고합니다. 인터페이스는 단순해지고, 답변 기준은 더 안정적으로 유지됩니다.

user-invocable: false에 담았던 의도

이 설정은 단순히 "숨겨두기"가 아니었습니다. 제 경우에는 이 Skill의 역할을 기능이 아니라 기준으로 한정하려는 선언에 가까웠습니다. 사용자가 직접 호출하는 순간, 이 Skill은 운영 문서보다 명령형 도구처럼 인식되기 쉽습니다.

그렇게 되면 문제가 두 가지 생깁니다. 하나는 사용법 자체를 또 학습해야 한다는 점이고, 다른 하나는 "언제 이 스킬을 써야 하지?"라는 메타 질문이 새로 생긴다는 점입니다. 저는 디자인 시스템을 다룰 때 필요한 것이 호출 절차가 아니라, 변경이나 확장 상황에서도 같은 기준을 유지하는 일이라고 봤기 때문에 그 부담을 사용자 쪽에 넘기고 싶지 않았습니다.

.claude/skills/design-system-color/SKILL.md YAML

---
name: design-system-color
description: Nevera 컬러 디자인 시스템 가이드
user-invocable: false
---

당신은 Nevera의 컬러 디자인 시스템 가이드다.
역할은 프로젝트의 시맨틱 토큰 구조를 기준으로
컬러 사용을 일관되게 유지하는 것이다.

내가 원한 사용 방식은 이런 흐름이었다

핵심은 사용자가 Skill의 존재를 몰라도 되는 흐름이었습니다. 개발자는 평범하게 질문하고, Claude는 필요한 순간에만 내부 규칙을 가져와 판단합니다. 이 방식은 디자인 시스템처럼 규칙이 계속 수정되고 확장되는 주제에서 특히 자연스러웠습니다.

Step 1 · 개발자 질문 "이 카드 내부 패딩은 어떤 spacing token이 맞아?" 또는 "새 semantic color를 추가할 때 기준이 뭐야?"처럼 자연어로 그냥 물어봅니다.

↓

Step 2 · Claude 판단 질문이 spacing 검토인지, 컬러 규칙 추가인지 같은 맥락을 파악하고 대응되는 Skill을 내부적으로 선택합니다.

↓

Step 3 · 기준 참조 `NeveraTheme.spacing.*`, 하드코딩 금지, `XxxDimension` 분리 규칙 같은 내용을 기준으로 답변을 구성합니다.

↓

Step 4 · 일관된 응답 사용자는 스킬을 호출하지 않았지만, 결과는 항상 같은 규칙에 기반한 답변을 받습니다.

실제로는 유지보수 측면에서도 이 방식이 더 좋았다

이 구조의 장점은 사용 경험만 단순해지는 데 있지 않았습니다. 유지보수 포인트도 분명해졌습니다. 디자인 시스템 규칙이 바뀌거나 새로운 기준을 추가해야 할 때, 프롬프트 예시를 여러 군데 고치는 대신 Skill 파일만 수정하면 됩니다. 질문 방식은 그대로 두고 내부 기준만 최신화할 수 있다는 점이 컸습니다.

질문 인터페이스와 규칙 저장소를 분리할 수 있다

개발자는 계속 자연어로 묻습니다. 반면 운영자는 Skill 문서에서 판단 기준만 관리하면 됩니다. 이 분리가 되면 "어떻게 물어봐야 좋은 답이 나오는지"를 교육하는 비용도 줄어들고, 규칙 개정이 생겨도 수정 지점이 명확해집니다.

규칙 변경이 생겨도 사용 방식은 바뀌지 않는다

예를 들어 spacing 토큰이나 typography 선택 기준이 조금 바뀌더라도, 사용자는 여전히 같은 방식으로 질문하면 됩니다. 바뀌는 것은 Skill 내부 지식뿐이고, 외부 인터페이스는 고정됩니다. 디자인 시스템처럼 계속 다듬어야 하는 주제에서는 이 고정된 인터페이스가 특히 중요하다고 느꼈습니다.

UX질의

사용자는 자연어만 기억하면 된다

스킬 이름, 호출 문법, 인수 형식을 외울 필요가 없습니다. 그냥 디자인 시스템을 수정하거나 검토할 때 필요한 질문을 던지면 됩니다.

OPS기준

운영자는 Skill 문서만 업데이트하면 된다

규칙이 바뀌거나 새 기준이 추가될 때 수정 대상이 분산되지 않습니다. 지식이 한곳에 모여 있으니 관리가 단순해집니다.

AI응답

Claude는 더 일관된 기준으로 답한다

그때그때 떠올린 설명이 아니라, 명시된 판단 절차와 금지 규칙을 따라가게 됩니다.

결국 이건 숨겨진 기능이 아니라 설계된 제약이었다

AI를 쓸 때는 기능을 더 열어두는 것이 무조건 좋아 보일 때가 많습니다. 하지만 실제로는 무엇을 노출하고 무엇을 내부 규칙으로 남길지 구분하는 일이 더 중요할 수 있습니다. 제 경우 디자인 시스템 Skill은 누군가가 직접 호출하는 도구보다, Claude의 답변을 흔들리지 않게 만드는 기준 문서에 가까웠습니다.

그래서 `user-invocable: false`는 제약이라기보다, 제가 원하는 사용 경험을 만들기 위한 설계 선택이었습니다. 사용자는 더 편하게 질문하고, Claude는 디자인 시스템을 변경하거나 확장하는 상황에서도 더 일관되게 답하게 만드는 방향이었기 때문입니다.

Key Points

• 직접 호출을 막은 이유는 기능을 숨기기 위해서가 아니라, 자연어 질의를 기본 인터페이스로 유지하기 위해서였습니다.
• 디자인 시스템 Skill의 역할은 자주 묻는 질문 대응보다, 변경과 확장 상황에서도 내부 판단 기준을 유지하는 데 더 가까웠습니다.
• user-invocable: false는 사용성 저하가 아니라 역할 분리를 위한 설정이었습니다.
• 유지보수 관점에서는 질문 방식은 그대로 두고, Skill 문서만 업데이트하면 된다는 점이 특히 유용했습니다.
• 결론적으로 이 설계는 Claude를 더 많이 하게 만든 것이 아니라, 더 일관되게 답하게 만든 선택이었습니다.