구성과 다중 파일 스킬

구성과 다중 파일 스킬

핵심 요약

• Claude Code에서는 모든 frontmatter 필드가 선택 사항이며, description만 권장됩니다. allowed-tools와 model은 가장 유용한 추가 필드 중 두 가지입니다
• 좋은 설명은 두 가지 질문에 답합니다: 스킬이 무엇을 하는가? Claude가 언제 이를 사용해야 하는가?
• allowed-tools는 스킬이 활성화되어 있는 동안 나열된 도구를 사전 승인하여 Claude가 묻지 않고 사용할 수 있게 하며, Claude를 해당 도구로 제한하지는 않습니다
• 점진적 공개: SKILL.md를 500줄 이내로 유지하고, Claude가 필요할 때만 읽는 지원 파일(참조 자료, 스크립트, 자산)을 링크하세요
• 스크립트는 내용을 컨텍스트에 로드하지 않고도 실행됩니다 — 출력만 토큰을 소비하므로 컨텍스트가 효율적으로 유지됩니다

기본 스킬은 이름과 설명만으로도 작동하지만, Claude Code에서 스킬을 훨씬 더 효과적으로 만들어주는 여러 고급 기법이 있습니다. 핵심 필드, 설명 작성 모범 사례, 도구 권한, 그리고 더 큰 스킬을 구조화하는 방법을 살펴보겠습니다.

스킬 메타데이터 필드

에이전트 스킬 오픈 표준은 SKILL.md frontmatter의 핵심 필드를 정의하며, Claude Code는 model과 같은 여러 자체 필드를 추가합니다. Claude Code에서는 모든 필드가 선택 사항이며 description만 권장됩니다. 다음 네 가지부터 시작하면 좋습니다 (나머지는 frontmatter 참조를 확인하세요):

• name (선택 사항) — 스킬을 식별합니다. 기본값은 디렉터리 이름입니다. 스킬을 Claude.ai나 Claude API에 업로드하는 경우 필수이며, 소문자, 숫자, 하이픈만 사용해 최대 64자까지 허용됩니다.
• description (권장) — Claude에게 스킬을 언제 사용할지 알려줍니다. 스킬을 Claude.ai나 Claude API에 업로드하는 경우 필수이며 최대 1,024자로 제한됩니다. Claude가 매칭에 이 필드를 사용하기 때문에 가장 중요한 필드입니다.
• allowed-tools (선택 사항) — 나열된 도구를 사전 승인하여, 스킬이 활성화되어 있는 동안 Claude가 권한을 묻지 않고 사용할 수 있게 합니다.
• model (선택 사항) — 스킬에 사용할 Claude 모델을 지정합니다.

효과적인 설명 작성하기

지시사항은 명확하게 작성하세요. 누군가 여러분에게 "당신의 업무는 문서 작업을 돕는 것입니다"라고만 말한다면 무엇을 해야 할지 알 수 없을 것입니다 — Claude도 똑같이 생각합니다.

좋은 설명은 두 가지 질문에 답합니다:

1. 스킬이 무엇을 하는가?
2. Claude가 언제 이를 사용해야 하는가?

스킬이 예상한 대로 트리거되지 않는다면, 실제로 요청할 때 사용하는 표현과 더 잘 맞는 키워드를 추가해 보세요. 설명은 Claude가 스킬이 관련이 있는지 판단하는 데 사용하는 요소이므로, 표현 방식이 중요합니다.

allowed-tools로 도구 사전 승인하기

때로는 스킬이 실행될 때마다 동일한 몇 가지 도구에 의존하는데, 매번 호출을 수동으로 승인하고 싶지 않을 수 있습니다. allowed-tools 필드는 나열한 도구를 사전 승인하여, 스킬을 호출한 턴이 끝날 때까지 Claude가 권한 프롬프트 없이 사용할 수 있게 합니다. 다음 메시지를 보내면 이 승인은 사라집니다.



