클로드 코드 스킬 만들기 (SKILL.md 구조와 트리거)

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Skills 문서와 platform.claude.com의 스킬 작성 가이드를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 필드 이름과 버전은 2026년 10월 3일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 같은 요청 문장을 매번 붙여 넣고 있을 때

블로그 글을 검수할 때마다 "문체 규칙 문서를 읽고, 검사 스크립트를 돌리고, 결과를 표로 정리해 줘"라는 긴 문장을 대화창에 붙여 넣고 있다면 스킬로 만들 때가 된 것입니다. CLAUDE.md에 넣자니 매 세션 컨텍스트를 차지하고, 넣지 않자니 매번 같은 설명을 반복하게 됩니다.

스킬이 무엇인지와 claude.ai에서 쓰는 법은 클로드 스킬 알아보기에 있습니다. 지금부터는 클로드 코드에서 스킬을 직접 만드는 법, 즉 폴더 구조와 frontmatter 필드, 설명을 어떻게 써야 제때 불리는지, 불리지 않을 때 무엇을 확인하는지를 정리합니다.

🔑 클로드 코드 스킬의 정의

클로드 코드 스킬은 반복할 작업의 설명과 절차를 SKILL.md에 모아 필요할 때 불러오는 기능입니다. 먼저 작은 작업을 직접 호출해 결과를 확인한 뒤 자동 호출 조건을 다듬습니다.

처음에는 SKILL.md 한 파일로 시작해도 됩니다. 외부 발송이나 파일 수정 없이 짧은 메모를 정리하는 스킬부터 연습합니다.

부르는 방법은 두 가지입니다. 사람이 /스킬이름을 입력하거나, 클로드가 대화 내용을 보고 관련 있다고 판단해 스스로 부릅니다. 예전에 .claude/commands/에 두던 커스텀 슬래시 명령은 이제 스킬로 합쳐졌다고 공식 문서가 설명합니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy로 불리고, 기존 명령 파일도 계속 동작하지만 새로 만들 때는 보조 파일을 함께 둘 수 있는 스킬을 권합니다.

📁 폴더 구조와 두는 위치

공식 예시를 따르면 스킬 폴더는 이렇게 생겼습니다.

SKILL.md에서 보조 파일마다 무엇이 들었고 언제 읽는지 링크로 알려 줍니다. 참조는 SKILL.md에서 한 단계까지만 두라고 스킬 작성 가이드가 권합니다. 참조가 다른 참조를 부르면 클로드가 필요한 파일을 끝까지 따라가지 못할 수 있기 때문입니다.

조직 관리, 개인과 프로젝트 스킬 사이에서 같은 이름이 겹치면 이 순서로 앞선 것이 쓰입니다. 기존 명령과 겹치지 않는 이름을 골라 어떤 파일이 호출되는지 확인합니다. 내 컴퓨터의 개인 스킬 폴더는 클라우드 세션과 루틴(예약 작업)에서 읽지 않습니다. 클라우드에 제공하려면 프로젝트 저장소에 포함하거나 claude.ai 계정의 스킬로 준비합니다. 이미 감시 중인 스킬 폴더의 SKILL.md 수정은 재시작 없이 발견됩니다. 세션을 시작한 뒤 최상위 skills 폴더를 처음 만들었다면 /reload-skills가 필요할 수 있습니다. 이미 대화에 들어온 과거 본문이 자동으로 새 내용으로 교체되는 것은 아니므로 수정 후 다시 호출합니다.

🏷️ frontmatter에 적는 필드

SKILL.md 맨 위의 --- 사이에 설정을 적습니다. 가장 기본적인 모양은 다음과 같습니다.

frontmatter는 문서 맨 위에 두는 설정 부분입니다. 위 예제는 이름, 용도와 수동 호출 여부만 정합니다. $ARGUMENTS에는 스킬 이름 뒤에 입력한 메모가 들어갑니다. 더 필요할 때 아래 필드를 확인합니다.

앞의 기본 예제를 고쳤다면 저장한 뒤 다시 호출해서 바뀐 본문을 적용합니다.

클로드 코드에서는 모든 필드가 선택이고 description만 권장입니다. 다만 스킬 공개 표준(agentskills.io)과 claude.ai 업로드는 name과 description을 필수로 요구하고 name, description, license, compatibility, metadata, allowed-tools 여섯 필드만 받습니다. 다른 곳에서도 쓸 스킬이라면 이 여섯 필드 안에서 쓰는 편이 안전합니다. name은 소문자, 숫자, 하이픈만 쓰고 폴더 이름과 맞춥니다.

