Ai 마법서

Anthropic Courses 2

11 min read

tags:

구성 및 다중 파일 스킬

학습 내용

예상 소요 시간: 20분

이 단원을 마치면 다음을 수행할 수 있습니다.

  • allowed-tools 및 model을 포함한 고급 스킬 메타데이터 필드 구성하기
  • 올바른 요청에 신뢰할 수 있게 트리거되는 효과적인 스킬 설명 작성하기
  • allowed-tools를 사용하여 스킬이 활성화되었을 때 Claude가 수행할 수 있는 작업을 제한하기
  • 점진적 공개 및 다중 파일 구조를 사용하여 복잡한 스킬 구성하기

구성 및 다중 파일 스킬

(4분)

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

핵심 요약

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

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

스킬 메타데이터 필드

에이전트 스킬 오픈 표준은 SKILL.md 프론트매터에서 여러 필드를 지원합니다. 두 가지는 필수이며 나머지는 선택 사항입니다.

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

효과적인 설명 작성

지침을 명확하게 설명하십시오. 누군가가 당신에게 “당신의 임무는 문서 작성을 돕는 것입니다”라고 말했다면 무엇을 해야 할지 모를 것입니다 — Claude도 마찬가지로 생각합니다.

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

  1. 스킬은 무엇을 합니까?
  2. Claude는 언제 사용해야 합니까?

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

allowed-tools를 사용한 도구 제한

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

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

---
name: codebase-onboarding
description: 새로운 개발자가 시스템 작동 방식을 이해하도록 돕습니다.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

allowed-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 Code를 사용자 정의하는 다른 방법들 — CLAUDE.md, 하위 에이전트, 훅 및 MCP 서버 —을 비교하여 각 상황에 맞는 올바른 도구를 선택할 수 있도록 하겠습니다.

피드백

코스를 진행하면서 스킬을 업무에 어떻게 사용하고 있는지, 그리고 가지고 계신 피드백을 듣고 싶습니다. 여기에서 피드백을 공유해 주세요.

Graph View