Claude Code: 제대로 알고 쓰자(Skills편)

Agent Skills

Agent Skills는 Claude의 기능을 확장하는 모듈식 기능이다. 각 Skill은 Claude가 관련 상황에서 자동으로 사용하는 지침, 메타데이터, 선택적 리소스(스크립트, 템플릿)를 패키징한다.

---

Skills를 사용하는 이유

Skills는 Claude에게 도메인별 전문 지식(워크플로우, 컨텍스트, 베스트 프랙티스)을 제공하여 범용 에이전트를 전문가로 변환하는 재사용 가능한 파일시스템 기반 리소스이다. 일회성 작업을 위한 대화 수준의 지침인 프롬프트와 달리, Skills는 필요에 따라 로드되며 여러 대화에서 동일한 가이드를 반복적으로 제공할 필요를 없앤다.

주요 이점:

• Claude 전문화: 도메인별 작업에 맞게 기능 조정
• 반복 감소: 한 번 생성하면 자동으로 사용
• 기능 조합: Skills를 결합하여 복잡한 워크플로우 구축

Skills 사용하기

Anthropic은 일반적인 문서 작업(PowerPoint, Excel, Word, PDF)을 위한 사전 구축된 Agent Skills를 제공하며, 자체 커스텀 Skills를 생성할 수도 있다. 두 가지 모두 동일한 방식으로 작동한다. Claude는 요청과 관련이 있을 때 자동으로 사용한다.

사전 구축된 Agent Skills는 https://claude.ai 및 Claude API를 통해 모든 사용자에게 제공된다.

커스텀 Skills를 사용하면 도메인 전문 지식과 조직 지식을 패키징할 수 있다. Claude의 모든 제품에서 사용할 수 있다. Claude Code에서 생성하거나, API를 통해 업로드하거나, https://claude.ai 설정에서 추가할 수 있다.

참고

시작하기:

• 사전 구축된 Agent Skills의 경우: 빠른 시작 튜토리얼을 참고하여 API에서 PowerPoint, Excel, Word, PDF skills 사용 시작
• 커스텀 Skills의 경우: Agent Skills Cookbook을 참고하여 자체 Skills 생성 방법 학습

Skills 작동 방식

Skills는 Claude의 VM 환경을 활용하여 프롬프트만으로는 불가능한 기능을 제공한다. Claude는 파일시스템 액세스가 있는 가상 머신에서 작동하므로 Skills는 지침, 실행 가능 코드, 참고 자료가 포함된 디렉토리로 존재할 수 있으며, 새 팀원을 위해 생성하는 온보딩 가이드처럼 구성된다.

이 파일시스템 기반 아키텍처는 점진적 공개를 가능하게 한다. Claude는 미리 컨텍스트를 소비하는 것이 아니라 필요에 따라 정보를 단계적으로 로드한다.

세 가지 유형의 Skill 콘텐츠, 세 가지 로딩 레벨

Skills는 세 가지 유형의 콘텐츠를 포함할 수 있으며, 각각 다른 시점에 로드된다.

레벨 1: 메타데이터 (항상 로드됨)

콘텐츠 유형: 지침. Skill의 YAML frontmatter는 발견 정보를 제공한다.

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

Claude는 시작 시 이 메타데이터를 로드하고 시스템 프롬프트에 포함한다. 이 경량 접근 방식은 컨텍스트 패널티 없이 많은 Skills를 설치할 수 있음을 의미한다. Claude는 각 Skill이 존재한다는 것과 언제 사용할지만 알고 있다.

레벨 2: 지침 (트리거될 때 로드됨)

콘텐츠 유형: 지침. SKILL.md의 본문에는 절차적 지식(워크플로우, 베스트 프랙티스, 가이드)이 포함된다.

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

Skill의 설명과 일치하는 요청을 하면 Claude는 bash를 통해 파일시스템에서 SKILL.md를 읽는다. 그때서야 이 콘텐츠가 컨텍스트 윈도우에 들어간다.

레벨 3: 리소스 및 코드 (필요에 따라 로드됨)

콘텐츠 유형: 지침, 코드, 리소스. Skills는 추가 자료를 번들로 제공할 수 있다.

pdf-skill/
├── SKILL.md (주요 지침)
├── FORMS.md (양식 작성 가이드)
├── REFERENCE.md (상세 API 참조)
└── scripts/
    └── fill_form.py (유틸리티 스크립트)

지침: 전문화된 가이드와 워크플로우가 포함된 추가 마크다운 파일(FORMS.md, REFERENCE.md)

코드: Claude가 bash를 통해 실행하는 실행 가능 스크립트(fill_form.py, validate.py). 스크립트는 컨텍스트를 소비하지 않고 결정적 작업을 제공한다

리소스: 데이터베이스 스키마, API 문서, 템플릿, 예제와 같은 참고 자료

Claude는 참조될 때만 이러한 파일에 액세스한다. 파일시스템 모델은 각 콘텐츠 유형이 서로 다른 장점을 갖는다는 것을 의미한다. 지침은 유연한 가이드용, 코드는 신뢰성용, 리소스는 사실 조회용이다.

레벨	로드 시점	토큰 비용	콘텐츠
레벨 1: 메타데이터	항상 (시작 시)	Skill당 ~100 토큰	YAML frontmatter의 name과 description
레벨 2: 지침	Skill이 트리거될 때	5k 토큰 미만	지침과 가이드가 포함된 SKILL.md 본문
레벨 3+: 리소스	필요에 따라	사실상 무제한	콘텐츠를 컨텍스트에 로드하지 않고 bash를 통해 실행되는 번들 파일

점진적 공개는 주어진 시점에 관련 콘텐츠만 컨텍스트 윈도우를 차지하도록 보장한다.

Skills 아키텍처

Skills는 Claude가 파일시스템 액세스, bash 명령, 코드 실행 기능을 갖춘 코드 실행 환경에서 실행된다. 다음과 같이 생각할 수 있다. Skills는 가상 머신의 디렉토리로 존재하며, Claude는 컴퓨터에서 파일을 탐색하는 데 사용하는 것과 동일한 bash 명령을 사용하여 상호 작용한다.

Claude가 Skill 콘텐츠에 액세스하는 방법:

Skill이 트리거되면 Claude는 bash를 사용하여 파일시스템에서 SKILL.md를 읽어 지침을 컨텍스트 윈도우로 가져온다. 해당 지침이 다른 파일(FORMS.md 또는 데이터베이스 스키마 등)을 참조하는 경우 Claude는 추가 bash 명령을 사용하여 해당 파일도 읽는다. 지침이 실행 가능 스크립트를 언급하면 Claude는 bash를 통해 실행하고 출력만 받는다(스크립트 코드 자체는 컨텍스트에 들어가지 않음).

이 아키텍처가 가능하게 하는 것:

주문형 파일 액세스: Claude는 각 특정 작업에 필요한 파일만 읽는다. Skill에 수십 개의 참조 파일이 포함될 수 있지만 작업에 영업 스키마만 필요한 경우 Claude는 해당 파일 하나만 로드한다. 나머지는 파일시스템에 남아 토큰을 소비하지 않는다.

효율적인 스크립트 실행: Claude가 validate_form.py를 실행할 때 스크립트 코드는 컨텍스트 윈도우에 로드되지 않는다. 스크립트의 출력("검증 통과" 또는 특정 오류 메시지 등)만 토큰을 소비한다. 이는 Claude가 즉석에서 동등한 코드를 생성하는 것보다 훨씬 효율적이다.

번들 콘텐츠에 사실상 제한 없음: 파일이 액세스될 때까지 컨텍스트를 소비하지 않기 때문에 Skills는 포괄적인 API 문서, 대용량 데이터세트, 광범위한 예제 또는 필요한 모든 참고 자료를 포함할 수 있다. 사용되지 않는 번들 콘텐츠에 대한 컨텍스트 패널티가 없다.

이 파일시스템 기반 모델은 점진적 공개를 작동하게 만든다. Claude는 온보딩 가이드의 특정 섹션을 참조하는 것처럼 Skill을 탐색하여 각 작업에 필요한 것만 정확히 액세스한다.

예시: PDF 처리 skill 로딩

Claude가 PDF 처리 skill을 로드하고 사용하는 방법은 다음과 같다.