🎯 설명(description)이 호출을 정하는 방식

클로드는 스킬 본문을 미리 읽지 않고 이름과 설명 등 목록 정보를 보고 부를지 판단합니다. 그래서 자동 호출을 검토할 때는 설명을 먼저 확인합니다. 직접 호출된 뒤의 결과는 본문의 절차와 판단 기준도 확인해야 합니다.

• 길이 제한: description과 when_to_use를 합친 문장은 스킬 목록에서 기본 1,536자에서 잘립니다. 핵심 용도를 첫 문장에 둡니다
• 목록 예산: 스킬 목록의 기본 예산은 모델 컨텍스트 크기의 1%에 맞춰지며, 넘치면 덜 쓰는 스킬부터 설명이 빠집니다
• 쓰는 방식: 스킬 작성 가이드는 무엇을 하는지와 언제 쓰는지를 함께, 3인칭 서술로 적으라고 권합니다
• 낱말 선택: 사람이 실제로 요청할 때 쓰는 낱말(검수, 교정, 초안)을 넣어 호출 조건을 분명히 합니다. 낱말 하나를 넣었다고 항상 호출되는 것은 아닙니다

본문은 짧게 쓰는 편이 좋습니다. 공식 문서는 SKILL.md를 500줄 미만으로 유지하라고 권장합니다. 이 수치는 작동 여부를 가르는 강제 제한이 아닙니다. 또한 한 번 불린 본문은 이후 턴 내내 컨텍스트에 남아 줄마다 비용이 된다고 설명합니다. 그래서 본문은 일회성 단계 설명보다 그 스킬이 켜져 있는 동안 지킬 지침으로 씁니다.

🧷 스크립트 경로와 allowed-tools

스킬에 스크립트를 넣을 때는 경로를 ${CLAUDE_SKILL_DIR}로 적습니다. scripts/check.sh처럼 상대 경로로 적으면 작업 폴더가 스킬 폴더가 아닐 때 파일을 찾지 못합니다.

본문의 명령과 allowed-tools의 경로가 일치하면 사전 승인 규칙이 적용될 수 있습니다. 다만 조직 정책과 deny 규칙 등을 무시할 수는 없습니다. allowed-tools는 도구를 제한하는 기능이 아니라 그 턴에 허락을 미리 주는 기능이라는 점도 알아 둡니다. 저장소에 올린 스킬의 allowed-tools는 작업 공간을 신뢰했는지와 상관없이 적용되므로, 남이 만든 저장소를 받았다면 이 필드와 실행할 스크립트 내용을 확인합니다. 처음 예제에는 자동 승인 도구를 지정하지 않습니다. 문장으로 “도구를 쓰지 않는다”고 적는 것과 실제 도구 권한을 제한하는 설정도 구분합니다.

🧪 스킬이 불리지 않거나 너무 자주 불릴 때

효과는 새 세션에서 같은 입력과 같은 모델로 스킬을 쓴 경우와 안 쓴 경우를 비교합니다. 올바른 값, 빠뜨린 조건과 수정 횟수를 기록합니다. 한 번 결과가 좋아졌다고 항상 개선된다고 결론 내리지 않습니다.

본문의 스킬 점검 항목을 정리했습니다. 진단 도구의 버전별 지원 조건은 본문 참고 자료에서 확인합니다.

⚠️ 자주 하는 실수

• 부작용 있는 스킬을 자동 호출에 열어 둡니다: 배포, 커밋, 메시지 발송 스킬은 disable-model-invocation: true로 사람만 부르게 합니다
• 한 스킬에 여러 일을 담습니다: 설명이 넓어져 엉뚱한 요청에 불립니다. 한 스킬은 한 가지 작업만 맡깁니다
• CLAUDE.md에 있는 규칙을 스킬 본문에 또 적습니다: 같은 내용이 두 번 컨텍스트에 들어갑니다
• 개인 스킬을 클라우드 세션에서 찾습니다: 내 컴퓨터의 개인 폴더는 자동 복사되지 않습니다. 저장소의 스킬이나 claude.ai에서 켠 스킬이 별도 경로로 제공되는지 확인합니다

❓ 자주 묻는 질문

스킬과 서브에이전트는 언제 나눠 쓰나요?

