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

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

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

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

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

🔑 클로드 코드 스킬의 정의

클로드 코드 스킬은 SKILL.md와 보조 파일을 담은 폴더로, 평소에는 설명만 컨텍스트에 두고 필요할 때 본문을 불러와 반복 절차를 수행하게 하는 확장 기능입니다.

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

📁 폴더 구조와 두는 위치

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

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

같은 이름이 겹치면 조직 관리, 개인, 프로젝트 순서로 앞선 것이 쓰입니다. 개인 스킬은 클라우드 세션과 루틴(예약 작업)에서는 읽히지 않으므로, 클라우드에서도 써야 하는 스킬은 프로젝트에 둡니다. 세션 중에 SKILL.md를 고치면 다시 시작하지 않아도 반영됩니다.

🏷️ frontmatter에 적는 필드

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

클로드 코드는 20개 필드를 읽는데, 실무에서 자주 쓰는 것은 아래 정도입니다.

클로드 코드에서는 모든 필드가 선택이고 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에 같은 경로 문자열을 쓰면 그 스크립트는 승인 창 없이 실행됩니다. allowed-tools는 도구를 제한하는 기능이 아니라 그 턴에 허락을 미리 주는 기능이라는 점도 알아 둡니다. 저장소에 올린 스킬의 allowed-tools는 작업 공간을 신뢰했는지와 상관없이 적용되므로, 남이 만든 저장소를 받았다면 스킬의 이 필드부터 확인합니다.

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

효과를 확인하는 방법으로 공식 문서는 실제 요청 몇 개를 새 세션에서 스킬을 켠 상태와 끈 상태로 나란히 돌려 비교하라고 안내합니다.

⚠️ 자주 하는 실수

• 부작용 있는 스킬을 자동 호출에 열어 둡니다: 배포, 커밋, 메시지 발송 스킬은 disable-model-invocation: true로 사람만 부르게 합니다
• 한 스킬에 여러 일을 담습니다: 설명이 넓어져 엉뚱한 요청에 불립니다. 한 스킬은 한 가지 작업만 맡깁니다
• CLAUDE.md에 있는 규칙을 스킬 본문에 또 적습니다: 같은 내용이 두 번 컨텍스트에 들어갑니다
• 개인 스킬을 클라우드 세션에서 찾습니다: 개인 스킬은 클라우드 세션과 루틴에서 읽히지 않습니다

❓ 자주 묻는 질문

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

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

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

올릴 수 있지만 공개 표준의 여섯 필드만 받습니다. disable-model-invocation이나 context 같은 클로드 코드 전용 필드가 있으면 업로드에서 오류가 나므로, 함께 쓸 스킬은 여섯 필드 안에서 만듭니다.

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

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

📋 3줄 요약

1. 클로드 코드 스킬은 SKILL.md가 든 폴더이고, 평소에는 description만 컨텍스트에 두다가 사람이 /이름으로 부르거나 클로드가 관련 있다고 판단할 때 본문을 불러옵니다.

2. description과 when_to_use를 합친 설명은 목록에서 1,536자에서 잘리므로 핵심 용도를 앞에 두고, SKILL.md 본문은 500줄 미만으로 유지합니다.

3. 배포나 커밋처럼 부작용이 있는 스킬은 disable-model-invocation: true로 사람만 부르게 하고, 번들 스크립트 경로는 ${CLAUDE_SKILL_DIR}로 적습니다.

📚 참고 자료

• 클로드 코드 스킬 문서: 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