Configuration and multi-file skills

Configuration and multi-file skills · 4 min

이 영상에서는 스킬을 더욱 강력하게 만드는 고급 기법들을 다룹니다: 전체 메타데이터 필드 세트, 안정적으로 트리거되는 설명을 작성하는 방법, 보안에 민감한 워크플로를 위한 도구 접근 제한, 그리고 점진적 공개를 사용하여 여러 파일에 걸쳐 더 큰 스킬을 구성하는 방법입니다. 복잡한 사용 사례를 지원하면서도 스킬을 효율적으로 유지하는 방법을 배우게 됩니다.

한국어 대본

00:00기본 Skill은 이름과 설명만으로도 작동하지만, 여기에 몇 가지 고급
00:07팁을 추가하면 Cloud Code에서 Skill을 훨씬 효과적으로 만들 수 있습니다.
00:12agentskills.io 오픈 표준에는 사용 가능한 필드가 많이 있습니다.
00:17이름에 대해서는 이미 살펴봤습니다. 이름은 Skill을 식별하며, 소문자, 숫자
00:22및 하이픈만 사용합니다. 최대 64자이며, 디렉터리 이름과 일치해야 합니다. 설명도
00:28필수이며, Claude가 Skill을 사용해야 하는 시기를 알려줍니다. 이 설명은 최대 1024자입니다.
00:34그리고 가장 중요한 필드입니다. Claude는 이 설명을 매칭에 사용하지만, 다른 선택적
00:38필드도 추가할 수 있습니다. 그중 하나는 허용 도구 필드로, Claude가 사용할 수 있는 도구를 제한합니다
00:44Skill이 활성화되면. 모델 필드는 Skill에 사용할 Claude 모델을 지정합니다.
00:49지침을 명확하게 하세요. 예를 들어, 누군가 제 작업이 문서 작성을 돕는 것이라고 말했다면
00:55무엇을 해야 할지 모를 것입니다. 따라서 Claude도 같은 방식으로 생각할 것이라고 가정해야 합니다.
01:02좋은 설명은 두 가지 질문에 답합니다. 이 Skill은 무엇을 합니까? 그리고 Claude는 언제 사용해야 합니까?
01:08이제 이 작업 설명이 나에게 주어지면, 나는 조금 더 확신을 느낍니다
01:12작업을 끝낼 수 있을 것이라는. Skill이 트리거되지 않는 경우,
01:15요청을 표현하는 방식과 일치하는 키워드를 더 추가하세요.
01:18목록.
01:21때로는 파일을 읽기만 하고 수정하지 않는 Skill이 필요할 수 있습니다.
01:25이는 보안에 민감한 워크플로, 읽기 전용 작업 등에 사용될 수 있습니다.
01:31이를 가능하게 하는 허용 도구 필드가 있습니다.
01:34이 Skill이 활성화되면 Claude는 권한을 묻지 않고 해당 도구만 사용할 수 있습니다.
01:38편집도, 쓰기도, bash 명령도 없습니다.
01:41허용 도구를 생략하면 Skill은 아무것도 제한하지 않습니다.
01:45Claude는 일반 권한 모델을 사용합니다.
01:48Skill은 Claude의 컨텍스트 창을 대화와 공유합니다.
01:53Claude가 Skill을 사용하려고 할 때, 해당 Skill의 내용을 로드하기로 결정합니다.
01:57컨텍스트에 포함됩니다.
01:58하지만 때로는 스킬에 필요한 참고 자료, 예시, 또는 유틸리티 스크립트가 필요할 수 있습니다.
02:04하지만 이 모든 것을 2000줄짜리 텍스트 파일 하나에 욱여넣으면
02:10컨텍스트 창에서 많은 공간을 차지하게 됩니다.
02:13그리고 솔직히 말해서, 그것을 유지 관리하는 것은 별로 재미있는 일이 아닙니다.
02:16여기서 점진적 공개가 등장합니다.
02:19핵심 지침은 skill.md에 넣고, 자세한 참고 자료는 Claude가 필요할 때만 읽는 별도의
02:23파일에 넣으세요.
02:26오픈 표준은 또한 실행 코드를 위한 scripts 폴더, 추가 문서를 위한 references,
02:31그리고 해당 스킬과 관련된 이미지, 템플릿, 또는 기타 데이터 파일을 위한 assets 폴더를
02:37두는 것을 권장합니다.
02:40그런 다음 skill.md에서 지원 파일에 링크를 거세요.
02:43여기서 Claude는 누군가 시스템 설계에 대해 물어볼 때만 architecture.md를 읽습니다.
02:48가령 구성 요소를 어디에 추가할지 묻는다면, 그 파일은 아예 로드되지 않습니다.
02:53마치 컨텍스트 창에 문서 전체를 통째로 넣는 대신
02:57목차를 두는 것과 같습니다.
02:59skill.md는 500줄 미만으로 유지하세요.
03:01그 줄 수를 초과한다면, 내용을 여러 개로 나눠야 할지 고려해 보세요.
03:08스킬 디렉터리의 스크립트는 내용을 컨텍스트에 로드하지 않고도 실행할 수 있습니다.
03:13스크립트가 실행되고 출력만 토큰을 소비합니다.
03:16Claude에게 스크립트를 읽지 말고 실행하라고 하세요.
03:18이는 환경 검증,
03:22일관성이 필요한 데이터 변환,
03:24그리고 생성된 코드보다 테스트된 코드로 수행할 때 더 신뢰할 수 있는 작업에 매우 유용합니다.
03:30Skills는 메타데이터 필드를 지원합니다.
03:33이름과 설명은 필수입니다.
03:35허용 도구는 사용 가능한 도구를 제한합니다.
03:37모델은 사용할 Claude를 지정합니다.
03:40설명에는 안정적인 매칭을 위해 특정 작업과 트리거 문구가 필요합니다.
03:45더 큰 Skills의 경우 점진적 공개를 사용하세요.
03:47skill.md 파일을 500줄 미만으로 유지하고 필요할 때만 로드되는 지원 파일에 연결하세요.
03:53스크립트는 내용을 로드하지 않고도 실행할 수 있어 컨텍스트를 효율적으로 유지합니다.