1. 시작: 시스템 프롬프트에 포함: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. 사용자 요청: "이 PDF에서 텍스트를 추출하고 요약해줘"
3. Claude 호출: bash: read pdf-skill/SKILL.md → 지침이 컨텍스트에 로드됨
4. Claude 판단: 양식 작성이 필요하지 않으므로 FORMS.md는 읽지 않음
5. Claude 실행: SKILL.md의 지침을 사용하여 작업 완료

다이어그램은 다음을 보여준다.

1. 시스템 프롬프트와 skill 메타데이터가 미리 로드된 기본 상태
2. Claude가 bash를 통해 SKILL.md를 읽어 skill을 트리거함
3. Claude가 필요에 따라 FORMS.md와 같은 추가 번들 파일을 선택적으로 읽음
4. Claude가 작업을 진행함

이 동적 로딩은 관련 skill 콘텐츠만 컨텍스트 윈도우를 차지하도록 보장한다.

Skills가 작동하는 곳

Skills는 Claude의 에이전트 제품 전반에서 사용할 수 있다.

Claude API

Claude API는 사전 구축된 Agent Skills와 커스텀 Skills를 모두 지원한다. 두 가지 모두 동일하게 작동한다. 코드 실행 도구와 함께 container 매개변수에서 관련 skill_id를 지정한다.

전제 조건: API를 통해 Skills를 사용하려면 세 가지 베타 헤더가 필요하다.

• code-execution-2025-08-25 - Skills가 코드 실행 컨테이너에서 실행됨
• skills-2025-10-02 - Skills 기능을 활성화함
• files-api-2025-04-14 - 컨테이너로/에서 파일을 업로드/다운로드하는 데 필요함

skill_id(예: pptx, xlsx)를 참조하여 사전 구축된 Agent Skills를 사용하거나, Skills API(/v1/skills 엔드포인트)를 통해 자체 Skills를 생성 및 업로드한다. 커스텀 Skills는 조직 전체에서 공유된다.

자세한 내용은 Claude API로 Skills 사용을 참고하자.

Claude Code

Claude Code는 커스텀 Skills만 지원한다.

커스텀 Skills: SKILL.md 파일이 포함된 디렉토리로 Skills를 생성한다. Claude가 자동으로 발견하고 사용한다.

Claude Code의 커스텀 Skills는 파일시스템 기반이며 API 업로드가 필요하지 않다.

자세한 내용은 Claude Code에서 Skills 사용을 참고하자.

Claude Agent SDK

Claude Agent SDK는 파일시스템 기반 구성을 통해 커스텀 Skills를 지원한다.

커스텀 Skills: .claude/skills/에 SKILL.md 파일이 포함된 디렉토리로 Skills를 생성한다. allowed_tools 구성에 "Skill"을 포함하여 Skills를 활성화한다.

그러면 SDK가 실행될 때 Agent SDK의 Skills가 자동으로 발견된다.

자세한 내용은 SDK의 Agent Skills를 참고하자.

Claude.ai

Claude.ai는 사전 구축된 Agent Skills와 커스텀 Skills를 모두 지원한다.

사전 구축된 Agent Skills: 이러한 Skills는 문서를 생성할 때 이미 백그라운드에서 작동하고 있다. Claude는 설정 없이 사용한다.

커스텀 Skills: Settings > Features를 통해 zip 파일로 자체 Skills를 업로드한다. 코드 실행이 활성화된 Pro, Max, Team, Enterprise 플랜에서 사용할 수 있다. 커스텀 Skills는 각 사용자에게 개별적이다. 조직 전체에서 공유되지 않으며 관리자가 중앙에서 관리할 수 없다.

https://claude.ai에서 Skills 사용에 대한 자세한 내용은 Claude Help Center의 다음 리소스를 참고하자.

• What are Skills?
• Using Skills in Claude
• How to create custom Skills
• Teach Claude your way of working using Skills

Skill 구조

모든 Skill은 YAML frontmatter가 포함된 SKILL.md 파일이 필요하다.

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

필수 필드: name과 description

필드 요구사항:

name:

• 최대 64자
• 소문자, 숫자, 하이픈만 포함해야 함
• XML 태그를 포함할 수 없음
• 예약어를 포함할 수 없음: "anthropic", "claude"

description:

• 비어 있지 않아야 함
• 최대 1024자
• XML 태그를 포함할 수 없음

description에는 Skill이 무엇을 하는지와 Claude가 언제 사용해야 하는지를 모두 포함해야 한다. 완전한 작성 가이드는 베스트 프랙티스 가이드를 참고하자.

보안 고려사항

신뢰할 수 있는 출처(직접 생성했거나 Anthropic에서 얻은 것)의 Skills만 사용할 것을 강력히 권장한다. Skills는 지침과 코드를 통해 Claude에게 새로운 기능을 제공하며, 이것이 강력하게 만들지만 악의적인 Skill이 Skill의 명시된 목적과 일치하지 않는 방식으로 도구를 호출하거나 코드를 실행하도록 Claude를 유도할 수 있음을 의미한다.

경고

신뢰할 수 없거나 알 수 없는 출처의 Skill을 사용해야 하는 경우 극도로 주의하고 사용하기 전에 철저히 감사한다. Claude가 Skill을 실행할 때 어떤 액세스 권한을 갖는지에 따라 악의적인 Skills는 데이터 유출, 무단 시스템 액세스 또는 기타 보안 위험을 초래할 수 있다.

주요 보안 고려사항:

• 철저한 감사: Skill에 번들로 제공되는 모든 파일(SKILL.md, 스크립트, 이미지, 기타 리소스)을 검토한다. 예상치 못한 네트워크 호출, 파일 액세스 패턴 또는 Skill의 명시된 목적과 일치하지 않는 작업과 같은 비정상적인 패턴을 찾는다
• 외부 소스는 위험함: 외부 URL에서 데이터를 가져오는 Skills는 특히 위험하다. 가져온 콘텐츠에 악의적인 지침이 포함될 수 있기 때문이다. 신뢰할 수 있는 Skills도 시간이 지남에 따라 외부 종속성이 변경되면 손상될 수 있다
• 도구 오용: 악의적인 Skills는 도구(파일 작업, bash 명령, 코드 실행)를 해로운 방식으로 호출할 수 있다
• 데이터 노출: 민감한 데이터에 액세스할 수 있는 Skills는 정보를 외부 시스템으로 유출하도록 설계될 수 있다
• 소프트웨어 설치처럼 취급: 신뢰할 수 있는 출처의 Skills만 사용한다. 민감한 데이터 또는 중요한 작업에 액세스할 수 있는 프로덕션 시스템에 Skills를 통합할 때는 특히 주의한다

사용 가능한 Skills

사전 구축된 Agent Skills

다음 사전 구축된 Agent Skills를 즉시 사용할 수 있다.

• PowerPoint (pptx): 프레젠테이션 생성, 슬라이드 편집, 프레젠테이션 콘텐츠 분석
• Excel (xlsx): 스프레드시트 생성, 데이터 분석, 차트가 포함된 보고서 생성
• Word (docx): 문서 생성, 콘텐츠 편집, 텍스트 서식 지정
• PDF (pdf): 서식이 지정된 PDF 문서 및 보고서 생성

이러한 Skills는 Claude API와 https://claude.ai에서 사용할 수 있다. API에서 사용을 시작하려면 빠른 시작 튜토리얼을 참고하자.

커스텀 Skills 예제

커스텀 Skills의 완전한 예제는 Skills cookbook을 참고하자.

제한사항 및 제약

이러한 제한사항을 이해하면 Skills 배포를 효과적으로 계획하는 데 도움이 된다.

교차 표면 가용성

커스텀 Skills는 표면 간에 동기화되지 않는다. 한 표면에 업로드된 Skills는 다른 표면에서 자동으로 사용할 수 없다.

• https://claude.ai에 업로드된 Skills는 API에 별도로 업로드해야 함
• API를 통해 업로드된 Skills는 https://claude.ai에서 사용할 수 없음
• Claude Code Skills는 파일시스템 기반이며 https://claude.ai와 API 모두와 별개임

사용하려는 각 표면에 대해 Skills를 별도로 관리하고 업로드해야 한다.

공유 범위

Skills는 사용하는 위치에 따라 다른 공유 모델을 갖는다.

• Claude.ai: 개별 사용자만. 각 팀원이 별도로 업로드해야 함
• Claude API: 워크스페이스 전체. 모든 워크스페이스 구성원이 업로드된 Skills에 액세스할 수 있음
• Claude Code: 개인용(~/.claude/skills/) 또는 프로젝트 기반(.claude/skills/). Claude Code 플러그인을 통해 공유할 수도 있음