스킬은 지금 대화 안에서 절차와 지침을 더해 주고, 서브에이전트는 별도 컨텍스트에서 일한 뒤 요약만 돌려줍니다. 스킬에 context: fork를 적으면 서브에이전트처럼 따로 실행할 수도 있습니다. 조사와 검수를 나누는 방법은 서브에이전트 실전에서 이어집니다.

클로드 코드에서 만든 스킬을 claude.ai에도 올릴 수 있나요?

올릴 수 있지만 여기서 쓰는 Claude Code 확장 필드와 호환 조건을 확인해야 합니다. claude.ai 업로드는 공개 표준의 여섯 필드만 받습니다. disable-model-invocation이나 context 같은 클로드 코드 전용 필드가 있으면 업로드에서 오류가 나므로, 함께 쓸 때는 호환되는 파일을 별도로 준비합니다. 수동 호출 제어를 위해 넣은 필드를 단순히 삭제하면 사용 방식이 달라질 수 있습니다. 본문의 Claude 전용 변수나 셸 실행 문법까지 자동 호환되는 것은 아닙니다.

스킬 여러 개를 한 번에 부를 수 있나요?

부를 수 있습니다. /write-tests /fix-issue 123처럼 한 메시지에 이어 적으면 되고, 첫 스킬을 포함해 여섯 개까지 쌓을 수 있다고 공식 문서가 적고 있습니다.

가상 메모 정리 스킬 만들고 고치기

Claude Code를 사용할 수 있다면 새 빈 폴더 skill-practice를 만듭니다. CLAUDE.md 실습의 방법으로 폴더와 터미널을 준비합니다.

1. 편집기에서 .claude/skills/practice-note-summary 폴더를 만들고 위의 SKILL.md 예제를 SKILL.md라는 이름으로 저장합니다. .txt가 뒤에 붙지 않았는지 확인합니다.
2. 프로젝트 루트 skill-practice에서 claude를 실행하고 /skills에서 practice-note-summary가 있는지 봅니다. 다른 폴더의 같은 이름이 선택되지 않았는지도 확인합니다.
3. Claude Code 입력창에 /practice-note-summary 2026년 11월 12일, 2번 회의실에서 회의를 보냅니다. 날짜는 2026년 11월 12일, 장소는 2번 회의실, 추가 확인은 시간이어야 합니다.
4. 시간이 임의로 채워졌다면 SKILL.md에 “입력에 시각이 없으면 추가 확인에는 시간이라고 적는다”를 추가합니다. 다시 스킬 이름과 같은 메모를 보내 결과를 비교합니다.
5. 이번에는 /practice-note-summary 2026년 11월 13일 오후 2시, 장소 미정을 보냅니다. 장소는 미확인이고 이미 제공한 시간을 또 묻지 않아야 합니다. 틀리면 “미정은 확정된 장소가 아니다”와 같은 판정 조건을 추가하고 재호출합니다.

메모와 결과, 고친 규칙을 나란히 남깁니다. 세 줄로 답했다는 사실만으로 성공으로 보지 말고 각 값이 원문에 있는지 확인합니다. 스킬을 찾지 못하면 폴더 위치와 이름, --- 구분선을 먼저 확인하고 필요하면 /reload-skills나 새 세션에서 다시 봅니다.

직접 호출이 안정되면 새 세션에서 자동 호출도 시험할 수 있습니다. 이 연습용 스킬에서만 disable-model-invocation: true를 제거하고 “회의 메모를 정리해 주세요: 2026년 11월 12일, 2번 회의실”과 “고양이에 관한 짧은 글을 써 주세요”를 각각 새로운 세션에서 시험합니다. 앞 요청에서는 스킬이 맞고 뒤 요청에서는 스킬이 필요하지 않습니다. 호출 기록과 결과를 함께 확인하고, 범위가 어긋나면 description을 고칩니다. 끝나면 수동 호출 설정을 다시 넣습니다.

📋 3줄 요약

1. 처음에는 SKILL.md 한 파일로 작은 작업을 만들고 직접 호출해 원문과 결과를 비교합니다.

2. description에는 할 일과 사용할 상황을 적고 호출되어야 할 요청과 호출되면 안 될 요청을 따로 시험합니다.

3. 스킬 호출 설정과 도구 권한은 별개이며 수정한 스킬은 다시 불러 실제 결과가 달라졌는지 확인합니다.

📚 참고 자료

• 클로드 코드 스킬 문서: https://code.claude.com/docs/en/skills
• 스킬 작성 가이드: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• 클로드 코드 모범 사례 문서: https://code.claude.com/docs/en/best-practices
• 스킬 공개 표준: https://agentskills.io/specification