Watch on YouTube

Key takeaways

name과 description은 필수입니다 — allowed-tools와 model은 선택 사항이지만 강력한 추가 기능입니다
좋은 설명은 두 가지 질문에 답합니다: 스킬이 무엇을 하는가? Claude가 언제 이를 사용해야 하는가?
**allowed-tools**는 스킬이 활성화되었을 때 Claude가 사용할 수 있는 도구를 제한합니다 — 읽기 전용 또는 보안에 민감한 워크플로에 유용합니다
점진적 공개: SKILL.md를 500줄 이하로 유지하고, Claude가 필요할 때만 읽는 지원 파일(참조, 스크립트, 자산)에 링크하세요
스크립트는 내용을 컨텍스트에 로드하지 않고 실행됩니다 — 출력만 토큰을 소비하므로 컨텍스트가 효율적으로 유지됩니다

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

Skill Metadata Fields

agent skills 개방형 표준은 SKILL.md 프런트매터에서 여러 필드를 지원합니다. 두 개는 필수이며, 나머지는 선택 사항입니다:

name (필수) — 스킬을 식별합니다. 소문자, 숫자, 하이픈만 사용하세요. 최대 64자입니다. 디렉터리 이름과 일치해야 합니다.
description (필수) — Claude에게 스킬을 언제 사용해야 하는지 알려줍니다. 최대 1,024자입니다. Claude가 매칭에 사용하는 가장 중요한 필드입니다.
allowed-tools (선택) — 스킬이 활성화되었을 때 Claude가 사용할 수 있는 도구를 제한합니다.
model (선택) — 스킬에 사용할 Claude 모델을 지정합니다.

Writing Effective Descriptions

지시사항을 명확하게 작성하세요. 누군가 "당신의 일은 문서 작업을 돕는 것입니다"라고 말했다면 무엇을 해야 할지 알 수 없을 것입니다 — Claude도 같은 방식으로 생각합니다.

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

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

스킬이 예상한 대로 트리거되지 않는다면, 실제로 요청을 표현하는 방식과 일치하는 키워드를 더 추가해 보세요. 설명은 Claude가 스킬의 관련성을 판단하는 데 사용하는 것이므로 언어가 중요합니다.

Restricting Tools with allowed-tools

때로는 파일을 읽기만 하고 수정할 수 없는 스킬을 원할 수 있습니다. 이는 보안에 민감한 워크플로, 읽기 전용 작업, 또는 가드레일이 필요한 모든 상황에 유용합니다.

이 예시에서 allowed-tools 필드는 Read, Grep, Glob, Bash로 설정되어 있습니다. 이 스킬이 활성화되면 Claude는 권한을 요청하지 않고 해당 도구만 사용할 수 있습니다 — 편집도, 쓰기도 할 수 없습니다.

yaml

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

allowed-tools를 완전히 생략하면 스킬은 아무것도 제한하지 않습니다. Claude는 일반적인 권한 모델을 사용합니다.

Progressive Disclosure

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

모든 것을 2,000줄짜리 파일 하나에 몰아넣으면 두 가지 문제가 생깁니다: 컨텍스트 윈도우 공간을 많이 차지하고, 유지 관리하기가 즐겁지 않습니다.

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

개방형 표준은 스킬 디렉터리를 다음과 같이 구성할 것을 제안합니다:

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

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

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

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

Using Scripts Efficiently

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

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

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

Lesson reflection

여러 파일이 포함된 스킬을 구축하고 싶다고 생각해 보세요. SKILL.md와 지원 참조 파일을 어떻게 구조화하시겠습니까?
팀 내 워크플로 중 allowed-tools로 도구 접근을 제한하는 것이 중요한 안전 계층을 추가할 수 있는 경우가 있습니까?

What's next

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