https://claude.ai는 현재 중앙 집중식 관리자 관리 또는 조직 전체 커스텀 Skills 배포를 지원하지 않는다.

런타임 환경 제약

skill에서 사용할 수 있는 정확한 런타임 환경은 사용하는 제품 표면에 따라 다르다.

• Claude.ai:
  • 다양한 네트워크 액세스: 사용자/관리자 설정에 따라 Skills는 전체, 부분 또는 네트워크 액세스가 없을 수 있다. 자세한 내용은 Create and Edit Files 지원 문서를 참고하자.
• Claude API:
  • 네트워크 액세스 없음: Skills는 외부 API 호출을 하거나 인터넷에 액세스할 수 없음
  • 런타임 패키지 설치 없음: 사전 설치된 패키지만 사용할 수 있음. 실행 중에 새 패키지를 설치할 수 없음
  • 사전 구성된 종속성만: 사용 가능한 패키지 목록은 코드 실행 도구 문서를 확인한다
• Claude Code:
  • 전체 네트워크 액세스: Skills는 사용자 컴퓨터의 다른 프로그램과 동일한 네트워크 액세스 권한을 가짐
  • 전역 패키지 설치 권장하지 않음: Skills는 사용자 컴퓨터를 방해하지 않도록 로컬에서만 패키지를 설치해야 함

이러한 제약 내에서 작동하도록 Skills를 계획한다.

---

Skill 작성 모범 사례

효과적인 Skill을 작성하여 Claude가 성공적으로 발견하고 사용할 수 있도록 하는 방법을 알아본다.

---

좋은 Skill은 간결하고, 잘 구조화되어 있으며, 실제 사용 사례로 테스트되어 있다. 이 가이드는 Claude가 효과적으로 발견하고 사용할 수 있는 Skill을 작성하는 데 도움이 되는 실용적인 작성 방법을 제공한다.

Skill의 작동 원리에 대한 개념적 배경은 Skills 개요를 참조하자.

핵심 원칙

간결함이 핵심이다

컨텍스트 윈도우는 공공재이다. Skill은 다음을 포함하여 Claude가 알아야 할 모든 것과 컨텍스트 윈도우를 공유한다.

• 시스템 프롬프트
• 대화 기록
• 다른 Skill의 메타데이터
• 실제 요청

Skill의 모든 토큰이 즉각적인 비용을 발생시키는 것은 아니다. 시작 시점에는 모든 Skill의 메타데이터(이름과 설명)만 미리 로드된다. Claude는 Skill이 관련성이 있을 때만 SKILL.md를 읽고, 필요에 따라 추가 파일만 읽는다. 그러나 SKILL.md에서 간결함은 여전히 중요하다. Claude가 일단 로드하면 모든 토큰이 대화 기록 및 다른 컨텍스트와 경쟁하게 된다.

기본 가정: Claude는 이미 매우 똑똑하다

Claude가 아직 가지고 있지 않은 컨텍스트만 추가한다. 각 정보에 대해 질문한다.

• "Claude가 정말로 이 설명이 필요한가?"
• "Claude가 이것을 알고 있다고 가정할 수 있는가?"
• "이 단락이 토큰 비용을 정당화하는가?"

좋은 예: 간결함 (약 50 토큰):

## PDF 텍스트 추출

텍스트 추출에 pdfplumber를 사용한다.

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

나쁜 예: 너무 장황함 (약 150 토큰):

## PDF 텍스트 추출

PDF(Portable Document Format) 파일은 텍스트, 이미지 및 기타 콘텐츠를 포함하는
일반적인 파일 형식이다. PDF에서 텍스트를 추출하려면 라이브러리를 사용해야 한다.
PDF 처리를 위한 많은 라이브러리가 있지만 pdfplumber를 권장한다. 사용하기 쉽고
대부분의 경우를 잘 처리하기 때문이다. 먼저 pip를 사용하여 설치해야 한다.
그런 다음 아래 코드를 사용할 수 있다...

간결한 버전은 Claude가 PDF가 무엇이고 라이브러리가 어떻게 작동하는지 알고 있다고 가정한다.

적절한 자유도를 설정한다

구체성의 수준을 작업의 취약성과 가변성에 맞춘다.

높은 자유도 (텍스트 기반 지침):

다음과 같은 경우에 사용한다.

• 여러 접근 방식이 유효한 경우
• 결정이 컨텍스트에 따라 달라지는 경우
• 휴리스틱이 접근 방식을 안내하는 경우

예시:

## 코드 리뷰 프로세스

1. 코드 구조와 구성을 분석한다
2. 잠재적인 버그나 엣지 케이스를 확인한다
3. 가독성과 유지보수성을 위한 개선 사항을 제안한다
4. 프로젝트 규칙 준수를 확인한다

중간 자유도 (매개변수가 있는 의사 코드 또는 스크립트):

다음과 같은 경우에 사용한다.

• 선호하는 패턴이 존재하는 경우
• 어느 정도의 변형이 허용되는 경우
• 구성이 동작에 영향을 미치는 경우

예시:

## 보고서 생성

이 템플릿을 사용하고 필요에 따라 사용자 정의한다.

```python
def generate_report(data, format="markdown", include_charts=True):
    # 데이터 처리
    # 지정된 형식으로 출력 생성
    # 선택적으로 시각화 포함
```

낮은 자유도 (특정 스크립트, 매개변수가 거의 없거나 전혀 없음):

다음과 같은 경우에 사용한다.

• 작업이 취약하고 오류가 발생하기 쉬운 경우
• 일관성이 중요한 경우
• 특정 순서를 따라야 하는 경우

예시:

## 데이터베이스 마이그레이션

정확히 이 스크립트를 실행한다.

```bash
python scripts/migrate.py --verify --backup
```

명령을 수정하거나 추가 플래그를 추가하지 않는다.

비유: Claude를 경로를 탐색하는 로봇으로 생각한다.

• 양쪽에 절벽이 있는 좁은 다리: 안전한 방법은 하나뿐이다. 특정 가드레일과 정확한 지침을 제공한다(낮은 자유도). 예: 정확한 순서로 실행해야 하는 데이터베이스 마이그레이션.
• 장애물이 없는 열린 들판: 많은 경로가 성공으로 이어진다. 일반적인 방향을 제공하고 Claude가 최선의 경로를 찾도록 신뢰한다(높은 자유도). 예: 컨텍스트가 최선의 접근 방식을 결정하는 코드 리뷰.

사용할 계획인 모든 모델로 테스트한다

Skill은 모델에 추가되는 것이므로 효과는 기본 모델에 따라 달라진다. 사용할 계획인 모든 모델로 Skill을 테스트한다.

모델별 테스트 고려사항:

• Claude Haiku (빠르고 경제적): Skill이 충분한 지침을 제공하는가?
• Claude Sonnet (균형잡힌): Skill이 명확하고 효율적인가?
• Claude Opus (강력한 추론): Skill이 과도한 설명을 피하는가?

Opus에서 완벽하게 작동하는 것이 Haiku에서는 더 많은 세부 정보가 필요할 수 있다. 여러 모델에서 Skill을 사용할 계획이라면 모든 모델에서 잘 작동하는 지침을 목표로 한다.

Skill 구조

YAML Frontmatter: SKILL.md frontmatter에는 두 개의 필드가 필요하다.

name:

• 최대 64자
• 소문자, 숫자 및 하이픈만 포함해야 한다
• XML 태그를 포함할 수 없다
• 예약어를 포함할 수 없다. "anthropic", "claude"

description:

• 비어 있지 않아야 한다
• 최대 1024자
• XML 태그를 포함할 수 없다
• Skill이 무엇을 하는지, 언제 사용하는지 설명해야 한다

전체 Skill 구조 세부 정보는 Skills 개요를 참조하자.

명명 규칙

Skill을 더 쉽게 참조하고 논의할 수 있도록 일관된 명명 패턴을 사용한다. 동명사 형태(동사 + -ing)를 Skill 이름으로 사용하는 것을 권장한다. 이는 Skill이 제공하는 활동이나 기능을 명확하게 설명하기 때문이다.

name 필드는 소문자, 숫자 및 하이픈만 사용해야 한다는 점을 기억한다.

좋은 명명 예시 (동명사 형태):

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code
• writing-documentation

