실제로 작동하는 Claude Code Skill 구축 방법 (완벽 가이드)

Claude를 일주일 동안 사용해보면 똑같은 내용을 계속 입력하게 된다. 코드를 커밋할 때마다 커밋 형식에 대한 세 가지 규칙을 붙여넣고, 문서를 작성할 때마다 스타일을 다시 설명한다. Claude는 잘 수행하지만 채팅이 끝나면 잊어버리고, 다음 날 또 똑같이 입력해야 한다.

스킬(Skill)이 이 문제를 해결한다. 한 번만 작성하면 Claude가 워크플로우를 영구적으로 학습하여 매 세션마다 별도의 요청 없이 적용하는 작은 폴더다.

작동 방식은 간단하다. 스킬은 하나의 파일이 들어 있는 폴더다. Claude는 그 스킬에 대한 한 줄 요약을 항상 표시하고, 요청이 일치할 때만 전체 지침을 불러온다. 이것이 전부다.

이 가이드에서는 실제 스킬 하나를 처음부터 만든다: commit-messages는 Git 커밋을 정확한 형식으로 작성하는 스킬이다. Claude가 설치되어 있고 다른 것은 없다면, 모든 단계를 따라 할 수 있다.

최종 결과물

핵심은 하나의 폴더와 하나의 필수 파일 SKILL.md다. 스킬이 성장함에 따라 세 가지 선택적 폴더가 추가된다:

1your-skill-name/
2├── SKILL.md          # 필수 - 메인 스킬 파일
3├── scripts/          # 선택 - 실행 가능한 코드
4├── references/       # 선택 - 문서
5└── assets/           # 선택 - 템플릿 등

SKILL.md 자체는 두 부분으로 구성된다: Claude에게 언제 스킬을 사용할지 알려주는 짧은 헤더와, 무엇을 해야 하는지 알려주는 아래의 지침이다. 이 분할이 중요한 이유는 Claude가 헤더를 지속적으로 읽어 스킬의 존재를 항상 인지하지만, 요청이 일치할 때만 지침을 로드하기 때문이다. 이 차이를 명심하라. 이 가이드의 거의 모든 내용이 이 원칙에서 비롯된다.

생성하기

스킬은 홈 디렉토리 안의 .claude/skills 폴더에 위치하며, Claude Code와 데스크톱 앱 모두 이 폴더를 읽는다. 숨김 폴더이며 아직 존재하지 않을 가능성이 높으므로, 스킬 폴더와 함께 생성하는 가장 빠른 방법은 단일 명령어다.

Mac에서는 터미널을 열고 실행:

1mkdir -p ~/.claude/skills/your-skill-name

Windows에서는 PowerShell을 열고 실행:

1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"

폴더 이름은 단순한 장식이 아니다. Claude는 이를 스킬의 식별자로 사용하며, 다음 형식 규칙을 따르지 않으면 문제가 발생한다:

• 케밥-케이스(kebab-case) 사용: notion-project-setup ✔
• 공백 없음: Notion Project Setup ✖
• 밑줄 없음: notion_project_setup ✖
• 대문자 없음: NotionProjectSetup ✖

해당 폴더 안에 SKILL.md라는 이름의 파일을 생성하고 텍스트 편집기로 연다. 여기부터는 모두 이 파일에 들어갈 내용이다.

작성하기 전에 설계하라

잘 작동하는 스킬은 파일을 작성하기 전에 두 가지 결정을 내린다. 둘 다 건너뛰고 싶지만, 그럴 수 없다.

첫째, 스킬이 정확히 언제 실행되어야 하는지 결정한다. 사용자가 실제로 입력할 법한 두세 가지 상황을 적어보라:

• "이 변경사항을 커밋해줘"
• "이 diff에 대한 커밋 메시지를 작성해줘"
• "스테이징하고 커밋해줘"

이것은 단순한 작업이 아니다. 이 구문들은 나중에 설명과 테스트를 위한 원자재가 되며, 이 과정 없이 설계된 스킬은 정확히 트리거되지 않는 모호한 상태가 되기 쉽다.

둘째, 어떻게 작동하는지 확인할 방법을 결정한다. 가장 중요한 기준은 스킬이 이름을 지정하지 않아도 자동으로 로드되는지 여부다. 매번 수동으로 호출해야 한다면 스킬은 기술적으로 실행되지만 실제 작업에는 실패한 것이다. 함께 확인해야 할 사항: 중간에 수정하지 않고 작업을 완료하는지, 여러 세션에서 동일한 형태의 결과를 제공하는지.

