<br> # Claude 스킬 만들기 완벽 가이드 > **The Complete Guide to Building Skills for Claude — 한국어 번역본 정리본** 이 문서는 업로드된 PDF의 내용을 바탕으로, 원문의 장·절 구조와 핵심 개념을 유지하면서 Markdown 문서로 다시 정리한 버전입니다. --- ## 목차 1. [소개](#소개) 2. [Chapter 1. 기본 개념](#chapter-1-기본-개념) 3. [Chapter 2. 계획 및 설계](#chapter-2-계획-및-설계) 4. [Chapter 3. 테스트와 반복 개선](#chapter-3-테스트와-반복-개선) 5. [Chapter 4. 배포 및 공유](#chapter-4-배포-및-공유) 6. [Chapter 5. 패턴과 트러블슈팅](#chapter-5-패턴과-트러블슈팅) 7. [Chapter 6. 리소스 및 참고자료](#chapter-6-리소스-및-참고자료) 8. [부록 A. 빠른 체크리스트](#부록-a-빠른-체크리스트) 9. [부록 B. YAML 프론트매터 참고](#부록-b-yaml-프론트매터-참고) 10. [부록 C. 완전한 스킬 예시 안내](#부록-c-완전한-스킬-예시-안내) 11. [핵심 요약](#핵심-요약) --- # 소개 ## 스킬(Skill)이란? **스킬(Skill)**은 특정 작업이나 워크플로우를 Claude가 처리하는 방법을 가르치기 위해 **폴더 형태로 패키징된 명령어 모음**입니다. 매번 대화할 때마다 다음 내용을 반복해서 설명하는 대신: - 선호하는 작업 방식 - 조직 또는 개인의 작업 절차 - 전문 지식 - 품질 기준 - 도구 사용 순서 이를 스킬에 한 번 정의해 두면, 필요할 때 Claude가 해당 지침을 불러와 일관되게 적용할 수 있습니다. ### 특히 효과적인 활용 사례 - 사양서를 기반으로 프론트엔드 디자인 생성 - 일관된 방법론으로 리서치 수행 - 팀의 스타일 가이드에 맞는 문서 작성 - 다단계 업무 프로세스 조율 - 코드 실행 및 문서 생성 - MCP와 결합한 자동화 워크플로우 ## 이 가이드에서 배우는 내용 - 스킬 구조의 기술 요구사항과 모범 사례 - 독립형 스킬과 MCP 연동 패턴 - 효과가 검증된 활용 패턴 - 테스트 방법 - 반복 개선 방법 - 배포 및 공유 방법 ## 대상 독자 - Claude가 특정 워크플로우를 일관되게 따르기를 원하는 개발자 - 반복 업무를 자동화하려는 파워 유저 - 조직 전체에서 Claude의 작업 방식을 표준화하려는 팀 ## 읽는 방법 ### 독립형 스킬을 만들 경우 다음 부분에 집중합니다. - Chapter 1. 기본 개념 - Chapter 2. 계획 및 설계 - 문서·에셋 생성 - 워크플로우 자동화 ### MCP 통합을 강화할 경우 다음 부분이 중요합니다. - 스킬 + MCP - MCP 강화 카테고리 - 멀티 MCP 조율 - MCP 연결 트러블슈팅 > PDF에서는 `skill-creator`를 활용하면 첫 번째 작동 스킬을 약 **15~30분** 안에 구축하고 테스트할 수 있다고 설명합니다. --- # Chapter 1. 기본 개념 ## 1. 스킬의 기본 구조 스킬은 하나의 폴더이며, 기본적으로 다음 구조를 가집니다. ```text your-skill-name/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/ ``` 각 요소의 역할은 다음과 같습니다. | 요소 | 필수 여부 | 역할 | |---|---:|---| | `SKILL.md` | 필수 | YAML 프론트매터와 실제 작업 지침을 담는 핵심 파일 | | `scripts/` | 선택 | Python, Bash 등의 실행 가능한 코드 | | `references/` | 선택 | 필요할 때 불러오는 문서와 예시 | | `assets/` | 선택 | 템플릿, 폰트, 아이콘 등 출력물에 사용하는 리소스 | --- ## 2. 핵심 설계 원칙 ### 2.1 점진적 공개(Progressive Disclosure) 스킬은 모든 정보를 한 번에 컨텍스트에 넣지 않고 **필요한 만큼 단계적으로 불러오는 구조**를 사용합니다. #### 1단계 — YAML 프론트매터 항상 Claude의 시스템 프롬프트에 노출되는 최소 정보입니다. 핵심 목적은 다음 질문에 답하는 것입니다. > **“이 스킬을 언제 사용해야 하는가?”** 즉, 전체 내용을 로드하지 않아도 Claude가 스킬의 사용 시점을 판단할 수 있어야 합니다. #### 2단계 — `SKILL.md` 본문 현재 작업에 해당 스킬이 관련 있다고 판단되면 본문이 로드됩니다. 여기에는 다음이 들어갑니다. - 전체 작업 절차 - 단계별 명령어 - 규칙 - 예시 - 검증 방법 - 트러블슈팅 #### 3단계 — 연결된 추가 파일 스킬 폴더 안의 다음 파일은 필요한 경우에만 선택적으로 탐색합니다. - `references/` - `scripts/` - `assets/` ### 점진적 공개의 장점 - 토큰 사용량 감소 - 컨텍스트 과부하 방지 - 전문화된 기능 유지 - 대형 스킬의 효율 향상 --- ### 2.2 조합 가능성(Composability) Claude는 여러 스킬을 동시에 사용할 수 있습니다. 따라서 스킬은 다른 스킬을 방해하는 독립적인 거대 명령 집합보다는, **다른 스킬과 조합될 수 있도록 설계**하는 것이 좋습니다. --- ### 2.3 이식성(Portability) 스킬은 다음 환경에서 동일한 개념으로 작동하도록 설계됩니다. - Claude.ai - Claude Code - API 환경이 스킬의 의존성을 지원한다면, 한 번 만든 스킬을 여러 환경에서 활용할 수 있습니다. --- # 스킬 + MCP ## MCP와 스킬의 차이 PDF에서는 이를 **전문 주방**에 비유합니다. - **MCP = 주방** - 도구 - 재료 - 장비 - 외부 서비스 접근 - **스킬 = 레시피** - 어떤 순서로 - 어떤 규칙에 따라 - 어떤 기준으로 - 도구를 사용해야 하는지 설명 즉, > **MCP는 Claude가 “무엇을 할 수 있는지” 확장하고, 스킬은 “어떻게 해야 하는지” 가르칩니다.** | MCP | 스킬 | |---|---| | 연결성 제공 | 지식과 절차 제공 | | Notion, Asana, Linear 등 서비스 연결 | 서비스를 효과적으로 사용하는 방법 정의 | | 실시간 데이터 접근 | 워크플로우와 모범 사례 제공 | | 도구 실행 | 도구 사용 순서와 판단 기준 제공 | | Claude가 할 수 있는 것 | Claude가 해야 하는 방법 | --- ## 스킬이 없을 때 - MCP는 연결되어 있지만 다음 행동을 판단하기 어려움 - 사용자가 매번 “어떻게 해야 하나요?”라고 물어야 함 - 대화가 매번 처음부터 시작 - 사람마다 프롬프트가 달라 결과가 불일치 ## 스킬이 있을 때 - 필요할 때 사전 구축된 워크플로우가 활성화 - 도구 사용 방식이 일관됨 - 모범 사례가 작업 과정에 내재화 - 사용자의 학습 부담 감소 --- # Chapter 2. 계획 및 설계 ## 1. 활용 사례부터 정의하기 코드를 작성하기 전에 스킬이 지원해야 할 **구체적인 활용 사례 2~3개**를 먼저 정합니다. ### 예시 — 프로젝트 스프린트 계획 **트리거** > “이번 스프린트 계획 도와줘” > “스프린트 작업 만들어줘” **워크플로우** 1. MCP를 통해 Linear의 현재 프로젝트 상태 가져오기 2. 팀 속도와 역량 분석 3. 작업 우선순위 제안 4. 라벨과 예상 시간이 포함된 작업 생성 **결과** - 실행 가능한 완전한 스프린트 계획 생성 ### 설계 전에 답해야 할 질문 - 사용자가 실제로 달성하려는 것은 무엇인가? - 어떤 다단계 워크플로우가 필요한가? - 어떤 도구가 필요한가? - 내장 기능만으로 가능한가? - MCP가 필요한가? - 어떤 도메인 지식을 포함해야 하는가? - 어떤 모범 사례를 자동화해야 하는가? --- ## 2. 대표적인 스킬 활용 사례 3가지 ### 카테고리 1 — 문서 및 에셋 생성 #### 용도 - 문서 - 프레젠테이션 - 앱 - 디자인 - 코드 - 기타 고품질 산출물 생성 #### 핵심 기법 - 스타일 가이드 내장 - 브랜드 기준 내장 - 반복 가능한 템플릿 구조 - 완료 전 품질 체크리스트 - Claude의 내장 기능 활용 #### 예시 `frontend-design` 스킬처럼 사양서를 기반으로 높은 디자인 품질의 인터페이스나 웹 컴포넌트를 생성하는 방식입니다. --- ### 카테고리 2 — 워크플로우 자동화 #### 용도 일관된 방법론이 필요한 다단계 업무를 처리합니다. #### 핵심 기법 - 단계별 워크플로우 - 검증 게이트 - 공통 구조 템플릿 - 자체 검토 - 개선 제안 - 반복 정제 루프 #### 예시 `skill-creator` - 활용 사례 정의 - 프론트매터 생성 - 명령어 작성 - 검증 - 반복 개선 --- ### 카테고리 3 — MCP 강화 #### 용도 MCP 서버가 제공하는 “도구 접근” 위에 실제 업무 지식과 워크플로우를 추가합니다. #### 핵심 기법 - 여러 MCP 호출 순서 조율 - 도메인 전문 지식 내장 - 필요한 맥락 자동 제공 - MCP 오류 처리 #### 예시 `sentry-code-review` - Sentry MCP의 에러 모니터링 데이터를 사용 - GitHub PR에서 감지된 버그 분석 - 수정 과정 자동화 --- ## 3. 성공 기준 정의 스킬이 “잘 작동한다”는 것을 사전에 정의해야 합니다. ### 정량적 지표 #### 트리거 성공률 관련 쿼리의 약 90%에서 스킬이 자동으로 트리거되는지 확인합니다. 권장 방식: - 10~20개의 테스트 쿼리 작성 - 스킬이 실제로 로드되는 비율 측정 #### 도구 호출 수 스킬 사용 전후를 비교합니다. 예: - 필요한 도구 호출 횟수 - 토큰 소비량 - 반복 질문 수 #### API 실패율 목표 예: - 워크플로우당 API 호출 실패 0건 확인 항목: - 재시도율 - MCP 서버 로그 - 오류 코드 --- ### 정성적 지표 - 사용자가 다음 단계를 직접 설명하지 않아도 되는가? - 같은 요청을 여러 번 실행해도 결과가 일관적인가? - 사용자 수정 없이 완료되는가? - 처음 사용하는 사용자도 최소한의 설명으로 성공할 수 있는가? --- # 기술적 요구사항 ## 1. 권장 파일 구조 ```text your-skill-name/ ├── SKILL.md # 필수 ├── scripts/ # 선택 │ ├── process_data.py │ └── validate.sh ├── references/ # 선택 │ ├── api-guide.md │ └── examples/ └── assets/ # 선택 └── report-template.md ``` --- ## 2. 필수 규칙 ### `SKILL.md` 파일명은 반드시 정확히 다음과 같아야 합니다. ```text SKILL.md ``` 허용되지 않는 예: ```text SKILL.MD skill.md Skill.md ``` > 대소문자를 구분합니다. --- ### 스킬 폴더 이름 반드시 **kebab-case**를 사용합니다. ✅ 올바른 예 ```text notion-project-setup ``` ❌ 잘못된 예 ```text Notion Project Setup notion_project_setup NotionProjectSetup ``` --- ### 스킬 폴더 내부 `README.md` 스킬 폴더에는 별도의 `README.md`를 넣지 않는 것을 권장합니다. 스킬 자체의 문서는 다음 위치에 작성합니다. - `SKILL.md` - `references/` GitHub에 공개하는 경우에는 **레포지토리 수준의 README**를 별도로 둘 수 있습니다. --- # YAML 프론트매터 ## 1. 최소 형식 ```yaml --- name: your-skill-name description: 이 스킬이 무엇을 합니다. 사용자가 [특정 문구]를 말할 때 사용하세요. --- ``` 스킬은 이 최소 구조만으로도 시작할 수 있습니다. --- ## 2. `name` 필수 조건: - kebab-case - 공백 없음 - 대문자 없음 - 스킬 폴더 이름과 동일 --- ## 3. `description` `description`은 스킬의 자동 트리거 여부를 결정하는 핵심 요소입니다. 반드시 다음 두 요소가 들어가야 합니다. 1. **무엇을 하는가** 2. **언제 사용하는가** 추가 요구사항: - 1024자 이하 - XML 꺾쇠괄호 사용 금지 - 실제 사용자가 말할 수 있는 작업 표현 포함 - 관련 있다면 파일 유형 포함 ### 권장 구조 ```text [무엇을 하는지] + [언제 사용하는지] + [핵심 기능] ``` --- ## 4. 좋은 `description` 예시 ### Figma 관련 ```yaml description: Figma 디자인 파일을 분석하고 개발자 핸드오프 문서를 생성합니다. 사용자가 .fig 파일을 업로드하거나, "디자인 스펙", "컴포넌트 문서", "디자인-코드 핸드오프"를 요청할 때 사용하세요. ``` ### 프로젝트 관리 관련 ```yaml description: 스프린트 계획, 작업 생성, 상태 추적 등 Linear 프로젝트 워크플로우를 관리합니다. 사용자가 "스프린트", "Linear 작업", "프로젝트 계획"을 언급하거나 "티켓 만들어줘"라고 할 때 사용하세요. ``` --- ## 5. 나쁜 `description` ### 너무 모호함 ```yaml description: 프로젝트를 도와줍니다. ``` ### 사용 시점이 없음 ```yaml description: 정교한 다중 페이지 문서 시스템을 생성합니다. ``` --- ## 6. 선택 필드 ### `license` 오픈소스로 배포할 경우 사용합니다. ```yaml license: MIT ``` ### `compatibility` 환경 요구사항을 설명합니다. ### `metadata` 사용자 정의 정보를 저장합니다. 예: ```yaml metadata: author: 회사명 version: 1.0.0 mcp-server: server-name ``` --- ## 7. 보안 제한 프론트매터에서 피해야 하는 항목: - XML 꺾쇠괄호 `< >` - 스킬 이름에 `claude` - 스킬 이름에 `anthropic` 프론트매터는 시스템 프롬프트에 노출되므로, 보안상 안전한 형태로 작성해야 합니다. --- # 효과적인 `SKILL.md` 작성 ## 권장 기본 구조 ```markdown --- name: your-skill description: [무엇을 하며 언제 사용하는지 설명] --- # 스킬 이름 ## 1단계: 첫 번째 주요 단계 단계에 대한 명확한 설명 ## 2단계: 다음 단계 구체적인 실행 방법 ## 예시 사용자 말: "새 마케팅 캠페인 설정해줘" 실행 액션: 1. MCP로 기존 캠페인 가져오기 2. 새 캠페인 생성 ## 트러블슈팅 오류: [일반적인 오류 메시지] 원인: [오류가 발생하는 이유] 해결: [수정 방법] ``` --- ## 명령어 작성 원칙 ### 구체적이고 실행 가능하게 작성 ✅ 좋은 예 ```markdown 데이터 형식을 확인하려면 다음 명령을 실행하세요. `python scripts/validate.py --input {filename}` 검증 실패 시 확인: - 필수 필드 누락 - 날짜 형식이 YYYY-MM-DD인지 확인 ``` ❌ 나쁜 예 ```markdown 계속 진행하기 전에 데이터를 검증하세요. ``` “검증하세요”라는 말만 쓰는 것이 아니라 **무엇으로, 어떻게, 어떤 조건을 확인하는지** 명확히 적는 것이 중요합니다. --- ## 오류 처리 포함 ```markdown ## 자주 발생하는 오류 ### MCP 연결 실패 "Connection refused"가 표시되면: 1. MCP 서버가 실행 중인지 확인 2. API 키가 유효한지 확인 3. 확장 프로그램에서 서비스 재연결 ``` --- # Chapter 3. 테스트와 반복 개선 ## 1. 테스트 수준 스킬의 중요도와 사용 범위에 따라 테스트 수준을 선택합니다. ### Claude.ai 수동 테스트 - 쿼리를 직접 실행 - 빠른 반복 - 별도 설정이 거의 필요 없음 ### Claude Code 스크립트 테스트 - 테스트 케이스 자동화 - 변경 전후 비교 - 반복 가능한 검증 ### Skills API 프로그래매틱 테스트 - 정의된 테스트 세트 - 체계적인 평가 - 대규모 또는 프로덕션 환경에 적합 --- ## 2. 먼저 하나의 어려운 작업을 성공시키기 가이드가 권장하는 방식은 처음부터 모든 경우를 처리하려 하지 않고: 1. 하나의 어려운 작업 선정 2. Claude가 성공할 때까지 반복 개선 3. 성공한 작업 절차를 스킬로 추출 4. 이후 범위를 확장 하는 것입니다. --- ## 3. 권장 테스트 3종 ### 3.1 트리거 테스트 **목표:** 올바른 순간에 스킬이 로드되는지 확인 #### 트리거되어야 하는 예 ```text "새 ProjectHub 워크스페이스 설정해줘" "ProjectHub에서 프로젝트 만들어야 해" "Q4 계획을 위한 ProjectHub 프로젝트 초기화해줘" ``` #### 트리거되면 안 되는 예 ```text "샌프란시스코 날씨 어때?" "Python 코드 작성 도와줘" "스프레드시트 만들어줘" ``` --- ### 3.2 기능 테스트 **목표:** 스킬이 올바른 결과물을 생성하는지 확인 검증 항목: - 유효한 결과물 생성 - API 호출 성공 - 오류 처리 - 엣지 케이스 처리 #### 예시 **테스트** > 5개 작업이 있는 `Q4 Planning` 프로젝트 생성 **기대 결과** - ProjectHub 프로젝트 생성 - 올바른 속성의 작업 5개 생성 - 모든 작업이 프로젝트에 연결 - API 오류 없음 --- ### 3.3 성능 비교 **목표:** 스킬을 사용했을 때 실제로 더 효율적인지 확인 #### 스킬 없을 때 - 매번 사용자가 명령 제공 - 질문·응답 15회 - API 호출 실패 3건 - 토큰 12,000개 사용 #### 스킬 있을 때 - 자동 워크플로우 실행 - 명확화 질문 2개 - API 호출 실패 0건 - 토큰 6,000개 사용 --- # `skill-creator` 활용 `skill-creator`는 스킬을 만들고 개선하는 작업을 지원합니다. ## 스킬 생성 - 자연어 설명으로 스킬 생성 - 올바른 `SKILL.md` 형식 작성 - 프론트매터 생성 - 트리거 문구 제안 - 구조 제안 ## 스킬 검토 - 모호한 설명 탐지 - 누락된 트리거 탐지 - 구조 문제 확인 - 과도한 트리거 가능성 확인 - 부족한 트리거 가능성 확인 - 테스트 케이스 제안 ## 반복 개선 실제 사용 중 문제가 발생하면 해당 실패 사례를 다시 입력해 개선합니다. 예: ```text 이 대화에서 발견된 문제와 해결책을 활용해 스킬이 [특정 엣지 케이스]를 처리하는 방식을 개선해줘. ``` ### 사용 예 ```text skill-creator 스킬을 사용해 [활용 사례]를 위한 스킬 만드는 것을 도와줘. ``` > `skill-creator`는 설계와 개선을 지원하지만, 자동화 테스트 스위트 실행이나 정량 평가 결과를 자동 생성하는 도구는 아니라는 점이 PDF에 명시되어 있습니다. --- # 피드백 기반 반복 개선 스킬은 완성 후 끝나는 문서가 아니라 **계속 수정되는 살아 있는 문서**로 관리합니다. ## 트리거 부족 신호 - 필요할 때 스킬이 로드되지 않음 - 사용자가 매번 수동으로 활성화 - “언제 이 스킬을 쓰나요?”라는 질문이 자주 발생 ### 해결 `description`에 다음을 추가합니다. - 더 구체적인 작업 표현 - 실제 사용자가 말할 키워드 - 파일 유형 - 명확한 트리거 문구 --- ## 트리거 과잉 신호 - 관련 없는 요청에도 스킬이 로드 - 사용자가 스킬을 비활성화 - 스킬의 목적이 불명확 ### 해결 - 더 구체적인 설명 작성 - 부정적 트리거 추가 --- ## 실행 문제 - 결과가 매번 다름 - API 호출 실패 - 사용자 수정이 반복적으로 필요 ### 해결 - 명령어 구체화 - 검증 단계 강화 - 오류 처리 추가 --- # Chapter 4. 배포 및 공유 ## 1. 개인 사용자의 설치 흐름 PDF의 2026년 기준 설명: 1. 스킬 폴더 다운로드 2. 필요하면 압축 3. Claude.ai 설정의 스킬 관련 메뉴에서 업로드 4. 또는 Claude Code 스킬 디렉터리에 배치 --- ## 2. 조직 수준 배포 조직에서는 다음 방식이 가능합니다. - 관리자 중심 배포 - 자동 업데이트 - 중앙집중식 관리 --- ## 3. 오픈 표준 Agent Skills는 특정 도구 하나에 종속되기보다는 **도구와 플랫폼 사이에서 이식 가능한 형태**를 지향합니다. 특정 플랫폼 기능에 의존한다면 `compatibility` 필드에 요구사항을 명시할 수 있습니다. --- ## 4. API를 통한 스킬 사용 프로그래매틱 애플리케이션이나 에이전트 시스템에서는 API를 사용합니다. PDF에서 언급한 주요 기능: - `/v1/skills` 엔드포인트를 통한 스킬 목록 및 관리 - `container.skills` 매개변수를 통한 Messages API 요청에 스킬 추가 - Claude Console을 통한 버전 관리 - Claude Agent SDK와 연동 --- ## 5. Claude.ai / Claude Code / API 선택 기준 | 활용 사례 | 적합한 플랫폼 | |---|---| | 최종 사용자가 스킬과 직접 상호작용 | Claude.ai / Claude Code | | 개발 중 수동 테스트와 반복 | Claude.ai / Claude Code | | 개인적·임시 워크플로우 | Claude.ai / Claude Code | | 스킬을 사용하는 애플리케이션 | API | | 대규모 프로덕션 배포 | API | | 자동화 파이프라인·에이전트 시스템 | API | --- ## 6. GitHub 배포 권장 방식 1. 공개 레포지토리에 스킬 호스팅 2. 레포지토리 수준의 명확한 README 작성 3. 사용 예시 스크린샷 추가 4. MCP 문서에서 스킬 링크 제공 5. MCP + 스킬을 함께 사용할 때의 장점 설명 6. 빠른 시작 가이드 제공 --- ## 7. 설치 가이드 예시 ```markdown # [서비스명] 스킬 설치 방법 ## 1. 스킬 다운로드 - 레포 클론 `git clone https://github.com/yourcompany/skills` - 또는 Releases에서 ZIP 다운로드 ## 2. Claude에 설치 - Claude.ai의 스킬 메뉴 열기 - "스킬 업로드" 선택 - 스킬 폴더 또는 압축 파일 선택 ## 3. 스킬 활성화 - [서비스명] 스킬 활성화 - 필요한 경우 MCP 서버 연결 상태 확인 ## 4. 테스트 Claude에게 요청: "[서비스명]에서 새 프로젝트 설정해줘" ``` --- ## 8. 스킬 포지셔닝 스킬을 소개할 때는 **기술 구조보다 사용자 성과**를 설명하는 것이 좋습니다. ✅ 좋은 표현 > ProjectHub 스킬을 사용하면 페이지, 데이터베이스, 템플릿을 포함한 프로젝트 워크스페이스를 수동으로 30분 동안 설정하는 대신 몇 초 안에 구축할 수 있습니다. ❌ 나쁜 표현 > YAML 프론트매터와 Markdown 명령어로 구성된 폴더이며 MCP 서버의 도구를 호출합니다. 핵심은: > **기능이 아니라 결과를 설명하는 것** 입니다. --- # Chapter 5. 패턴과 트러블슈팅 ## 1. 문제 우선 vs. 도구 우선 ### 문제 우선 사용자가 원하는 결과를 먼저 말합니다. ```text "프로젝트 워크스페이스를 설정해야 해." ``` 스킬이 적절한 도구와 순서를 선택합니다. ### 도구 우선 사용자가 이미 도구를 연결했습니다. ```text "Notion MCP를 연결했어." ``` 스킬이 그 도구를 효과적으로 사용하는 방법을 Claude에게 제공합니다. --- # 패턴 1. 순차적 워크플로우 조율 ## 언제 사용? 작업이 반드시 특정 순서로 진행되어야 할 때 ### 예시 — 새 고객 온보딩 ```markdown ## 1단계: 계정 생성 MCP 도구: create_customer 매개변수: - name - email - company ## 2단계: 결제 설정 MCP 도구: setup_payment_method 대기: 결제 수단 인증 ## 3단계: 구독 생성 MCP 도구: create_subscription 매개변수: - plan_id - customer_id ## 4단계: 환영 이메일 발송 MCP 도구: send_email 템플릿: welcome_email_template ``` ### 핵심 - 명확한 순서 - 단계 간 의존성 - 각 단계 검증 - 실패 시 롤백 지침 --- # 패턴 2. 멀티 MCP 조율 ## 언제 사용? 하나의 워크플로우가 여러 서비스에 걸쳐 있을 때 ### 예시 — 디자인 → 개발 핸드오프 #### Phase 1 — Figma MCP 1. 디자인 에셋 내보내기 2. 디자인 사양서 생성 3. 에셋 매니페스트 생성 #### Phase 2 — Drive MCP 1. 프로젝트 폴더 생성 2. 에셋 업로드 3. 공유 링크 생성 #### Phase 3 — Linear MCP 1. 개발 작업 생성 2. 작업에 에셋 링크 첨부 3. 엔지니어링 팀에 할당 #### Phase 4 — Slack MCP 1. `#engineering` 채널에 요약 게시 2. 에셋 링크와 작업 참조 포함 --- # 패턴 3. 반복적 정제 ## 언제 사용? 첫 결과물보다 **검토 → 수정 → 재검증**을 반복할수록 품질이 좋아지는 작업 ### 예시 — 보고서 생성 #### 초안 1. MCP로 데이터 가져오기 2. 첫 보고서 생성 3. 임시 파일 저장 #### 품질 점검 1. `scripts/check_report.py` 실행 2. 문제 확인 - 누락 섹션 - 일관성 없는 포맷 - 데이터 오류 #### 정제 루프 1. 각 문제 수정 2. 해당 섹션 재생성 3. 재검증 4. 품질 기준을 만족할 때까지 반복 #### 최종화 1. 최종 포맷 적용 2. 요약 생성 3. 최종 버전 저장 --- # 패턴 4. 컨텍스트 인식 도구 선택 ## 언제 사용? 같은 목적을 달성하더라도 상황에 따라 다른 도구를 선택해야 할 때 ### 예시 — 스마트 파일 저장 ```text 1. 파일 유형과 크기 확인 2. 저장 위치 결정 - 10MB 초과 대용량 파일 → 클라우드 스토리지 MCP - 협업 문서 → Notion / Docs MCP - 코드 파일 → GitHub MCP - 임시 파일 → 로컬 저장소 ``` 저장 후에는: - 적절한 MCP 도구 호출 - 서비스별 메타데이터 적용 - 접근 링크 생성 - 왜 해당 저장소를 선택했는지 사용자에게 설명 --- # 패턴 5. 도메인 특화 인텔리전스 ## 언제 사용? 단순 도구 실행을 넘어 **업무 규칙·전문 지식·검증 기준**을 적용해야 할 때 ### 예시 — 컴플라이언스가 포함된 결제 처리 #### 처리 전 검사 1. MCP로 트랜잭션 세부 정보 가져오기 2. 컴플라이언스 규정 적용 - 제재 목록 확인 - 관할권 허용 여부 - 리스크 수준 평가 3. 결정 문서화 #### 처리 **통과 시** - MCP 도구 호출 - 사기 검사 - 트랜잭션 처리 **미통과 시** - 검토 대상으로 플래그 - 컴플라이언스 케이스 생성 #### 감사 추적 - 검사 기록 - 처리 결정 기록 - 감사 보고서 생성 --- # 트러블슈팅 ## 1. 스킬이 업로드되지 않음 ### 오류 ```text 업로드된 폴더에서 SKILL.md를 찾을 수 없습니다 ``` ### 원인 파일명이 정확하지 않음 ### 해결 ```text SKILL.md ``` 로 정확하게 변경합니다. --- ## 2. 잘못된 프론트매터 ### 잘못된 예 ```yaml name: my-skill description: 기능을 수행합니다 ``` ### 올바른 예 ```yaml --- name: my-skill description: 기능을 수행합니다 --- ``` --- ## 3. 잘못된 스킬 이름 ❌ 잘못된 예 ```yaml name: My Cool Skill ``` ✅ 올바른 예 ```yaml name: my-cool-skill ``` --- ## 4. 스킬이 자동 트리거되지 않음 ### 확인할 것 - `description`이 너무 일반적이지 않은가? - 사용자가 실제로 입력할 문구가 있는가? - 파일 유형이 중요한 경우 명시했는가? - “언제 사용하는가”가 들어 있는가? ### 디버깅 방법 Claude에게 다음처럼 질문합니다. ```text "[스킬 이름] 스킬을 언제 사용하나요?" ``` Claude가 `description` 내용을 바탕으로 답하므로 부족한 부분을 확인할 수 있습니다. --- ## 5. 스킬이 너무 자주 트리거됨 ### 해결책 1 — 부정적 트리거 ```yaml description: CSV 파일의 고급 데이터 분석용. 통계 모델링, 회귀, 클러스터링에 사용하세요. 단순한 데이터 탐색에는 사용하지 마세요. ``` ### 해결책 2 — 범위를 좁히기 ❌ 너무 광범위 ```yaml description: 문서를 처리합니다. ``` ✅ 구체적 ```yaml description: 계약서 검토를 위한 PDF 법률 문서를 처리합니다. ``` --- ## 6. MCP 연결 문제 ### 증상 스킬은 로드되지만 MCP 도구 호출이 실패 ### 체크리스트 1. MCP 서버가 연결 상태인지 확인 2. API 키가 유효한지 확인 3. 권한과 Scope 확인 4. OAuth 토큰 갱신 확인 5. MCP를 스킬 없이 직접 테스트 6. 스킬에 적힌 MCP 도구 이름 확인 7. 도구 이름의 대소문자 확인 --- ## 7. Claude가 명령어를 제대로 따르지 않음 ### 원인 - 명령어가 너무 장황함 - 중요한 규칙이 문서 깊숙이 묻혀 있음 - 표현이 모호함 ### 해결 - 짧고 명확한 문장 사용 - 번호 목록과 글머리표 사용 - 중요한 규칙을 상단에 배치 - `## 중요`, `## 필수` 등의 헤더 사용 - 세부 내용은 `references/`로 이동 ❌ 나쁜 예 ```text 항목들을 제대로 검증하세요. ``` ✅ 좋은 예 ```markdown 필수: create_project 호출 전 반드시 다음을 확인: - 프로젝트 이름이 비어 있지 않음 - 최소 한 명의 팀원이 할당됨 - 시작 날짜가 과거가 아님 ``` --- ## 8. 모델이 검증 과정을 건너뛰는 경우 PDF에서는 중요한 작업일수록 다음과 같이 명시적으로 품질 기준을 강조하는 방법을 제시합니다. ```markdown ## 성능 참고 - 이 작업을 철저하게 수행하세요. - 속도보다 품질이 중요합니다. - 검증 단계를 건너뛰지 마세요. ``` --- ## 9. 대용량 컨텍스트 문제 ### 증상 - 스킬이 느림 - 응답 품질 저하 ### 원인 - `SKILL.md`가 지나치게 큼 - 너무 많은 스킬이 동시에 활성화 - 점진적 공개 없이 모든 콘텐츠를 한 번에 로드 ### 해결 - 상세 문서를 `references/`로 이동 - `SKILL.md`는 **5,000단어 이하**로 유지하는 방향 권장 - 동시에 활성화된 스킬이 **20~50개 이상**이면 정리 검토 - 관련 스킬을 하나의 “스킬 팩”으로 묶는 방식 고려 --- # Chapter 6. 리소스 및 참고자료 ## 공식 문서 PDF에서는 다음 Anthropic 자료를 참고 리소스로 제시합니다. - 모범 사례 가이드 - 스킬 문서 - API 레퍼런스 - MCP 문서 ## 관련 블로그 주제 - 에이전트 스킬 소개 - 에이전트를 실전에 맞게 준비하기 - 스킬 설명 - Claude 스킬을 만드는 방법 - 스킬을 통한 프론트엔드 디자인 개선 ## 예시 스킬 공개 스킬 레포지토리: ```text anthropics/skills ``` 여기에는 커스터마이즈 가능한 Anthropic 제작 스킬 예시가 포함되어 있다고 안내합니다. --- ## skill-creator 기능: - 설명으로부터 스킬 생성 - 스킬 검토 - 개선 사항 제안 사용 예: ```text skill-creator를 활용해 스킬 구축하는 것을 도와줘. ``` 검토 예: ```text 이 스킬을 검토하고 개선사항을 제안해줘. ``` --- ## 지원 채널 ### 일반적인 기술 질문 - Claude Developers Discord 커뮤니티 포럼 ### 버그 리포트 - `anthropics/skills/issues` 버그를 보고할 때 포함할 정보: - 스킬 이름 - 오류 메시지 - 재현 단계 --- # 부록 A. 빠른 체크리스트 ## 시작 전 - [ ] 구체적인 활용 사례 2~3개 정의 - [ ] 사용할 도구 확인 - [ ] 내장 기능인지 MCP인지 결정 - [ ] 관련 예시 스킬 검토 - [ ] 폴더 구조 설계 --- ## 개발 중 - [ ] 폴더 이름이 kebab-case - [ ] `SKILL.md`가 정확한 파일명으로 존재 - [ ] YAML 프론트매터에 `---` 구분자 존재 - [ ] `name`은 kebab-case - [ ] `name`에 공백 없음 - [ ] `name`에 대문자 없음 - [ ] `description`에 “무엇을” 포함 - [ ] `description`에 “언제” 포함 - [ ] XML 태그 없음 - [ ] 명령어가 구체적이고 실행 가능 - [ ] 오류 처리 포함 - [ ] 사용 예시 포함 - [ ] 참조 파일 연결이 명확함 --- ## 업로드 전 - [ ] 명확한 요청에서 트리거되는지 테스트 - [ ] 다른 표현의 요청에서도 트리거되는지 테스트 - [ ] 관련 없는 요청에서는 트리거되지 않는지 확인 - [ ] 기능 테스트 통과 - [ ] 도구 연동 확인 - [ ] 필요한 경우 ZIP 압축 --- ## 업로드 후 - [ ] 실제 대화에서 테스트 - [ ] 트리거 부족 여부 확인 - [ ] 트리거 과잉 여부 확인 - [ ] 사용자 피드백 수집 - [ ] `description` 반복 개선 - [ ] 명령어 반복 개선 - [ ] 메타데이터 버전 업데이트 --- # 부록 B. YAML 프론트매터 참고 ## 최소 필수 필드 ```yaml --- name: skill-name-in-kebab-case description: 무엇을 하며 언제 사용하는지 설명합니다. 구체적인 트리거 문구를 포함하세요. --- ``` --- ## 선택 필드를 포함한 예시 ```yaml --- name: skill-name description: [필수 설명] license: MIT allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" metadata: author: 회사명 version: 1.0.0 mcp-server: server-name category: productivity tags: - project-management - automation documentation: https://example.com/docs support: support@example.com --- ``` --- ## 보안 참고 ### 허용 - 문자열 - 숫자 - 불리언 - 목록 - 객체 - 커스텀 메타데이터 - 최대 1024자의 `description` ### 금지 또는 제한 - XML 꺾쇠괄호 `< >` - YAML에서의 코드 실행 - `claude` 또는 `anthropic`이 포함된 예약된 형태의 스킬 이름 --- # 부록 C. 완전한 스킬 예시 안내 PDF에서는 완전한 프로덕션 수준의 예시를 별도 레포지토리에서 확인하도록 안내합니다. 예시 범주: - PDF 생성 스킬 - DOCX 생성 스킬 - PPTX 생성 스킬 - XLSX 생성 스킬 - 다양한 워크플로우 예시 스킬 - 파트너 스킬 파트너 예시: - Asana - Atlassian - Canva - Figma - Sentry - Zapier 이 레포지토리들은 가이드의 기본 패턴을 넘어서는 추가 예시를 제공하며, 필요에 따라 클론하거나 수정해 활용할 수 있다고 설명합니다. --- # 실전용 최소 스킬 템플릿 아래는 PDF 본문에 제시된 프론트매터, 단계 구조, 예시, 트러블슈팅 원칙을 하나의 형태로 정리한 템플릿입니다. ```markdown --- name: my-workflow-skill description: [무엇을 하는지]를 처리합니다. 사용자가 "[트리거 문구 1]", "[트리거 문구 2]"를 말하거나 [특정 파일/작업]을 요청할 때 사용하세요. --- # My Workflow Skill ## 중요 - 작업 순서를 반드시 지킵니다. - 각 단계가 완료되었는지 검증한 후 다음 단계로 진행합니다. - 검증 단계를 건너뛰지 않습니다. ## 1단계: 입력 확인 1. 사용자 입력 확인 2. 필요한 파일 확인 3. 필수 정보 누락 여부 확인 ## 2단계: 작업 실행 1. 필요한 도구 호출 2. 결과 저장 3. 오류 여부 확인 ## 3단계: 검증 다음을 확인합니다. - 필수 결과물이 모두 생성되었는가? - 형식이 올바른가? - API 또는 MCP 오류가 없는가? ## 4단계: 결과 제공 - 최종 결과 요약 - 생성된 파일 또는 링크 제공 - 필요한 경우 다음 행동 안내 ## 예시 사용자: "[실제 사용자가 말할 가능성이 높은 요청]" 처리: 1. ... 2. ... 3. ... ## 트러블슈팅 ### 오류: [오류 메시지] 원인: - ... 해결: 1. ... 2. ... 3. ... ``` --- # 핵심 요약 Claude 스킬을 잘 만들기 위해 가장 중요한 원칙은 다음과 같습니다. 1. **먼저 2~3개의 실제 활용 사례를 정의한다.** 2. **`description`에 “무엇을 하는지 + 언제 사용하는지”를 명확하게 쓴다.** 3. **`SKILL.md`는 짧고 실행 가능한 지침 중심으로 작성한다.** 4. **세부 자료는 `references/`로 분리해 점진적 공개를 활용한다.** 5. **MCP는 도구이고, 스킬은 그 도구를 사용하는 업무 레시피다.** 6. **트리거 테스트·기능 테스트·성능 비교를 수행한다.** 7. **실제 실패 사례를 기반으로 계속 수정한다.** 8. **도구 호출 전후에 검증 조건을 명시한다.** 9. **관련 없는 요청에 과도하게 트리거되지 않도록 범위를 좁힌다.** 10. **사용자에게 스킬을 설명할 때는 기술 구조보다 결과와 이점을 강조한다.** > 좋은 스킬은 단순히 긴 프롬프트를 저장한 것이 아니라, > **반복 가능한 작업 절차 + 판단 기준 + 도구 사용법 + 검증 방식 + 오류 처리**를 하나의 재사용 가능한 패키지로 만든 것입니다.