허용되는 대안:

• 명사구: pdf-processing, spreadsheet-analysis
• 행동 지향: process-pdfs, analyze-spreadsheets

피해야 할 것:

• 모호한 이름: helper, utils, tools
• 지나치게 일반적: documents, data, files
• 예약어: anthropic-helper, claude-tools
• skill 컬렉션 내에서 일관성 없는 패턴

일관된 명명은 다음을 더 쉽게 만든다.

• 문서 및 대화에서 Skill 참조
• 한눈에 Skill이 무엇을 하는지 이해
• 여러 Skill을 구성하고 검색
• 전문적이고 일관성 있는 skill 라이브러리 유지

효과적인 설명 작성

description 필드는 Skill 발견을 가능하게 하며 Skill이 무엇을 하는지와 언제 사용하는지를 모두 포함해야 한다.

항상 3인칭으로 작성한다. 설명은 시스템 프롬프트에 주입되며 일관성 없는 시점은 발견 문제를 일으킬 수 있다.

• 좋음: "Excel 파일을 처리하고 보고서를 생성한다"
• 피함: "Excel 파일 처리를 도와줄 수 있다"
• 피함: "Excel 파일을 처리하는 데 사용할 수 있다"

구체적이고 핵심 용어를 포함한다. Skill이 무엇을 하는지와 언제 사용하는지에 대한 특정 트리거/컨텍스트를 모두 포함한다.

각 Skill에는 정확히 하나의 description 필드가 있다. 설명은 skill 선택에 매우 중요하다. Claude는 잠재적으로 100개 이상의 사용 가능한 Skill 중에서 올바른 Skill을 선택하는 데 이를 사용한다. 설명은 Claude가 이 Skill을 선택해야 할 때를 알 수 있을 만큼 충분한 세부 정보를 제공해야 하며, SKILL.md의 나머지 부분은 구현 세부 정보를 제공한다.

효과적인 예시:

PDF 처리 skill:

description: PDF 파일에서 텍스트와 표를 추출하고, 양식을 채우고, 문서를 병합한다. PDF 파일을 다루거나 사용자가 PDF, 양식 또는 문서 추출을 언급할 때 사용한다.

Excel 분석 skill:

description: Excel 스프레드시트를 분석하고, 피벗 테이블을 만들고, 차트를 생성한다. Excel 파일, 스프레드시트, 표 형식 데이터 또는 .xlsx 파일을 분석할 때 사용한다.

Git 커밋 도우미 skill:

description: git diff를 분석하여 설명적인 커밋 메시지를 생성한다. 사용자가 커밋 메시지 작성 또는 스테이징된 변경 사항 검토에 도움을 요청할 때 사용한다.

다음과 같은 모호한 설명을 피한다.

description: 문서를 도와준다

description: 데이터를 처리한다

description: 파일로 작업을 수행한다

점진적 공개 패턴

SKILL.md는 필요에 따라 Claude를 상세한 자료로 안내하는 개요 역할을 한다. 마치 온보딩 가이드의 목차와 같다. 점진적 공개가 작동하는 방식에 대한 설명은 개요의 How Skills work를 참조하자.

실용적인 지침:

• 최적의 성능을 위해 SKILL.md 본문을 500줄 이하로 유지한다
• 이 한계에 도달하면 콘텐츠를 별도의 파일로 분할한다
• 아래 패턴을 사용하여 지침, 코드 및 리소스를 효과적으로 구성한다

시각적 개요: 단순한 것부터 복잡한 것까지

기본 Skill은 메타데이터와 지침을 포함하는 SKILL.md 파일로만 시작한다.

Skill이 커지면 필요할 때만 Claude가 로드하는 추가 콘텐츠를 번들로 제공할 수 있다.

전체 Skill 디렉토리 구조는 다음과 같을 수 있다.

pdf/
├── SKILL.md              # 주요 지침 (트리거될 때 로드됨)
├── FORMS.md              # 양식 작성 가이드 (필요에 따라 로드됨)
├── reference.md          # API 참조 (필요에 따라 로드됨)
├── examples.md           # 사용 예시 (필요에 따라 로드됨)
└── scripts/
    ├── analyze_form.py   # 유틸리티 스크립트 (실행됨, 로드되지 않음)
    ├── fill_form.py      # 양식 작성 스크립트
    └── validate.py       # 유효성 검사 스크립트

패턴 1: 참조가 있는 높은 수준의 가이드

---
name: pdf-processing
description: PDF 파일에서 텍스트와 표를 추출하고, 양식을 채우고, 문서를 병합한다. PDF 파일을 다루거나 사용자가 PDF, 양식 또는 문서 추출을 언급할 때 사용한다.
---

# PDF 처리

## 빠른 시작

pdfplumber로 텍스트를 추출한다.
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 고급 기능

**양식 작성**: 전체 가이드는 [FORMS.md](FORMS.md)를 참조한다
**API 참조**: 모든 메서드는 [REFERENCE.md](REFERENCE.md)를 참조한다
**예시**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md)를 참조한다

Claude는 필요할 때만 FORMS.md, REFERENCE.md 또는 EXAMPLES.md를 로드한다.

패턴 2: 도메인별 구성

여러 도메인이 있는 Skill의 경우 관련 없는 컨텍스트 로드를 피하기 위해 도메인별로 콘텐츠를 구성한다. 사용자가 판매 지표에 대해 질문할 때 Claude는 판매 관련 스키마만 읽으면 되며 재무나 마케팅 데이터는 필요하지 않다. 이는 토큰 사용량을 낮게 유지하고 컨텍스트에 집중하게 한다.

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (수익, 청구 지표)
    ├── sales.md (기회, 파이프라인)
    ├── product.md (API 사용, 기능)
    └── marketing.md (캠페인, 어트리뷰션)

# BigQuery 데이터 분석

## 사용 가능한 데이터셋

**재무**: 수익, ARR, 청구 → [reference/finance.md](reference/finance.md) 참조
**판매**: 기회, 파이프라인, 계정 → [reference/sales.md](reference/sales.md) 참조
**제품**: API 사용, 기능, 도입 → [reference/product.md](reference/product.md) 참조
**마케팅**: 캠페인, 어트리뷰션, 이메일 → [reference/marketing.md](reference/marketing.md) 참조

## 빠른 검색

grep을 사용하여 특정 지표를 찾는다.

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

패턴 3: 조건부 세부 정보

기본 콘텐츠를 표시하고 고급 콘텐츠에 링크한다.

# DOCX 처리

## 문서 생성

새 문서에는 docx-js를 사용한다.

## 문서 편집

간단한 편집의 경우 XML을 직접 수정한다.

**변경 사항 추적**: [REDLINING.md](REDLINING.md)를 참조한다
**OOXML 세부 정보**: [OOXML.md](OOXML.md)를 참조한다

Claude는 사용자가 이러한 기능이 필요할 때만 REDLINING.md 또는 OOXML.md를 읽는다.

깊게 중첩된 참조를 피한다

Claude는 다른 참조 파일에서 참조될 때 파일을 부분적으로 읽을 수 있다. 중첩된 참조를 만날 때 Claude는 전체 파일을 읽는 대신 head -100과 같은 명령을 사용하여 콘텐츠를 미리 볼 수 있으며, 이는 불완전한 정보를 초래할 수 있다.

SKILL.md에서 한 단계 깊이의 참조를 유지한다. 모든 참조 파일은 SKILL.md에서 직접 링크되어야 Claude가 필요할 때 전체 파일을 읽을 수 있도록 보장한다.

나쁜 예: 너무 깊음:

# SKILL.md
[advanced.md](advanced.md) 참조...

# advanced.md
[details.md](details.md) 참조...

# details.md
실제 정보는 여기에...

좋은 예: 한 단계 깊이:

# SKILL.md

**기본 사용법**: [SKILL.md의 지침]
**고급 기능**: [advanced.md](advanced.md) 참조
**API 참조**: [reference.md](reference.md) 참조
**예시**: [examples.md](examples.md) 참조

더 긴 참조 파일을 목차로 구조화한다

100줄보다 긴 참조 파일의 경우 상단에 목차를 포함한다. 이는 부분 읽기로 미리 볼 때도 Claude가 사용 가능한 정보의 전체 범위를 볼 수 있도록 보장한다.

예시:

# API 참조