이 예시에서 allowed-tools 필드는 Read, Grep, Glob, Bash로 설정되어 있습니다. 이 스킬이 활성화되어 있는 동안 Claude는 이 네 가지 도구를 권한 확인 없이 사용할 수 있습니다. 다른 것에 대한 접근 권한을 잃지는 않습니다: 스킬의 지시사항에 따라 Claude가 파일을 편집하거나 작성하게 되면, 다른 모든 도구 호출과 마찬가지로 일반적인 권한 설정을 거치게 됩니다. 한 가지 주의할 점: Bash만 단독으로 나열하면 셸 명령 전반을 사전 승인하게 되므로, 신뢰하는 스킬에만 이를 사용하거나 Bash(git status *)와 같은 패턴으로 범위를 좁히세요.

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

allowed-tools를 아예 생략하면 아무것도 사전 승인되지 않으며, Claude는 모든 도구에 대해 일반적인 권한 모델을 사용합니다. 반대로 스킬이 활성화된 동안 도구에 대한 접근을 제거하려면, 별도의 Claude Code frontmatter 필드인 disallowed-tools를 사용하세요. 이 필드는 나열한 도구를 Claude가 사용할 수 있는 집합에서 제외합니다.

점진적 공개

스킬은 Claude의 컨텍스트 창을 대화와 공유합니다. Claude가 스킬을 활성화하면 해당 SKILL.md의 내용을 컨텍스트에 로드합니다. 하지만 때로는 스킬이 의존하는 참조 자료, 예시, 또는 유틸리티 스크립트가 필요할 수 있습니다.

모든 것을 하나의 2,000줄짜리 파일에 욱여넣으면 두 가지 문제가 발생합니다: 컨텍스트 창 공간을 많이 차지하고, 유지 관리가 번거로워집니다.

점진적 공개는 이 문제를 해결합니다. 필수적인 지시사항은 SKILL.md에 담아두고, 상세한 참조 자료는 Claude가 필요할 때만 읽는 별도의 파일에 넣으세요.

오픈 표준에서는 스킬 디렉터리를 다음과 같이 구성할 것을 제안합니다:

• scripts/ — 실행 가능한 코드
• references/ — 추가 문서
• assets/ — 이미지, 템플릿, 또는 기타 데이터 파일

그런 다음 SKILL.md에서 지원 파일을 링크하고, 언제 로드해야 하는지 명확한 지시사항을 함께 작성하세요:



이 예시에서 Claude는 누군가 시스템 설계에 대해 물어볼 때만 architecture-guide.md를 읽습니다. 컴포넌트를 어디에 추가할지 묻는 경우에는 이 파일을 전혀 로드하지 않습니다. 이는 컨텍스트 창에 전체 문서 대신 목차를 두는 것과 같습니다.

좋은 경험칙: SKILL.md를 500줄 이내로 유지하세요. 이를 초과한다면 내용을 별도의 참조 파일로 분리해야 하는지 고려해 보세요.

스크립트를 효율적으로 사용하기

스킬 디렉터리 안의 스크립트는 내용을 컨텍스트에 로드하지 않고도 실행할 수 있습니다. 스크립트가 실행되고 출력만 토큰을 소비합니다. SKILL.md에 포함할 핵심 지시사항은 스크립트를 읽으라가 아니라 실행하라고 Claude에게 알려주는 것입니다.

이는 특히 다음과 같은 경우에 유용합니다:

• 환경 검증
• 일관성이 필요한 데이터 변환
• 생성된 코드보다 테스트된 코드로 처리하는 것이 더 신뢰할 수 있는 작업

레슨 돌아보기

• 여러 파일을 포함하는, 만들고 싶은 스킬을 하나 떠올려 보세요. SKILL.md와 지원 참조 파일을 어떻게 구조화하시겠습니까?
• 팀이 공유하는 스킬의 경우, 어떤 도구를 allowed-tools로 사전 승인하고, 어떤 도구는 Claude가 계속 물어보길 원하시나요?

다음 단계

다음 레슨에서는 스킬을 Claude Code를 커스터마이즈할 수 있는 다른 방법들 — CLAUDE.md, 서브에이전트, 훅, MCP 서버 — 과 비교하여, 각 상황에 맞는 올바른 도구를 선택할 수 있도록 해보겠습니다.