설명이 성패를 가른다

파일의 모든 요소 중에서 헤더의 설명이 가장 중요하다. Claude가 스킬을 로드할지 여부를 결정할 때 읽는 유일한 부분이기 때문이다. 지침이 완벽하더라도 설명이 일치하지 않으면 Claude는 지침에 도달하지 못한다. "작동하지 않는" 대부분의 스킬이 여기서 실패한다.

강력한 설명은 한 문장에 두 가지 질문에 답한다: 스킬이 무엇을 하는지, Claude가 언제 그것을 사용해야 하는지. 두 번째 부분이 사람들이 빠뜨리는 부분이다.

차이점은 다음과 같다:

1# 약함 - 무엇인지만 말하고, 요청과 매칭할 대상을 제공하지 않음
2description: git 커밋을 도와줍니다.
3
4# 강함 - 실행되어야 할 순간을 구체적으로 명시
5description: Conventional Commits 형식으로 git 커밋 메시지를 작성합니다. 사용자가 변경사항을 커밋하라고 요청하거나, 커밋 메시지를 작성하거나, 파일을 스테이징하고 커밋할 때 사용하세요.

약한 버전은 Claude에게 스킬이 존재한다는 것을 알리지만, 사용자가 말할 법한 어떤 것과도 연결되지 않는다. 강한 버전은 실제 구문을 명시하므로, "이 변경사항을 커밋해줘"라고 입력하면 Claude가 매칭할 대상을 가지게 된다. 사용자가 실제로 사용할 단어를 명시하고, 전체를 1024자 미만으로 유지하며, 내부에 < 또는 >를 넣지 마라.

스킬이 트리거되지 않을 때, 거의 항상 여기서 해결된다. 실제로 사용하는 표현을 추가하라. "작업 저장해줘"라고 말하지만 설명에 "커밋"만 언급되어 있다면, Claude는 둘을 연결할 방법이 없다. 반대로 스킬이 실행되어서는 안 될 때 실행된다면, 설명을 좁히거나 부정 트리거를 추가하라:

1description: Conventional Commits 형식으로 git 커밋 메시지를 작성합니다. 변경사항을 커밋할 때 사용하세요. 코드 주석이나 문서 작성에는 사용하지 마세요.

의존하기 전에 빠르게 확인하는 방법이 있다. Claude에게 직접 물어보라:

"commit-messages 스킬을 언제 사용하시겠습니까?"

Claude가 당신의 설명을 자신의 말로 읽어줄 것이다. 그것이 실제로 스킬이 실행되길 원하는 시점과 일치하지 않는다면, 문제를 찾은 것이다. 그리고 그 문제는 아래의 지침이 아니라 설명에 있다.

Claude가 실제로 따르는 지침 작성하기

헤더 아래에는 일반 Markdown 형식의 본문이 온다. 여기에 실제 워크플로우가 위치하며, Claude가 따르는 지침과 무시하는 지침을 구분하는 두 가지 습관이 있다.

첫 번째는 구체성이다. Claude는 구체적인 지침에 반응하고 모호한 지침은 대충 넘어간다. 따라서 더 정확할수록 더 안정적으로 작동한다:

1# 나쁨
2최종 확정 전에 커밋을 검증하세요.
3
4# 좋음
5`python scripts/validate.py "<message>"`를 실행하세요.
6실패하면 다음 항목을 수정하세요:
7- 잘못된 타입: feat, fix, docs, refactor, test, chore 사용
8- 요약이 60자를 초과: 줄이세요

두 번째는 순서다. Claude는 먼저 읽은 내용에 더 큰 가중치를 둔다. 따라서 긴 파일의 맨 아래에 묻힌 규칙은 놓치기 쉽다. 절대 깨지면 안 되는 규칙은 맨 위에, 그것을 알리는 제목과 함께 배치하라:

1## 중요
2- 요약 줄은 항상 60자 미만
3- 현재형만 사용: "added"가 아닌 "add"

언어가 보장할 수 있는 한계도 있다. 지침은 해석되므로, Claude가 매번 동일하게 따르지는 않는다. 실제로 모든 실행에서 반드시 통과해야 하는 검사가 있다면, 산문으로 설명하지 말고 스크립트로 옮겨 지침이 실행하도록 하라. 코드는 매번 동일하게 작동하지만, 문장은 그렇지 않다. (이것이 다음에 다룰 scripts/ 폴더의 용도다.)