## 목차
- 인증 및 설정
- 핵심 메서드 (생성, 읽기, 업데이트, 삭제)
- 고급 기능 (배치 작업, 웹훅)
- 오류 처리 패턴
- 코드 예시

## 인증 및 설정
...

## 핵심 메서드
...

Claude는 필요에 따라 전체 파일을 읽거나 특정 섹션으로 이동할 수 있다.

이 파일 시스템 기반 아키텍처가 점진적 공개를 가능하게 하는 방법에 대한 세부 정보는 아래 고급 섹션의 런타임 환경 섹션을 참조하자.

워크플로우와 피드백 루프

복잡한 작업에는 워크플로우를 사용한다

복잡한 작업을 명확하고 순차적인 단계로 나눈다. 특히 복잡한 워크플로우의 경우 Claude가 응답에 복사하여 진행하면서 체크할 수 있는 체크리스트를 제공한다.

예시 1: 연구 종합 워크플로우 (코드가 없는 Skill의 경우):

## 연구 종합 워크플로우

이 체크리스트를 복사하고 진행 상황을 추적한다.

```
연구 진행 상황:
- [ ] 단계 1: 모든 소스 문서 읽기
- [ ] 단계 2: 핵심 주제 식별
- [ ] 단계 3: 주장 교차 참조
- [ ] 단계 4: 구조화된 요약 생성
- [ ] 단계 5: 인용 확인
```

**단계 1: 모든 소스 문서 읽기**

`sources/` 디렉토리의 각 문서를 검토한다. 주요 주장과 지원 증거를 기록한다.

**단계 2: 핵심 주제 식별**

소스 전반에 걸친 패턴을 찾는다. 어떤 주제가 반복적으로 나타나는가? 소스가 동의하거나 동의하지 않는 곳은 어디인가?

**단계 3: 주장 교차 참조**

각 주요 주장에 대해 소스 자료에 나타나는지 확인한다. 어떤 소스가 각 요점을 지원하는지 기록한다.

**단계 4: 구조화된 요약 생성**

주제별로 발견 사항을 구성한다. 다음을 포함한다.
- 주요 주장
- 소스의 지원 증거
- 상충되는 관점 (있는 경우)

**단계 5: 인용 확인**

모든 주장이 올바른 소스 문서를 참조하는지 확인한다. 인용이 불완전하면 단계 3으로 돌아간다.

이 예시는 코드가 필요하지 않은 분석 작업에 워크플로우가 어떻게 적용되는지 보여준다. 체크리스트 패턴은 복잡한 다단계 프로세스에 적용된다.

예시 2: PDF 양식 작성 워크플로우 (코드가 있는 Skill의 경우):

## PDF 양식 작성 워크플로우

이 체크리스트를 복사하고 완료하면서 항목을 체크한다.

```
작업 진행 상황:
- [ ] 단계 1: 양식 분석 (analyze_form.py 실행)
- [ ] 단계 2: 필드 매핑 생성 (fields.json 편집)
- [ ] 단계 3: 매핑 유효성 검사 (validate_fields.py 실행)
- [ ] 단계 4: 양식 작성 (fill_form.py 실행)
- [ ] 단계 5: 출력 확인 (verify_output.py 실행)
```

**단계 1: 양식 분석**

실행: `python scripts/analyze_form.py input.pdf`

이는 양식 필드와 위치를 추출하여 `fields.json`에 저장한다.

**단계 2: 필드 매핑 생성**

`fields.json`을 편집하여 각 필드에 값을 추가한다.

**단계 3: 매핑 유효성 검사**

실행: `python scripts/validate_fields.py fields.json`

계속하기 전에 유효성 검사 오류를 수정한다.

**단계 4: 양식 작성**

실행: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**단계 5: 출력 확인**

실행: `python scripts/verify_output.py output.pdf`

확인이 실패하면 단계 2로 돌아간다.

명확한 단계는 Claude가 중요한 유효성 검사를 건너뛰는 것을 방지한다. 체크리스트는 Claude와 사용자 모두 다단계 워크플로우의 진행 상황을 추적하는 데 도움이 된다.

피드백 루프를 구현한다

일반적인 패턴: 유효성 검사기 실행 → 오류 수정 → 반복

이 패턴은 출력 품질을 크게 향상시킨다.

예시 1: 스타일 가이드 준수 (코드가 없는 Skill의 경우):

## 콘텐츠 검토 프로세스

1. STYLE_GUIDE.md의 지침을 따라 콘텐츠를 작성한다
2. 체크리스트에 대해 검토한다.
   - 용어 일관성 확인
   - 예시가 표준 형식을 따르는지 확인
   - 모든 필수 섹션이 있는지 확인
3. 문제가 발견되면:
   - 특정 섹션 참조와 함께 각 문제를 기록한다
   - 콘텐츠를 수정한다
   - 체크리스트를 다시 검토한다
4. 모든 요구 사항이 충족될 때만 계속 진행한다
5. 문서를 완성하고 저장한다

이는 스크립트 대신 참조 문서를 사용하는 유효성 검사 루프 패턴을 보여준다. "유효성 검사기"는 STYLE_GUIDE.md이며 Claude는 읽고 비교하여 검사를 수행한다.

예시 2: 문서 편집 프로세스 (코드가 있는 Skill의 경우):

## 문서 편집 프로세스

1. `word/document.xml`을 편집한다
2. **즉시 유효성 검사**: `python ooxml/scripts/validate.py unpacked_dir/`
3. 유효성 검사가 실패하면:
   - 오류 메시지를 주의 깊게 검토한다
   - XML의 문제를 수정한다
   - 유효성 검사를 다시 실행한다
4. **유효성 검사가 통과할 때만 계속 진행한다**
5. 재빌드: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. 출력 문서를 테스트한다

유효성 검사 루프는 오류를 조기에 포착한다.

콘텐츠 가이드라인

시간에 민감한 정보를 피한다

오래될 정보를 포함하지 않는다.

나쁜 예: 시간에 민감함 (오래되면 틀리게 됨):

2025년 8월 이전에 이 작업을 수행하는 경우 이전 API를 사용한다.
2025년 8월 이후에는 새 API를 사용한다.

좋은 예 ("이전 패턴" 섹션 사용):

## 현재 메서드

v2 API 엔드포인트를 사용한다. `api.example.com/v2/messages`

## 이전 패턴

<details>
<summary>레거시 v1 API (2025-08 폐기됨)</summary>

v1 API는 다음을 사용했다. `api.example.com/v1/messages`

이 엔드포인트는 더 이상 지원되지 않는다.
</details>

이전 패턴 섹션은 주요 콘텐츠를 복잡하게 만들지 않으면서 역사적 컨텍스트를 제공한다.

일관된 용어를 사용한다

하나의 용어를 선택하고 Skill 전체에서 사용한다.

좋음 - 일관성 있음:

• 항상 "API 엔드포인트"
• 항상 "필드"
• 항상 "추출"

나쁨 - 일관성 없음:

• "API 엔드포인트", "URL", "API 경로", "경로" 혼용
• "필드", "박스", "요소", "컨트롤" 혼용
• "추출", "가져오기", "얻기", "검색" 혼용

일관성은 Claude가 지침을 이해하고 따르는 데 도움이 된다.

일반적인 패턴

템플릿 패턴

출력 형식에 대한 템플릿을 제공한다. 엄격함의 수준을 필요에 맞춘다.

엄격한 요구 사항의 경우 (API 응답이나 데이터 형식 같은):

## 보고서 구조

항상 이 정확한 템플릿 구조를 사용한다.

```markdown
# [분석 제목]

## 요약
[주요 발견 사항의 한 단락 개요]

## 주요 발견 사항
- 지원 데이터가 있는 발견 사항 1
- 지원 데이터가 있는 발견 사항 2
- 지원 데이터가 있는 발견 사항 3

## 권장 사항
1. 구체적이고 실행 가능한 권장 사항
2. 구체적이고 실행 가능한 권장 사항
```

유연한 지침의 경우 (적응이 유용할 때):

## 보고서 구조

다음은 합리적인 기본 형식이지만 분석에 따라 최선의 판단을 사용한다.

```markdown
# [분석 제목]

## 요약
[개요]

## 주요 발견 사항
[발견한 내용에 따라 섹션을 조정한다]

## 권장 사항
[특정 컨텍스트에 맞게 조정한다]
```

특정 분석 유형에 필요에 따라 섹션을 조정한다.

예시 패턴

