AI툴 · 클로드

클로드 스킬 2탄: Claude Code 스킬 배치·호출법

지난 글에서는 클로드 스킬(Claude Skills)을 claude.ai 웹에서 업로드해 쓰는 기본 절차를 다뤘습니다. 그런데 터미널 기반의 Claude Code를 쓰는 분이라면 사정이 조금 다릅니다. .claude/skills/ 폴더에 SKILL.md를 만들어놓고도 정작 필요한 순간에 스킬이 켜지지 않거나, 팀원과 공유하려는데 어디에 둬야 할지 헷갈리는 경우가 적지 않습니다. description을 대충 한 줄 적었다가 스킬 자체가 조용히 무시당하는 사례도 드물지 않습니다.

Claude Code 스킬, 어디에 두고 어떤 순서로 읽힐까요

Claude Code에서 스킬이 저장되는 위치는 네 단계로 나뉩니다. 관리자가 조직 차원에서 배포하는 Enterprise, 개인 홈 디렉토리에 두는 Personal(~/.claude/skills/<이름>/SKILL.md), 저장소 안에 두는 Project(.claude/skills/<이름>/SKILL.md), 그리고 플러그인에 포함되는 Plugin 방식입니다. 이름이 겹치면 Enterprise가 Personal을, Personal이 Project를 덮어씁니다.

프로젝트 스킬은 지금 작업 중인 폴더부터 저장소 루트까지, 상위 경로에 있는 .claude/skills/를 전부 훑어서 불러옵니다. 모노레포처럼 하위 폴더(예: packages/frontend/.claude/skills/)에 따로 스킬을 둘 수도 있는데, 이 경우 해당 폴더의 파일을 다룰 때만 자동으로 로드됩니다. 이름이 겹치는 중첩 스킬은 apps/web:deploy처럼 경로가 붙은 이름으로 함께 살아남고, Claude가 지금 작업 중인 파일 위치에 맞춰 알아서 골라 씁니다.

스킬 파일을 고치면 세션을 새로 시작할 필요 없이 바로 반영됩니다. ~/.claude/skills/든 프로젝트 .claude/skills/든, --add-dir로 추가한 디렉토리 안 스킬이든 마찬가지입니다. 다만 세션을 시작한 시점에 없던 최상위 스킬 디렉토리를 새로 만든 경우엔 예외입니다. 이때는 재시작이 필요합니다. 여기서 다들 한 번씩 헷갈립니다.

클로드 스킬 자동 호출과 직접 호출, 그 사이

스킬을 어떻게 부를지도 세밀하게 조정할 수 있습니다. 기본값은 사람이 /스킬이름으로 직접 부르는 것과 Claude가 필요하다고 판단해 알아서 부르는 것, 둘 다 가능한 상태입니다.

배포나 커밋처럼 되돌리기 번거로운 작업에는 disable-model-invocation: true를 걸어두는 편이 안전합니다. Claude가 맥락만 보고 실행 버튼을 누르는 상황을 막아주기 때문입니다. 반대로 사람이 명령어를 잘못 눌러 문제가 생기는 걸 막고 싶다면 user-invocable: false로 참고 지식 용도로만 묶어둘 수 있습니다. claude.ai 웹에는 이렇게 세분화된 호출 제어 자체가 없습니다. 다만 이런 옵션들은 문서상 최소 지원 버전이 각기 다르게 표시돼 있어서(추정), 쓰고 있는 Claude Code 버전이 오래됐다면 일부는 아직 적용되지 않을 수 있습니다.

의외로 잘 모르는 함정 — 클라우드 세션은 로컬 스킬을 못 읽습니다

개인 스킬만 로컬에 만들어둔 상태에서 예약 routine이 그 스킬을 부르면 “스킬을 찾을 수 없음” 오류가 뜹니다. 실무에서 자주 보고되는 증상이 바로 이겁니다. 분명 터미널에서는 잘 되던 스킬이 예약 실행에서는 먹통이 되는 상황입니다. 해결책은 세 가지 중 하나입니다. claude.ai 계정에도 같은 스킬을 등록하거나, 저장소에 스킬 파일을 커밋해 프로젝트 스킬로 만들거나, 저장소 설정에 선언된 플러그인으로 배포하는 방법입니다.

공식 예시 스킬 뜯어보기: internal-comms와 brand-guidelines

Anthropic이 공개한 anthropic-skills 저장소에는 문서 처리용 스킬(docx, pdf, pptx, xlsx) 말고도 실제로 열일곱 개의 스킬 폴더가 들어 있습니다(2026년 7월 확인 기준). 이 중 사내 문서 업무와 맞닿아 있는 두 가지를 살펴보겠습니다.

