Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code Skill은 `SKILL.md` 파일에 정의되며, YAML 헤더의 이름과 설명을 통해 Claude가 사용 시점을 판단합니다. 스킬 내용은 요청이 필요할 때만 로드되어 비용 효율적이며, 개발자는 프롬프트를 이용해 쉽게 개인 스킬을 생성하고 관리할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기원문은 khadim.tech에 게재되었습니다.
요약: Claude Code skill은 SKILL.md 파일이 포함된 폴더입니다. 이 파일에는 짧은 YAML 헤더가 있는데, 여기에 기재된 이름(name)과 설명(description)을 통해 Claude는 언제 해당 스킬을 사용해야 할지 알게 됩니다. 이후 스킬이 실행될 때만 로드되는 지침들이 포함됩니다. Claude는 요청 내용에 따라 스스로 적절한 스킬을 선택하거나, 사용자에게 /skill-name 형태로 직접 실행하도록 요청할 수 있습니다. 제가 Claude Code 2.1.310으로 108번의 테스트를 진행했을 때, 이름이나 설명 중 어느 하나라도 기능을 명시하면 매칭되는 요청 15건 중 15건에서 스킬이 로드되었고, 둘 다 명시하지 않았을 때는 15건 중 5건에서만 로드되었습니다. 또한 disable-model-invocation: true를 설정했을 때는 Claude가 스킬의 규칙 없이 작업을 수행했습니다.
저는 개인 에이전트 저장소(agent repo)에 71개의 스킬을 사용하여 Claude Code로 작업하며, 제 YouTube 채널 Khadim Labs에서 짧은 Claude Code 튜토리얼을 제작하고 있습니다. '스킬' 에피소드를 위해 저는 Claude Code에게 한 문장으로 스킬을 작성하도록 요청했고, 그 결과 제가 원하지 않았던 결정을 내렸습니다. 이에 저는 모든 가이드가
스킬(Skills)은 로딩 시점에 따라 비용이 저렴합니다. Claude Code는 컨텍스트에 이름과 설명만 유지하고, "전체 스킬 내용은 호출될 때만 로드됩니다." 400줄 분량의 절차는 요청이 필요할 때까지 거의 비용이 들지 않지만, CLAUDE.md 파일은 매 세션마다 전체가 로드됩니다. 스킬은 Agent Skills 오픈 표준을 따르며, Claude Code는 호출 제어(invocation control)나 서브 에이전트에서 스킬 실행과 같은 자체 필드를 추가합니다.
| 범위 (Scope) | 경로 (Path) | 누가 접근하나요? |
|---|---|---|
| 개인 (Personal) | ~/.claude/skills/<name>/SKILL.md | 이 컴퓨터의 모든 프로젝트에 있는 사용자 본인 |
| ... |
두 스킬이 같은 이름을 공유할 경우, 엔터프라이즈(enterprise)가 개인보다 우선하며, 개인은 프로젝트보다 우선합니다. 이전의 .claude/commands/deploy.md 파일들은 계속 작동하는데, 이는 "커스텀 명령어들이 스킬로 병합되었기" 때문에, 동일한 이름의 명령 파일보다 스킬이 우선권을 갖기 때문입니다. /skills는 Claude Code가 발견한 목록을 보여줍니다. 또한 이 폴더들을 감시하여, SKILL.md 파일을 새로 만들거나 수정하면 재시작 없이 실행 중인 세션에 즉시 반영됩니다.
수동으로 SKILL.md를 작성할 수도 있지만, 가장 빠른 방법은 원하는 바를 설명하는 것입니다. Claude Code 2.1.310이 실행되는 깨끗한 Windows VM에서 저는 다음과 같이 입력했습니다:
현재 폴더의 파일을 유형별로 하위 폴더에 정리하고, 스크린샷을 별도의 Screenshots 폴더에 넣고, 아무것도 삭제하지 않으며, 무엇이 이동했는지 짧은 표로 마무리하는 개인 스킬(personal skill) tidy-folder를 만들어 줘.
50초 후, 이 파일은 ~/.claude/skills/tidy-folder/SKILL.md라는 이름으로 생성되었고 길이는 2,936자였습니다. 이것이 편집되지 않은 프론트매터(frontmatter) 부분입니다:
---
name: tidy-folder
description: 현재 폴더의 느슨한 파일들을 유형별로 하위 폴더에 정리하고 (Images, Documents, Spreadsheets, Audio, Video, Archives, Code, Other), 스크린샷을 Screenshots 폴더에 넣고, 아무것도 삭제하지 않으며, 무엇이 이동했는지 표로 마무리합니다. 사용자가 폴더를 정리하거나, 청소하거나, 구성하거나, 분류하라고 요청할 때 사용하세요.
...
본문에는 제가 명시하지 않은 규칙들이 추가되었습니다. 이 기능은 폴더 내부에 직접 있는 파일에 대해서만 작동하며, 숨겨진 시스템 파일은 건너뜁니다. 이름 충돌이 발생하면 (1), (2) 등을 붙여 두 파일을 모두 유지하고, PowerShell의 Move-Item 명령어를 -Force 없이 사용하여 파일을 이동합니다. 만약 해당 폴더가 프로젝트처럼 보일 경우(예: .git 폴더, 솔루션 파일), 파일 이동이 문제를 일으킬 수 있기 때문에 멈추고 먼저 사용자에게 질문을 합니다.
저는 프론트매터의 마지막 줄을 요청한 적이 없습니다. disable-model-invocation: true를 사용하면 해당 스킬은 수동 전용(manual-only)이 됩니다. 즉, Claude가 스스로 로드하지 않으며, /tidy-folder를 입력할 때만 실행됩니다. Claude는 이 스킬이 파일을 이동시키기 때문에 이를 설정했습니다. 문서에서도 이 필드를
각 버전은 여섯 가지 요청을 받았습니다. 그중 다섯 개는 폴더를 정리하라는 내용이었고, 다른 단어로 표현되었으며, 나머지 하나는 단순히 '무엇이 들어있는지'만 묻는 것이었습니다. 저는 이 세트를 총 108회에 걸쳐 2026년 10월 26일에 실행했습니다. 모든 테스트는 여섯 개의 더미 파일(dummy files)과 스킬을 .claude/skills/ 폴더에서 가지고 시작했으며, Claude Code 2.1.310 및 Opus 5.5 (claude-opus-5-5) 모델에 대해 claude -p 헤드리스(headless) 방식으로 실행했습니다. 또한 스킬 목록에는 제 claude.ai 계정에 동기화된 아홉 개의 스킬(PDF, Word, Excel 등)도 포함되어 있었는데, 이들 중 폴더와 관련된 것은 없었습니다. 파일 명령은 차단되었기 때문에 실제로 이동한 것은 아무것도 없습니다.
| 이름 (Name) | 설명 (Description) | 스킬을 로드한 정리 요청 (Tidy requests that loaded the skill) | "이 폴더에는 어떤 파일들이 있나요?" ("What files are in this folder?") |
|---|---|---|---|
tidy-folder | Claude가 작성한 특정 스킬 | 15/15 | 0/3 |
| ... | |||
| Claude는 설명뿐만 아니라 이름도 읽었으며, 명확한 신호 하나만으로 충분했습니다. 알려주는 이름 아래 두 단어짜리 설명이 있을 때마다 트리거되었고, 반대로 의미 없는 이름에 알려주는 설명이 붙어도 마찬가지였습니다. 둘 다 아닐 경우 15개 중 5개에서 작동했습니다. 다섯 가지 정리 요청 방식은 실제 차이가 없었으며, 폴더 내용만 물어본 요청은 어떤 버전에서도 스킬을 로드하지 못했습니다. |
수동 실행 전용 행(manual-only row)은 다시 살펴볼 필요가 있습니다. Claude는 해당 스킬을 절대 로드하지 않았지만, 작업을 거부하지도 않았습니다. 15회 모든 테스트에서 스킬의 규칙 없이 PowerShell 또는 Bash로 직접 파일을 정리했습니다. 만약 그 규칙들이 중요하다면 (제 생각으로는 절대로 아무것도 삭제해서는 안 된다), /tidy-folder를 입력하거나 Claude가 스스로 스킬을 로드하도록 두어야 합니다.
이 테스트는 하나의 모델에서 한 스킬과 약 12개의 다른 스킬들을 비교합니다. 스킬이 훨씬 더 많아지면, Claude Code는 모든 이름은 유지하되 설명(description)을 목록에서 누락시키기 시작하며 (다음 섹션 참조), 이는 스킬의 기능을 따라 이름을 지정해야 하는 또 하나의 이유가 됩니다.
순서대로 다음 사항들을 확인해 보세요. 저는 이미 앞의 두 가지 경우를 겪었습니다.
disable-model-invocation: true가 설정되어 있습니다. 제 tidy-folder 스킬에서 볼 수 있듯이, 이 설정을 직접 작성하지 않아도 포함될 수 있으므로, 설명을 다시 작성하기 전에 프론트매터(frontmatter)를 읽어보세요.---일 때만 프론트매터를 읽습니다. YAML 마커 사이에 내용이 잘못 구성되어 있으면, 스킬은 필드 없이 로드되므로 /skill-name은 여전히 작동하지만 Claude에게 매칭할 설명이 없습니다. 필드 이름은 하이픈(-)을 포함하여 정확히 일치해야 하며, Claude Code는 알 수 없는 필드를 발견해도 오류를 내지 않습니다. claude --debug 명령어를 사용하면 파싱 오류가 표시됩니다./doctor 명령어는 목록의 비용을 추정하고, skillListingBudgetFraction 설정을 통해 예산을 높일 수 있습니다.paths를 설정합니다. 그러면 현재 작업 디렉토리(current working directory) 내의 일치하는 파일에 대해서만 활성화됩니다.가장 빠른 확인 방법은 Claude에게 "사용 가능한 스킬이 무엇인가요?"라고 묻는 것입니다. 만약 답변에 해당 스킬이 없다면, Claude는 그 스킬을 선택할 수 없습니다.
| 로드 시점 | 사용 용도 | |
|---|---|---|
CLAUDE.md | 모든 세션에서 전체적으로 | 항상 적용되는 사실과 규칙 |
| ... |
문서(docs)에서는 CLAUDE.md에서 무언가를 분리하는 간단한 테스트를 제공합니다: "채팅에 동일한 지침, 체크리스트 또는 다단계 절차를 계속 붙여넣거나, CLAUDE.md의 특정 섹션이 사실(fact)이라기보다는 절차(procedure)로 성장했을 때 스킬을 생성하세요." Claude가 매번 유지되어야 하는 규칙을 건너뛰는 경우, 그 규칙을 후크로 옮기는 것을 권장합니다.
제 자체 에이전트 레포(agent repo)에는 제가 머지 리퀘스트를 검토하는 방법, 이 사이트를 게시하고 YouTube 채널을 운영하는 방법 등 다양한 작업을 다루는 71개의 스킬이 담겨 있습니다. 두 가지 교훈은 저에게 실제 시간을 소모하게 했습니다.
스킬 이름을 내장 명령어(built-in command)와 같게 지으면 안 됩니다. 저는 resume이라는 CV 스킬을 가지고 있었는데, Claude Code의 내장 /resume 기능과 충돌하여 작동하지 않았습니다. 이는 문서화된 동작 방식입니다: "로컬 터미널 세션에서 사용자의 스킬이 내장 명령어를 대체하지만, 그 별칭(aliases)까지는 그렇지 않습니다." 그래서 저는 제 스킬 이름을 resume-cv로 변경했고, 이제 스킬을 인덱싱하는 스크립트는 내장된 이름은 거부합니다.
각 스킬의 복사본 하나만 유지하고 그것을 가리키도록 하세요. 제 스킬들은 Claude Code가 스캔하지 않는 일반 skills/ 폴더에 있습니다. 이 폴더에는 각 스킬에 대한 한 줄짜리 포인터(pointer)를 .claude/commands/<name>.md 파일로 작성하는 스크립트가 존재합니다("read skills/<name>/SKILL.md and follow it"). 이렇게 하면 /<name>으로 접근할 수 있으면서도 지침은 한 곳에 유지되며, 포인터가 누락되거나 오래된 경우 이 스크립트는 빌드 실패를 일으킵니다. 제가 처음 생성했을 때, 재시작 없이 이미 실행 중이던 세션에서 55개의 모든 포인터가 작동했습니다.
정리된 폴더 구조로 운영하는 스킬 에피소드는 제 YouTube 채널에서 확인하실 수 있습니다.
모호한 설명이 Claude가 스킬을 사용하는 것을 막나요?
이름만 명확하다면 그렇지 않습니다. 제가 테스트한 결과, "폴더 유틸리티(Folder utility)."라는 설명을 가진 tidy-folder 스킬은 15개의 tidy 요청 중 15개에서 로드되었습니다. 반면, "일반적인 도우미(General helper)."라는 설명의 helper 스킬은 15개 중 단 5개에서만 로드되었으므로, Claude에게 최소한 하나의 명확한 신호를, 가급적이면 두 가지 모두 제공해 주세요.
Claude Code 스킬이 컨텍스트(context)를 사용하나요?
조금 사용합니다. Claude Code는 모든 스킬의 이름과 설명을 컨텍스트에 유지하며, 스킬이 실행될 때만 전체 SKILL.md 파일을 로드합니다. 각 설명은 1,536자로 잘리며, 전체 목록은 모델의 컨텍스트 창(context window) 중 약 1%를 차지합니다. 그 이상을 초과하면 가장 적게 사용되는 스킬들은 설명을 잃지만 이름은 유지됩니다.
스킬을 추가한 후 Claude Code를 재시작해야 하나요?
Claude Code는 스킬 폴더를 감시하며 실행 세션에서 새롭거나 수정된 SKILL.md 파일을 가져옵니다. 예외는 세션 시작 시 존재하지 않았던 최상위 스킬 폴더입니다: 이 경우 /reload-skills를 실행해야 합니다.
스킬(skill)과 슬래시 명령어(slash command)의 차이점은 무엇인가요?
현재는 거의 없습니다. 커스텀 명령어는 스킬로 통합되었기 때문에 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md 모두 /deploy를 생성합니다. 스킬은 지원 파일과 누가 호출할 수 있는지 제어하는 프론트매터(frontmatter)를 위한 폴더를 추가하며, 둘 다 같은 이름으로 존재하면 스킬이 우선권을 가집니다.
Claude가 자체적으로 스킬을 사용하지 않게 하려면 어떻게 해야 하나요?
프론트매터에 disable-model-invocation: true를 추가하세요. 그러면 Claude Code는 사용자가 /skill-name을 입력할 때만 해당 스킬을 실행합니다. 여전히 평범한 단어로 요청하면 작업을 수행합니다: 제 테스트에서는 이 스킬이 로드되지 않았고, 매번 스킬의 규칙 없이 파일을 스스로 정렬했습니다.
스킬이 스크립트를 실행할 수 있나요?
네. 스크립트를 스킬 폴더에 넣고 SKILL.md에서 Claude에게 이를 실행하도록 지시하세요. 이때 경로에는 ${CLAUDE_SKILL_DIR}를 사용하여 스킬이 설치된 곳 어디서든 해결되도록 합니다. Claude Code는 코드를 대화창에 로드하는 대신 스크립트를 직접 실행합니다.
Claude Code 스킬은 다른 AI 도구에서도 작동하나요?