출력 품질이 예시를 보는 것에 달려 있는 Skill의 경우 일반 프롬프팅에서처럼 입력/출력 쌍을 제공한다.

## 커밋 메시지 형식

다음 예시를 따라 커밋 메시지를 생성한다.

**예시 1:**
입력: JWT 토큰을 사용한 사용자 인증 추가
출력:
```
feat(auth): JWT 기반 인증 구현

로그인 엔드포인트 및 토큰 유효성 검사 미들웨어 추가
```

**예시 2:**
입력: 보고서에서 날짜가 잘못 표시되는 버그 수정
출력:
```
fix(reports): 시간대 변환의 날짜 형식 수정

보고서 생성 전반에 걸쳐 UTC 타임스탬프를 일관되게 사용
```

**예시 3:**
입력: 종속성 업데이트 및 오류 처리 리팩토링
출력:
```
chore: 종속성 업데이트 및 오류 처리 리팩토링

- lodash를 4.17.21로 업그레이드
- 엔드포인트 전반의 오류 응답 형식 표준화
```

이 스타일을 따른다. type(scope): 간략한 설명, 그 다음 상세한 설명.

예시는 Claude가 설명만으로는 파악하기 어려운 원하는 스타일과 세부 수준을 이해하는 데 도움이 된다.

조건부 워크플로우 패턴

결정 지점을 통해 Claude를 안내한다.

## 문서 수정 워크플로우

1. 수정 유형을 결정한다.

   **새 콘텐츠를 생성하는가?** → 아래 "생성 워크플로우"를 따른다
   **기존 콘텐츠를 편집하는가?** → 아래 "편집 워크플로우"를 따른다

2. 생성 워크플로우:
   - docx-js 라이브러리를 사용한다
   - 처음부터 문서를 빌드한다
   - .docx 형식으로 내보낸다

3. 편집 워크플로우:
   - 기존 문서의 압축을 푼다
   - XML을 직접 수정한다
   - 각 변경 후 유효성을 검사한다
   - 완료되면 다시 압축한다

팁

워크플로우가 크거나 많은 단계로 복잡해지면 별도의 파일로 푸시하고 당면한 작업에 따라 적절한 파일을 읽도록 Claude에게 지시하는 것을 고려한다.

평가 및 반복

평가를 먼저 구축한다

광범위한 문서를 작성하기 전에 평가를 생성한다. 이는 Skill이 상상한 문제가 아닌 실제 문제를 해결하도록 보장한다.

평가 중심 개발:

1. 격차 식별: Skill 없이 대표적인 작업에서 Claude를 실행한다. 특정 실패나 누락된 컨텍스트를 문서화한다
2. 평가 생성: 이러한 격차를 테스트하는 세 가지 시나리오를 구축한다
3. 기준선 설정: Skill 없이 Claude의 성능을 측정한다
4. 최소 지침 작성: 격차를 해결하고 평가를 통과하기에 충분한 콘텐츠만 생성한다
5. 반복: 평가를 실행하고 기준선과 비교하여 개선한다

이 접근 방식은 결코 실현되지 않을 수 있는 요구 사항을 예상하는 것이 아니라 실제 문제를 해결하도록 보장한다.

평가 구조:

{
  "skills": ["pdf-processing"],
  "query": "이 PDF 파일에서 모든 텍스트를 추출하여 output.txt에 저장한다",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "적절한 PDF 처리 라이브러리 또는 명령줄 도구를 사용하여 PDF 파일을 성공적으로 읽는다",
    "페이지를 놓치지 않고 문서의 모든 페이지에서 텍스트 콘텐츠를 추출한다",
    "추출된 텍스트를 명확하고 읽기 쉬운 형식으로 output.txt라는 파일에 저장한다"
  ]
}

참고

이 예시는 간단한 테스트 루브릭이 있는 데이터 중심 평가를 보여준다. 현재 이러한 평가를 실행하는 기본 제공 방법을 제공하지 않는다. 사용자는 자체 평가 시스템을 만들 수 있다. 평가는 Skill 효과를 측정하는 진실의 원천이다.

Claude와 함께 Skill을 반복적으로 개발한다

가장 효과적인 Skill 개발 프로세스는 Claude 자체를 포함한다. 하나의 Claude 인스턴스("Claude A")와 함께 작업하여 다른 인스턴스("Claude B")가 사용할 Skill을 만든다. Claude A는 지침을 설계하고 개선하는 데 도움을 주고 Claude B는 실제 작업에서 이를 테스트한다. Claude 모델은 효과적인 에이전트 지침을 작성하는 방법과 에이전트에게 필요한 정보를 모두 이해하기 때문에 이것이 작동한다.

새 Skill 만들기:

1. Skill 없이 작업 완료: 일반 프롬프팅을 사용하여 Claude A와 함께 문제를 해결한다. 작업하면서 자연스럽게 컨텍스트를 제공하고, 선호도를 설명하고, 절차적 지식을 공유한다. 반복적으로 제공하는 정보를 주목한다.
2. 재사용 가능한 패턴 식별: 작업을 완료한 후 유사한 미래 작업에 유용할 제공한 컨텍스트를 식별한다.

   예시: BigQuery 분석을 진행했다면 테이블 이름, 필드 정의, 필터링 규칙(예: "항상 테스트 계정 제외"), 일반적인 쿼리 패턴을 제공했을 수 있다.

3. Claude A에게 Skill 생성 요청: "방금 사용한 이 BigQuery 분석 패턴을 포착하는 Skill을 만들어줘. 테이블 스키마, 명명 규칙, 테스트 계정 필터링에 대한 규칙을 포함해줘."

   팁

   Claude 모델은 Skill 형식과 구조를 기본적으로 이해한다. Skill을 만들도록 Claude를 돕기 위해 특별한 시스템 프롬프트나 "스킬 작성" skill이 필요하지 않다. Claude에게 Skill을 만들라고 요청하기만 하면 적절한 frontmatter와 본문 콘텐츠가 있는 올바르게 구조화된 SKILL.md 콘텐츠를 생성한다.

4. 간결성 검토: Claude A가 불필요한 설명을 추가하지 않았는지 확인한다. "승률이 무엇을 의미하는지에 대한 설명을 제거해줘 - Claude는 이미 알고 있어."라고 요청한다.
5. 정보 아키텍처 개선: Claude A에게 콘텐츠를 더 효과적으로 구성하도록 요청한다. 예를 들어: "테이블 스키마가 별도의 참조 파일에 있도록 구성해줘. 나중에 더 많은 테이블을 추가할 수 있어."
6. 유사한 작업에서 테스트: Skill이 로드된 Claude B(새 인스턴스)와 관련 사용 사례에서 Skill을 사용한다. Claude B가 올바른 정보를 찾고, 규칙을 올바르게 적용하고, 작업을 성공적으로 처리하는지 관찰한다.
7. 관찰을 기반으로 반복: Claude B가 어려움을 겪거나 무언가를 놓치면 구체적인 내용과 함께 Claude A로 돌아간다. "Claude가 이 Skill을 사용했을 때 Q4의 날짜별 필터링을 잊었어. 날짜 필터링 패턴에 대한 섹션을 추가해야 할까?"

기존 Skill 반복:

Skill을 개선할 때도 동일한 계층적 패턴이 계속된다. 다음 사이를 번갈아 가며:

• Claude A와 작업 (Skill을 개선하는 데 도움을 주는 전문가)
• Claude B로 테스트 (실제 작업을 수행하기 위해 Skill을 사용하는 에이전트)
• Claude B의 동작 관찰 및 인사이트를 Claude A에게 다시 가져오기

1. 실제 워크플로우에서 Skill 사용: Claude B(Skill이 로드된)에게 테스트 시나리오가 아닌 실제 작업을 제공한다
2. Claude B의 동작 관찰: 어려움을 겪거나, 성공하거나, 예상치 못한 선택을 하는 곳을 기록한다

   예시 관찰: "Claude B에게 지역 판매 보고서를 요청했을 때 쿼리를 작성했지만 Skill이 이 규칙을 언급하고 있음에도 불구하고 테스트 계정을 필터링하는 것을 잊었어."