internal-comms 스킬의 frontmatter는 description을 이렇게 적어뒀습니다. “회사가 선호하는 형식으로 각종 사내 커뮤니케이션(상태 보고, 리더십 업데이트, 3P 업데이트, 사내 뉴스레터, FAQ, 인시던트 리포트, 프로젝트 업데이트 등) 작성을 돕는 자료 모음이며, 이런 종류의 사내 커뮤니케이션 작성을 요청받을 때마다 이 스킬을 써야 한다”는 취지입니다.

실제 동작은 단순합니다. 먼저 요청받은 커뮤니케이션 유형이 3P 업데이트인지 뉴스레터인지 FAQ인지 파악하고, examples/ 하위 폴더에서 그 유형에 맞는 가이드라인 파일을 불러와 형식과 톤을 맞추는 구조입니다.

이 구조를 그대로 국내 직장인의 반복 업무에 옮겨보면 쓸모가 커집니다. 주간보고서, 회의록, 사내 공지처럼 회사마다 정해진 양식과 톤이 있는 문서를 examples/ 폴더에 유형별로 정리해두고, SKILL.md가 요청 유형을 판단해 맞는 예시를 불러오게 만드는 식입니다. 매번 “이전에 쓰던 양식대로 다시 써줘”라고 반복 설명할 필요가 없어집니다.

brand-guidelines 스킬은 description에 “Anthropic 공식 브랜드 컬러와 타이포그래피를 각종 산출물에 적용한다. 브랜드 색상이나 스타일 가이드, 시각적 포맷, 회사 디자인 표준이 필요할 때 쓴다”고 적어뒀습니다.

실제로는 메인 컬러·포인트 컬러 체계와 제목용·본문용 폰트 규칙을 정의해, 문서나 슬라이드 같은 결과물에 일관된 톤을 자동으로 입힙니다. 다만 이 스킬은 Anthropic 자사 색상과 폰트를 그대로 담고 있어서 다른 회사가 통째로 가져다 쓸 수는 없습니다. 벤치마킹할 부분은 내용물이 아니라 “회사 고유의 색상·폰트 규칙을 스킬 하나에 고정해두는 구조” 그 자체입니다.

SKILL.md 작성법: description이 반입니다

스킬을 만들어놓고 “왜 안 켜지지”라는 질문을 하게 되는 원인은 십중팔구 description에 있습니다. Claude가 지금 이 스킬을 써야 하는지 판단하는 유일한 단서가 description이기 때문입니다.

YAML frontmatter 요구사항부터 짚어보겠습니다. name은 최대 64자, 소문자와 숫자, 하이픈만 허용되고 XML 태그나 “anthropic”, “claude” 같은 예약어는 쓸 수 없습니다. description은 비워둘 수 없고 최대 1,024자까지이며, 역시 XML 태그는 금지입니다. 무엇보다 “무엇을 하는지”와 “언제 쓰는지”를 반드시 함께 담아야 하고, 3인칭으로 써야 한다는 점이 명시돼 있습니다.

이름을 지을 때는 동사에 -ing를 붙인 동명사형을 권장합니다. processing-pdfs, analyzing-spreadsheets, managing-databases 같은 식입니다. 반대로 helper, utils, tools, documents, data처럼 모호하고 포괄적인 이름은 피해야 합니다. 이름 자체가 이미 하나의 힌트이기 때문입니다.

참고 파일 구조에도 규칙이 있습니다. SKILL.md 본문은 500줄을 넘기지 않아야 하고, 세부 참고자료(reference.md 등)는 SKILL.md에서 딱 한 단계 깊이로만 링크해야 합니다. SKILL.md에서 advanced.md를 링크하고 advanced.md가 다시 details.md를 링크하는 식으로 참조가 중첩되면, Claude가 head -100 같은 명령으로 파일 일부만 미리 보고 넘어가면서 정보를 놓칠 수 있다고 공식 문서는 경고합니다. 참고 파일이 100줄을 넘어간다면 목차부터 넣어야 부분 미리보기만으로도 전체 범위를 가늠할 수 있습니다.

문서를 먼저 쓰지 말라는 조언도 눈에 띕니다. 스킬 없이 Claude에게 실제 과제를 먼저 시켜보고, 구체적으로 실패하는 지점 세 가지를 찾아낸 다음 그 갭만 메우는 최소한의 지침을 쓰라는 순서입니다(evaluation-driven development). 스킬을 설계하는 Claude와 그 스킬을 실제로 써서 일하는 Claude를 번갈아 돌려가며 관찰과 개선을 반복하는 방법도 함께 제시돼 있습니다.

다만 이 글자수 기준이 완전히 깔끔하지는 않습니다. best practices 문서는 description 상한을 1,024자로 못박아두는 반면, Claude Code 문서는 description과 when_to_use를 합쳐 1,536자에서 자른다고 설명합니다. 어느 쪽이 실제로 적용되는 상한인지 두 문서를 오가며 확인해도 명확한 상호 참조 문구는 찾을 수 없었습니다. description은 애초에 짧고 명확하게 쓰는 편이 안전합니다.