대부분의 스킬에서 유지되는 구조는 다음과 같다:

1# 스킬 이름
2
3## 중요
4놓쳐서는 안 되는 중요한 규칙
5
6## 지침
7단계별로, 구체적이고 실행 가능하게
8
9## 예시
10구체적인 입력과 출력. Claude는 규칙을 따르는 것보다 예시를 더 안정적으로 복사합니다.

파일을 간결하게 유지하라. 핵심 지침을 넘어서기 시작하면 추가 세부사항을 밖으로 옮길 때이며, 이것이 바로 선택적 폴더의 목적이다.

스크립트, 참조, 자산

지금까지의 모든 내용은 Claude에게 지침을 제공하는 스킬을 생성한다. 세 가지 선택적 폴더는 Claude에게 도구를 제공하는 스킬로 바꾸며, 이것이 일반 프롬프트로는 할 수 없는 일을 스킬이 수행하는 이유다.

scripts/는 Claude가 실행하는 코드를 보관한다. 정확해야 하는 모든 것에 사용된다. Claude가 커밋 형식이 올바른지 눈으로 확인하도록 신뢰하는 대신, 확인하는 스크립트를 제공한다:

1# scripts/validate.py
2import sys
3msg = sys.argv[1]
4types = ("feat", "fix", "docs", "refactor", "test", "chore")
5
6if msg.split(":")[0] not in types:
7    print(f"잘못된 타입입니다. 다음 중 하나를 사용하세요: {', '.join(types)}")
8elif len(msg.split("\n")[0]) > 60:
9    print("요약이 너무 깁니다 (60자 초과)")
10else:
11    print("OK")

그런 다음 SKILL.md에서 Claude에게 사용하도록 지시한다:

1최종 확정 전에 `python scripts/validate.py "<message>"`를 실행하고
2플래그가 지정된 항목을 수정하세요.

이제 형식 규칙은 매번 동일하게 실행되는 코드에 의해 강제되며, Claude가 확인하는 것을 기억하는 데 의존하지 않는다.

references/는 필요할 때만 로드되는 문서를 보관한다. 커밋 규칙이 스코프, 푸터, 예외 케이스로 두 페이지에 달한다고 가정해보자. 이 모든 것을 SKILL.md에 넣으면 한 줄짜리 커밋에도 매번 로드된다. 대신 참조 파일로 옮기라:

1your-skill-name/
2├── SKILL.md
3└── references/
4    └── conventions.md

그리고 메인 파일에서 가리킨다:

1전체 규칙 목록은 references/conventions.md를 참조하세요.

Claude는 작업이 필요할 때만 해당 파일을 연다. 이것이 스킬을 저렴하게 실행할 수 있는 이유다: 무거운 세부 사항은 실제로 관련이 있을 때까지 디스크에 머물며, 매번 컨텍스트에 실려 다니지 않는다.

assets/는 스킬이 출력에 사용하는 파일(템플릿, 설정 파일, 로고 등)을 보관한다. 커밋 스킬에는 필요하지 않지만, 보고서를 생성하는 스킬은 여기에 template.md를 보관하고 매번 채워서 모든 보고서가 동일한 구조로 나오게 할 수 있다.

이 세 폴더를 함께 사용하면, Claude에게 작업 방식을 알려주는 스킬과 작업을 당신의 방식으로 수행할 정확한 도구를 제공하는 스킬 사이의 차이가 만들어진다.

기억해야 할 한 가지

스킬은 Claude에게 새로운 능력을 가르치는 것이 아니다. 이미 커밋을 작성하는 방법을 알고 있다. 스킬이 하는 일은 매번, 다시 설명할 필요 없이 당신의 방식으로 작업을 수행하게 만드는 것이다.

그리고 스킬이 작동하지 않을 때, 원인은 거의 항상 당신이 공들여 작성한 지침이 아니다. 설명이다. Claude는 스킬을 로드할지 여부를 그 한 줄로 결정하며, 그 아래의 작업을 읽기 전에 결정한다. 설명을 올바르게 작성하면 아래의 모든 것이 마침내 사용된다.

이 글이 유용했다면, 제 프로필로 이동하여 팔로우해 주세요. 기술, AI, 실제로 작동하는 시스템에 대한 글을 씁니다.

Ciao,

@undefinedKi