3. 개선을 위해 Claude A로 돌아가기: 현재 SKILL.md를 공유하고 관찰한 내용을 설명한다. "지역 보고서를 요청했을 때 Claude B가 테스트 계정을 필터링하는 것을 잊었어. Skill이 필터링을 언급하지만 충분히 눈에 띄지 않을 수 있어?"라고 요청한다.
4. Claude A의 제안 검토: Claude A는 규칙을 더 눈에 띄게 만들기 위해 재구성하거나, "항상 필터링" 대신 "반드시 필터링"과 같은 더 강한 언어를 사용하거나, 워크플로우 섹션을 재구성하도록 제안할 수 있다.
5. 변경 사항 적용 및 테스트: Claude A의 개선 사항으로 Skill을 업데이트한 다음 유사한 요청으로 Claude B로 다시 테스트한다
6. 사용을 기반으로 반복: 새로운 시나리오를 만날 때 이 관찰-개선-테스트 사이클을 계속한다. 각 반복은 가정이 아닌 실제 에이전트 동작을 기반으로 Skill을 개선한다.

팀 피드백 수집:

1. 팀원과 Skill을 공유하고 사용을 관찰한다
2. 질문한다. Skill이 예상대로 활성화되는가? 지침이 명확한가? 무엇이 누락되었는가?
3. 자신의 사용 패턴에서 맹점을 해결하기 위해 피드백을 통합한다

이 접근 방식이 작동하는 이유: Claude A는 에이전트 요구 사항을 이해하고, 사용자는 도메인 전문 지식을 제공하고, Claude B는 실제 사용을 통해 격차를 드러내고, 반복적인 개선은 가정이 아닌 관찰된 동작을 기반으로 Skill을 개선한다.

Claude가 Skill을 탐색하는 방법을 관찰한다

Skill을 반복할 때 Claude가 실제로 어떻게 사용하는지 주의를 기울인다. 다음을 주목한다.

• 예상치 못한 탐색 경로: Claude가 예상하지 못한 순서로 파일을 읽는가? 이는 구조가 생각만큼 직관적이지 않음을 나타낼 수 있다
• 놓친 연결: Claude가 중요한 파일에 대한 참조를 따르지 못하는가? 링크를 더 명시적이거나 눈에 띄게 만들어야 할 수 있다
• 특정 섹션에 대한 과도한 의존: Claude가 반복적으로 동일한 파일을 읽는 경우 해당 콘텐츠가 주요 SKILL.md에 있어야 하는지 고려한다
• 무시된 콘텐츠: Claude가 번들 파일에 절대 액세스하지 않는 경우 불필요하거나 주요 지침에서 제대로 표시되지 않을 수 있다

가정이 아닌 이러한 관찰을 기반으로 반복한다. Skill의 메타데이터에 있는 'name'과 'description'은 특히 중요하다. Claude는 현재 작업에 대한 응답으로 Skill을 트리거할지 결정할 때 이것을 사용한다. Skill이 무엇을 하는지, 언제 사용해야 하는지 명확하게 설명하는지 확인한다.

피해야 할 안티패턴

Windows 스타일 경로를 피한다

Windows에서도 파일 경로에 항상 슬래시를 사용한다.

• ✓ 좋음: scripts/helper.py, reference/guide.md
• ✗ 피함: scripts\helper.py, reference\guide.md

Unix 스타일 경로는 모든 플랫폼에서 작동하지만 Windows 스타일 경로는 Unix 시스템에서 오류를 일으킨다.

너무 많은 옵션을 제공하는 것을 피한다

필요하지 않은 경우 여러 접근 방식을 제시하지 않는다.

나쁜 예: 너무 많은 선택 (혼란스러움):

"pypdf 또는 pdfplumber 또는 PyMuPDF 또는 pdf2image 또는..."를 사용할 수 있다

좋은 예: 기본값 제공 (탈출구 포함):

"텍스트 추출에는 pdfplumber를 사용한다.
```python
import pdfplumber
```

OCR이 필요한 스캔된 PDF의 경우 대신 pytesseract와 함께 pdf2image를 사용한다."

고급: 실행 가능한 코드가 있는 Skill

아래 섹션은 실행 가능한 스크립트를 포함하는 Skill에 중점을 둔다. Skill이 마크다운 지침만 사용하는 경우 효과적인 Skill 체크리스트로 건너뛴다.

해결하고 미루지 않는다

Skill용 스크립트를 작성할 때 Claude에게 미루지 말고 오류 조건을 처리한다.

좋은 예: 오류를 명시적으로 처리:

def process_file(path):
    """파일을 처리하고 존재하지 않으면 생성한다."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 실패하는 대신 기본 콘텐츠로 파일을 생성한다
        print(f"파일 {path}를 찾을 수 없음, 기본값 생성")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # 실패하는 대신 대안을 제공한다
        print(f"{path}에 액세스할 수 없음, 기본값 사용")
        return ''

나쁜 예: Claude에게 미룸:

def process_file(path):
    # 그냥 실패하고 Claude가 알아내도록 한다
    return open(path).read()

구성 매개변수도 "부두 상수"(Ousterhout의 법칙)를 피하기 위해 정당화되고 문서화되어야 한다. 올바른 값을 모르면 Claude가 어떻게 결정할까?

좋은 예: 자체 문서화:

# HTTP 요청은 일반적으로 30초 이내에 완료된다
# 더 긴 타임아웃은 느린 연결을 고려한다
REQUEST_TIMEOUT = 30

# 세 번의 재시도는 안정성과 속도의 균형을 맞춘다
# 대부분의 간헐적 실패는 두 번째 재시도에서 해결된다
MAX_RETRIES = 3

나쁜 예: 마법 숫자:

TIMEOUT = 47  # 왜 47?
RETRIES = 5   # 왜 5?

유틸리티 스크립트를 제공한다

Claude가 스크립트를 작성할 수 있더라도 미리 만들어진 스크립트는 장점을 제공한다.

유틸리티 스크립트의 이점:

• 생성된 코드보다 더 안정적이다
• 토큰을 절약한다(컨텍스트에 코드를 포함할 필요가 없음)
• 시간을 절약한다(코드 생성이 필요하지 않음)
• 사용 전반에 걸쳐 일관성을 보장한다

위 다이어그램은 실행 가능한 스크립트가 지침 파일과 함께 작동하는 방법을 보여준다. 지침 파일(forms.md)은 스크립트를 참조하며 Claude는 콘텐츠를 컨텍스트에 로드하지 않고도 실행할 수 있다.

중요한 구분: 지침에서 Claude가 다음을 해야 하는지 명확히 한다.

• 스크립트 실행 (가장 일반적): "필드를 추출하려면 analyze_form.py를 실행한다"
• 참조로 읽기 (복잡한 로직의 경우): "필드 추출 알고리즘은 analyze_form.py를 참조한다"

대부분의 유틸리티 스크립트의 경우 실행이 더 안정적이고 효율적이기 때문에 선호된다. 스크립트 실행이 작동하는 방법에 대한 세부 정보는 아래 런타임 환경 섹션을 참조하자.

예시:

## 유틸리티 스크립트

**analyze_form.py**: PDF에서 모든 양식 필드를 추출한다

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

출력 형식:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: 겹치는 경계 상자를 확인한다

```bash
python scripts/validate_boxes.py fields.json
# 반환: "OK" 또는 충돌 목록
```

**fill_form.py**: PDF에 필드 값을 적용한다

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

시각적 분석을 사용한다

입력을 이미지로 렌더링할 수 있는 경우 Claude가 분석하도록 한다.

## 양식 레이아웃 분석

1. PDF를 이미지로 변환한다.
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. 각 페이지 이미지를 분석하여 양식 필드를 식별한다
3. Claude는 필드 위치와 유형을 시각적으로 볼 수 있다

참고

이 예시에서는 pdf_to_images.py 스크립트를 작성해야 한다.

Claude의 비전 기능은 레이아웃과 구조를 이해하는 데 도움이 된다.

검증 가능한 중간 출력을 생성한다

Claude가 복잡하고 개방형 작업을 수행할 때 실수를 할 수 있다. "계획-검증-실행" 패턴은 Claude가 먼저 구조화된 형식으로 계획을 만든 다음 실행하기 전에 스크립트로 해당 계획을 검증하도록 하여 오류를 조기에 포착한다.

예시: 스프레드시트를 기반으로 PDF의 50개 양식 필드를 업데이트하도록 Claude에게 요청한다고 상상한다. 검증 없이 Claude는 존재하지 않는 필드를 참조하거나, 충돌하는 값을 생성하거나, 필수 필드를 놓치거나, 업데이트를 잘못 적용할 수 있다.

해결책: 위에 표시된 워크플로우 패턴(PDF 양식 작성)을 사용하되 변경 사항을 적용하기 전에 검증되는 중간 changes.json 파일을 추가한다. 워크플로우는 다음과 같이 된다. 분석 → 계획 파일 생성 → 계획 검증 → 실행 → 확인.

이 패턴이 작동하는 이유:

• 오류를 조기에 포착: 검증은 변경 사항이 적용되기 전에 문제를 찾는다
• 기계 검증 가능: 스크립트는 객관적인 검증을 제공한다
• 가역적 계획: Claude는 원본을 건드리지 않고 계획을 반복할 수 있다
• 명확한 디버깅: 오류 메시지는 특정 문제를 가리킨다

사용 시점: 배치 작업, 파괴적 변경, 복잡한 검증 규칙, 고위험 작업.

구현 팁: "필드 'signature_date'를 찾을 수 없음. 사용 가능한 필드: customer_name, order_total, signature_date_signed"와 같은 구체적인 오류 메시지와 함께 검증 스크립트를 자세히 작성하여 Claude가 문제를 수정하는 데 도움이 되도록 한다.

패키지 종속성

Skill은 플랫폼별 제한이 있는 코드 실행 환경에서 실행된다.

• claude.ai: npm 및 PyPI에서 패키지를 설치하고 GitHub 저장소에서 가져올 수 있다
• Anthropic API: 네트워크 액세스가 없고 런타임 패키지 설치가 없다

SKILL.md에 필요한 패키지를 나열하고 코드 실행 도구 문서에서 사용 가능한지 확인한다.

런타임 환경

Skill은 파일 시스템 액세스, bash 명령 및 코드 실행 기능이 있는 코드 실행 환경에서 실행된다. 이 아키텍처에 대한 개념적 설명은 개요의 The Skills architecture를 참조하자.

작성에 미치는 영향:

Claude가 Skill에 액세스하는 방법:

1. 메타데이터 사전 로드: 시작 시 모든 Skill의 YAML frontmatter에서 name과 description이 시스템 프롬프트에 로드된다
2. 필요 시 파일 읽기: Claude는 필요할 때 bash Read 도구를 사용하여 파일 시스템에서 SKILL.md 및 기타 파일에 액세스한다
3. 스크립트를 효율적으로 실행: 유틸리티 스크립트는 전체 콘텐츠를 컨텍스트에 로드하지 않고 bash를 통해 실행될 수 있다. 스크립트의 출력만 토큰을 소비한다
4. 대용량 파일에 대한 컨텍스트 페널티 없음: 참조 파일, 데이터 또는 문서는 실제로 읽을 때까지 컨텍스트 토큰을 소비하지 않는다

• 파일 경로가 중요함: Claude는 skill 디렉토리를 파일 시스템처럼 탐색한다. 슬래시(reference/guide.md)를 사용하고 백슬래시를 사용하지 않는다
• 파일 이름을 설명적으로 지정: 콘텐츠를 나타내는 이름을 사용한다. form_validation_rules.md, doc2.md가 아님
• 발견을 위해 구성: 도메인 또는 기능별로 디렉토리를 구조화한다
  • 좋음: reference/finance.md, reference/sales.md
  • 나쁨: docs/file1.md, docs/file2.md
• 포괄적인 리소스 번들: 완전한 API 문서, 광범위한 예시, 대용량 데이터셋을 포함한다; 액세스할 때까지 컨텍스트 페널티 없음
• 결정론적 작업에는 스크립트 선호: Claude에게 검증 코드를 생성하도록 요청하는 대신 validate_form.py를 작성한다
• 실행 의도를 명확히:
  • "필드를 추출하려면 analyze_form.py를 실행한다" (실행)
  • "추출 알고리즘은 analyze_form.py를 참조한다" (참조로 읽기)
• 파일 액세스 패턴 테스트: 실제 요청으로 테스트하여 Claude가 디렉토리 구조를 탐색할 수 있는지 확인한다

예시:

bigquery-skill/
├── SKILL.md (개요, 참조 파일을 가리킴)
└── reference/
    ├── finance.md (수익 지표)
    ├── sales.md (파이프라인 데이터)
    └── product.md (사용 분석)

사용자가 수익에 대해 질문하면 Claude는 SKILL.md를 읽고 reference/finance.md에 대한 참조를 보고 bash를 호출하여 해당 파일만 읽는다. sales.md 및 product.md 파일은 파일 시스템에 남아 있으며 필요할 때까지 0개의 컨텍스트 토큰을 소비한다. 이 파일 시스템 기반 모델이 점진적 공개를 가능하게 하는 것이다. Claude는 각 작업이 필요로 하는 것을 정확하게 탐색하고 선택적으로 로드할 수 있다.

기술 아키텍처에 대한 완전한 세부 정보는 Skills 개요의 How Skills work를 참조하자.

MCP 도구 참조

Skill이 MCP(Model Context Protocol) 도구를 사용하는 경우 "도구를 찾을 수 없음" 오류를 피하기 위해 항상 정규화된 도구 이름을 사용한다.

형식: ServerName:tool_name

예시:

BigQuery:bigquery_schema 도구를 사용하여 테이블 스키마를 검색한다.
GitHub:create_issue 도구를 사용하여 이슈를 생성한다.

여기서:

• BigQuery와 GitHub는 MCP 서버 이름이다
• bigquery_schema와 create_issue는 해당 서버 내의 도구 이름이다

서버 접두사가 없으면 Claude는 특히 여러 MCP 서버를 사용할 수 있을 때 도구를 찾지 못할 수 있다.

도구가 설치되어 있다고 가정하지 않는다

패키지를 사용할 수 있다고 가정하지 않는다.

나쁜 예: 설치를 가정:

"pdf 라이브러리를 사용하여 파일을 처리한다."

좋은 예: 종속성에 대해 명시적:

"필요한 패키지를 설치한다. `pip install pypdf`

그런 다음 사용한다.
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

기술적 참고 사항

YAML frontmatter 요구 사항

SKILL.md frontmatter에는 특정 검증 규칙이 있는 name과 description 필드가 필요하다.

• name: 최대 64자, 소문자/숫자/하이픈만, XML 태그 없음, 예약어 없음
• description: 최대 1024자, 비어 있지 않음, XML 태그 없음

전체 구조 세부 정보는 Skills 개요를 참조하자.

토큰 예산

최적의 성능을 위해 SKILL.md 본문을 500줄 이하로 유지한다. 콘텐츠가 이를 초과하면 앞에서 설명한 점진적 공개 패턴을 사용하여 별도의 파일로 분할한다. 아키텍처 세부 정보는 Skills 개요를 참조하자.

효과적인 Skill 체크리스트

Skill을 공유하기 전에 확인한다.

핵심 품질

• ☐ 설명이 구체적이고 핵심 용어를 포함한다
• ☐ 설명이 Skill이 무엇을 하는지와 언제 사용하는지를 모두 포함한다
• ☐ SKILL.md 본문이 500줄 이하다
• ☐ 추가 세부 정보가 별도의 파일에 있다 (필요한 경우)
• ☐ 시간에 민감한 정보가 없다 (또는 "이전 패턴" 섹션에 있음)
• ☐ 전체에 걸쳐 일관된 용어를 사용한다
• ☐ 예시가 구체적이고 추상적이지 않다
• ☐ 파일 참조가 한 단계 깊이다
• ☐ 점진적 공개를 적절히 사용한다
• ☐ 워크플로우에 명확한 단계가 있다

코드 및 스크립트

• ☐ 스크립트가 Claude에게 미루지 않고 문제를 해결한다
• ☐ 오류 처리가 명시적이고 유용하다
• ☐ "부두 상수"가 없다 (모든 값이 정당화됨)
• ☐ 필요한 패키지가 지침에 나열되어 있고 사용 가능한 것으로 확인되었다
• ☐ 스크립트에 명확한 문서가 있다
• ☐ Windows 스타일 경로가 없다 (모두 슬래시 사용)
• ☐ 중요한 작업에 대한 검증/확인 단계가 있다
• ☐ 품질이 중요한 작업에 피드백 루프가 포함되어 있다

테스트

• ☐ 최소 3개의 평가가 생성되었다
• ☐ Haiku, Sonnet 및 Opus로 테스트되었다
• ☐ 실제 사용 시나리오로 테스트되었다
• ☐ 팀 피드백이 통합되었다 (해당하는 경우)