Claude Skills 완벽 가이드

https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
의 내용을 한글로 번역한 내용입니다.

목차

• 소개
• 1장. 기본 개념
• 2장. 계획 및 설계
• 3장. 테스트 및 반복
• 4장. 배포 및 공유
• 5장. 패턴 및 문제 해결
• 6장. 리소스 및 참고 자료

---

소개

**Skill(스킬)**은 Claude가 특정 작업을 일관되게 처리하게 만드는 지침 폴더다. 매 대화마다 선호사항과 절차를 다시 설명하지 않아도 되고, 팀 방식도 안정적으로 재사용할 수 있다.

스킬이 특히 유용한 경우

• 스펙에서 프론트엔드 디자인 생성
• 일관된 방법으로 연구 진행
• 팀의 스타일 가이드를 따르는 문서 생성
• 다단계 프로세스 조정

이 가이드에서 배울 내용

• 스킬 구조를 위한 기술 요구사항 및 모범 사례
• 독립형 스킬 및 MCP 강화 워크플로우 패턴
• 여러 사용 사례에서 재사용하기 좋은 패턴
• 스킬을 테스트, 반복, 배포하는 방법

이 가이드의 대상

• Claude가 특정 워크플로우를 일관되게 따르도록 하려는 개발자
• Claude가 특정 워크플로우를 따르도록 하려는 파워 유저
• 조직 전체에서 Claude의 작동 방식을 표준화하려는 팀

가이드 활용법

• 독립형 스킬 구축: 기본 개념, 계획 및 설계, 카테고리 1-2에 집중
• MCP 통합 강화: "Skills + MCP" 섹션과 카테고리 3 참조

---

1장. 기본 개념

스킬이란 무엇인가?

스킬은 다음을 포함하는 폴더입니다:

복사
your-skill-name/
├── SKILL.md          # 필수 - YAML frontmatter가 포함된 Markdown 지침
├── scripts/          # 선택 사항 - 실행 가능한 코드 (Python, Bash 등)
│   ├── process_data.py
│   └── validate.sh
├── references/       # 선택 사항 - 필요 시 로드되는 문서
│   ├── api-guide.md
│   └── examples/
└── assets/           # 선택 사항 - 출력에 사용되는 템플릿, 폰트, 아이콘
    └── report-template.md

핵심 설계 원칙

1. 점진적 공개 (Progressive Disclosure)

스킬은 3단계로 로드된다.

이 구조를 쓰면 필요한 내용만 읽어서 토큰 낭비를 줄일 수 있다.

2. 구성 가능성 (Composability)

Claude는 여러 스킬을 함께 로드할 수 있다. 그래서 각 스킬은 단독 동작만 가정하지 말고, 다른 스킬과 같이 돌아가도 충돌이 없어야 한다.

3. 이식성 (Portability)

스킬은 Claude.ai, Claude Code, API에서 같은 구조로 쓸 수 있다. 필요한 의존성만 맞으면 대부분 수정 없이 옮길 수 있다.

MCP 빌더를 위한: Skills + Connectors

MCP 없이 독립형 스킬만 만들면 된다면, 이 섹션은 건너뛰고 계획/설계부터 보면 된다.

이미 MCP 서버가 동작한다면, 스킬은 그 위에 워크플로우 지식을 얹는 단계다. 팀이 이미 쓰는 절차를 문서화해 두면 Claude가 매번 같은 방식으로 적용한다.

주방 비유

함께 작동하는 방식

MCP 사용자에게 중요한 이유

스킬 없이:

• 사용자가 MCP를 연결하지만 다음에 무엇을 해야 할지 모름
• "통합으로 X를 어떻게 하나요"라는 지원 티켓
• 각 대화가 처음부터 시작됨
• 사용자가 매번 다르게 프롬프트하기 때문에 일관되지 않은 결과
• 실제 문제는 워크플로우 가이드인데 사용자가 커넥터를 비난

스킬 있으면:

• 필요할 때 미리 구축된 워크플로우가 자동으로 활성화됨
• 일관되고 신뢰할 수 있는 도구 사용
• 모든 상호작용에 모범 사례가 내장됨
• 통합에 대한 학습 곡선 감소

---

2장. 계획 및 설계

사용 사례로 시작

코드를 쓰기 전에 스킬이 해결해야 할 사용 사례 2~3개를 먼저 정한다.

좋은 사용 사례 정의 예시

복사
사용 사례: 프로젝트 스프린트 계획

트리거: 사용자가 "이 스프린트 계획을 도와줘" 또는 "스프린트 작업 생성"이라고 말함

단계:
1. Linear에서 현재 프로젝트 상태 가져오기 (MCP 통해)
2. 팀 속도 및 용량 분석
3. 작업 우선순위 제안
4. 적절한 라벨과 예상 시간으로 Linear에 작업 생성

결과: 작업이 생성된 완전히 계획된 스프린트

스스로에게 질문하기

• 사용자가 성취하고 싶은 것은 무엇인가?
• 이것에 어떤 다단계 워크플로우가 필요한가?
• 어떤 도구가 필요한가 (내장 또는 MCP)?
• 어떤 도메인 지식이나 모범 사례를 내장해야 하는가?

일반적인 스킬 사용 사례 카테고리

실무에서 자주 쓰는 패턴은 크게 세 가지다.

카테고리 1: 문서 및 자산 생성

용도: 문서, 프레젠테이션, 앱, 디자인, 코드 등 일관되고 고품질의 출력 생성

실제 예시: frontend-design 스킬

복사
"높은 디자인 품질로 독특하고 프로덕션급 프론트엔드 인터페이스를 생성합니다.
웹 컴포넌트, 페이지, 아티팩트, 포스터 또는 애플리케이션을 구축할 때 사용하세요."

핵심 기법:

• 내장된 스타일 가이드 및 브랜드 표준
• 일관된 출력을 위한 템플릿 구조
• 완료 전 품질 체크리스트
• 외부 도구 불필요 - Claude의 내장 기능 사용

카테고리 2: 워크플로우 자동화

용도: 일관된 방법론의 이점을 누릴 수 있는 다단계 프로세스, 여러 MCP 서버 간 조정 포함

실제 예시: skill-creator 스킬

복사
"새로운 스킬을 만들기 위한 대화형 가이드. 사용 사례 정의, frontmatter 생성,
지침 작성 및 검증을 통해 사용자를 안내합니다."

핵심 기법:

• 검증 게이트가 있는 단계별 워크플로우
• 일반적인 구조를 위한 템플릿
• 내장된 검토 및 개선 제안
• 반복적인 정제 루프

카테고리 3: MCP 강화

용도: MCP 서버가 제공하는 도구 액세스를 강화하는 워크플로우 가이드

실제 예시: sentry-code-review 스킬 (Sentry 제공)

복사
"Sentry의 MCP 서버를 통한 오류 모니터링 데이터를 사용하여 GitHub Pull Request에서
감지된 버그를 자동으로 분석하고 수정합니다."

핵심 기법:

• 순차적으로 여러 MCP 호출 조정
• 도메인 전문 지식 내장
• 사용자가 달리 지정해야 할 컨텍스트 제공
• 일반적인 MCP 문제에 대한 오류 처리

성공 기준 정의

스킬이 제대로 동작하는지는 아래 기준으로 확인한다.

정량적 지표

정성 지표

• 사용자가 Claude에게 다음 단계에 대해 프롬프트할 필요가 없음
• 사용자 수정 없이 워크플로우 완료
• 세션 간 일관된 결과

기술 요구사항

파일 구조

복사
your-skill-name/
├── SKILL.md          # 필수 - 메인 스킬 파일
├── scripts/          # 선택 사항 - 실행 가능한 코드
│   ├── process_data.py
│   └── validate.sh
├── references/       # 선택 사항 - 문서
│   ├── api-guide.md
│   └── examples/
└── assets/           # 선택 사항 - 템플릿 등
    └── report-template.md

중요 규칙

SKILL.md 명명:

• 정확히 SKILL.md여야 함 (대소문자 구분)
• 변형 허용 안 됨 (SKILL.MD, skill.md 등)

스킬 폴더 명명:

• kebab-case 사용: notion-project-setup ✅
• 공백 없음: Notion Project Setup ❌
• 밑줄 없음: notion_project_setup ❌
• 대문자 없음: NotionProjectSetup ❌

README.md 금지:

• 스킬 폴더 안에 README.md를 포함하지 마세요
• 모든 문서는 SKILL.md 또는 references/에 들어갑니다

YAML frontmatter: 가장 중요한 부분

YAML frontmatter는 스킬 로드 여부를 결정하는 핵심 정보다. 여기서 실수하면 트리거가 잘 안 맞는다.

최소 필수 형식

복사
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

필드 요구사항

name (필수):

• kebab-case만
• 공백이나 대문자 없음
• 폴더 이름과 일치해야 함

description (필수):

• 반드시 둘 다 포함:
   - 스킬이 하는 일
   - 사용 시기 (트리거 조건)
• 1024자 미만
• XML 태그 없음 (< 또는 >)
• 사용자가 말할 수 있는 특정 작업 포함
• 관련 있는 경우 파일 형식 언급

license (선택 사항):

• 스킬을 오픈 소스로 만드는 경우 사용
• 일반적: MIT, Apache-2.0

compatibility (선택 사항):

• 1-500자
• 환경 요구사항 표시

metadata (선택 사항):

• 모든 사용자 정의 키-값 쌍
• 권장: author, version, mcp-server

복사
metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

보안 제한

frontmatter에서 금지된 것:

• XML 꺾쇠 괄호 (< >)
• 이름에 "claude" 또는 "anthropic"이 포함된 스킬 (예약됨)

잘 작동하는 스킬 작성

description 필드

핵심은 간단하다. description에 "무엇을 하는지"와 "언제 쓰는지"를 정확히 써야 Claude가 필요한 순간에만 스킬을 불러온다.

구조:

복사
[무엇을 하는지] + [언제 사용하는지] + [핵심 기능]

좋은 description 예시:

복사
# 좋음 - 구체적이고 실행 가능
description: Figma 디자인 파일을 분석하고 개발자 인계 문서를 생성합니다. 사용자가 .fig 파일을 업로드하거나, "디자인 스펙", "컴포넌트 문서", 또는 "디자인-투-코드 인계"를 요청할 때 사용하세요.

# 좋음 - 트리거 문구 포함
description: 스프린트 계획, 작업 생성 및 상태 추적을 포함한 Linear 프로젝트 워크플로우를 관리합니다. 사용자가 "스프린트", "Linear 작업", "프로젝트 계획"을 언급하거나 "티켓 생성"을 요청할 때 사용하세요.

# 좋음 - 명확한 가치 제안
description: PayFlow를 위한 엔드투엔드 고객 온보딩 워크플로우. 계정 생성, 결제 설정 및 구독 관리를 처리합니다. 사용자가 "새 고객 온보딩", "구독 설정" 또는 "PayFlow 계정 생성"이라고 말할 때 사용하세요.

나쁜 description 예시:

복사
# 너무 모호함
description: 프로젝트를 도와줍니다.

# 트리거 없음
description: 정교한 다중 페이지 문서 시스템을 생성합니다.

# 너무 기술적, 사용자 트리거 없음
description: 계층적 관계가 있는 Project 엔터티 모델을 구현합니다.

메인 지침 작성

frontmatter 후, Markdown으로 실제 지침을 작성하세요.

권장 구조:

복사
---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [첫 번째 주요 단계]
무슨 일이 일어나는지 명확히 설명.

Example:
\`\`\`bash
python scripts/fetch_data.py --project-id PROJECT_ID
\`\`\`

Expected output: [성공이 어떻게 보이는지 설명]

## Examples

### Example 1: [일반적인 시나리오]
User says: "새 마케팅 캠페인 설정"
Actions:
1. MCP를 통해 기존 캠페인 가져오기
2. 제공된 매개변수로 새 캠페인 생성
Result: 확인 링크와 함께 캠페인 생성됨

## Troubleshooting

### Error: [일반적인 오류 메시지]
**Cause:** [왜 발생하는지]
**Solution:** [수정 방법]

지침 작성 모범 사례

구체적이고 실행 가능하게:

복사
✅ 좋음:
데이터 형식을 확인하려면 `python scripts/validate.py --input {filename}`을 실행하세요.
검증이 실패하면 일반적인 문제는 다음과 같습니다:
- 필수 필드 누락 (CSV에 추가)
- 잘못된 날짜 형식 (YYYY-MM-DD 사용)

❌ 나쁨:
진행하기 전에 데이터를 검증하세요.

오류 처리 포함:

복사
## Common Issues

### MCP Connection Failed
"Connection refused"가 표시되면:
1. MCP 서버가 실행 중인지 확인: Settings > Extensions
2. API 키가 유효한지 확인
3. 재연결 시도: Settings > Extensions > [Your Service] > Reconnect

---

3장. 테스트 및 반복

테스트 수준

권장 테스트 접근법

1. 트리거링 테스트

목표: 스킬이 올바른 시점에 로드되는지 확인

테스트 케이스:

• ✅ 명백한 작업에서 트리거
• ✅ 바꿔 말한 요청에서 트리거
• ❌ 관련 없는 주제에서 트리거하지 않음

예시 테스트 스위트:

복사
트리거되어야 함:
- "새 ProjectHub 워크스페이스 설정을 도와줘"
- "ProjectHub에 프로젝트를 만들어야 해"
- "Q4 계획을 위한 ProjectHub 프로젝트 초기화"

트리거되지 않아야 함:
- "샌프란시스코 날씨 어때?"
- "Python 코드 작성 도와줘"
- "스프레드시트 만들어" (ProjectHub 스킬이 시트를 처리하지 않는 한)

2. 기능 테스트

목표: 스킬이 올바른 출력을 생성하는지 확인

테스트 케이스:

• 유효한 출력 생성됨
• API 호출 성공
• 오류 처리 작동
• 엣지 케이스 커버됨

예시:

복사
Test: 5개 작업으로 프로젝트 생성
Given: 프로젝트 이름 "Q4 Planning", 5개 작업 설명
When: 스킬이 워크플로우 실행
Then:
- ProjectHub에 프로젝트 생성됨
- 올바른 속성으로 5개 작업 생성됨
- 모든 작업이 프로젝트에 연결됨
- API 오류 없음

3. 성능 비교

베이스라인 비교:

skill-creator 스킬 사용

skill-creator 스킬은 초안 작성과 반복 개선에 유용하다.

기능:

• 자연어 설명에서 스킬 생성
• 적절한 형식의 SKILL.md with frontmatter 생성
• 트리거 문구 및 구조 제안
• 일반적인 문제 플래그
• 과잉/부족 트리거링 위험 식별
• 스킬의 목적에 기반한 테스트 케이스 제안

사용법:

복사
"skill-creator 스킬을 사용하여 [사용 사례]를 위한 스킬을 만들어 도와줘"

피드백 기반 반복

스킬은 한 번 만들고 끝나는 문서가 아니다. 아래 신호를 기준으로 계속 다듬는다.

과소 트리거링 신호

• 스킬이 로드되어야 할 때 로드되지 않음
• 사용자가 수동으로 활성화
• 사용 시기에 대한 지원 질문

해결책: description에 더 많은 세부 사항과 뉘앙스 추가

과잉 트리거링 신호

• 관련 없는 쿼리에 스킬 로드
• 사용자가 비활성화
• 목적에 대한 혼란

해결책: 부정적 트리거 추가, 더 구체적으로

실행 문제

• 일관되지 않은 결과
• API 호출 실패
• 사용자 수정 필요

해결책: 지침 개선, 오류 처리 추가

---

4장. 배포 및 공유

현재 배포 모델 (2026년 1월)

개별 사용자:

1. 스킬 폴더 다운로드
2. 폴더 압축 (필요한 경우)
3. Claude.ai > Settings > Capabilities > Skills에서 업로드
4. 또는 Claude Code 스킬 디렉토리에 배치

조직 수준 스킬:

• 관리자가 워크스페이스 전체에 스킬 배포 가능 (2025년 12월 18일 출시)
• 자동 업데이트
• 중앙 집중식 관리

개방형 표준

Agent Skills는 개방형 표준을 지향한다. MCP와 마찬가지로, 한 플랫폼에서 만든 스킬을 다른 환경으로 옮겨도 최대한 같은 방식으로 동작해야 한다.

API를 통한 스킬 사용

주요 기능:

• /v1/skills 엔드포인트로 스킬 목록 및 관리
• container.skills 매개변수를 통해 Messages API 요청에 스킬 추가
• Claude Console을 통한 버전 관리
• Claude Agent SDK와 함께 작동

사용 사례별 최적 플랫폼:

권장 접근법

1. GitHub에 호스팅
     - 오픈 소스 스킬을 위한 공개 저장소
     - 설치 지침이 있는 명확한 README
     - 예제 사용법 및 스크린샷

2. MCP 저장소에 사용법 문서화
     - MCP 문서에서 스킬로 링크
     - 함께 사용하는 가치 설명
     - 빠른 시작 가이드 제공

3. 설치 가이드 작성

복사
# [Your Service] 스킬 설치

1. 스킬 다운로드:
   - 저장소 복제: `git clone https://github.com/yourcompany/skills`
   - 또는 Releases에서 ZIP 다운로드

2. Claude에 설치:
   - Claude.ai > Settings > skills 열기
   - "Upload skill" 클릭 - 스킬 폴더 선택 (압축된 상태)

3. 스킬 활성화:
   - [Your Service] 스킬 켜기
   - MCP 서버가 연결되어 있는지 확인

4. 테스트:
   - Claude에 다음처럼 입력: "[Your Service]에 새 프로젝트 설정해 줘"

스킬 포지셔닝

기능 나열보다 결과 중심으로 설명:

복사
✅ 좋음:
"ProjectHub 스킬을 사용하면 팀이 몇 초 만에 완전한 프로젝트 워크스페이스를 설정할 수 있습니다.
수동 설정에 30분을 소비하는 대신 페이지, 데이터베이스, 템플릿을 포함합니다."

❌ 나쁨:
"ProjectHub 스킬은 YAML frontmatter와 Markdown 지침이 포함된 폴더로,
MCP 서버 도구를 호출합니다."

MCP + 스킬 스토리 강조:

복사
"MCP 서버는 Claude에게 Linear 프로젝트에 대한 액세스를 제공합니다.
스킬은 Claude에게 팀의 스프린트 계획 워크플로우를 가르칩니다.
함께, AI 기반 프로젝트 관리를 가능하게 합니다."

---

5장. 패턴 및 문제 해결

접근 방식 선택: 문제 우선 vs 도구 우선

문제 우선: "프로젝트 워크스페이스를 설정해야 해" → 목표 달성을 위한 MCP 호출 순서를 스킬이 정리

도구 우선: "Notion MCP가 연결되어 있어" → 연결된 도구를 실무 절차에 맞게 쓰도록 스킬이 안내

패턴 1: 순차적 워크플로우 조정

사용 시점: 사용자가 특정 순서로 다단계 프로세스가 필요한 경우

복사
# Workflow: 신규 고객 온보딩

## Step 1: 계정 생성
Call MCP tool: `create_customer`
Parameters: name, email, company

## Step 2: 결제 설정
Call MCP tool: `setup_payment_method`
Wait for: 결제 수단 확인

## Step 3: 구독 생성
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (Step 1에서)

## Step 4: 환영 이메일 발송
Call MCP tool: `send_email`
Template: welcome_email_template

핵심 기법:

• 명시적인 단계 순서
• 단계 간 의존성
• 각 단계에서 검증
• 실패 시 롤백 지침

패턴 2: 다중 MCP 조정

사용 시점: 워크플로우가 여러 서비스에 걸쳐 있는 경우

복사
# 디자인-투-개발 인계

## Phase 1: 디자인 내보내기 (Figma MCP)
1. Figma에서 디자인 자산 내보내기
2. 디자인 사양 생성
3. 자산 매니페스트 생성

## Phase 2: 자산 저장 (Drive MCP)
1. Drive에 프로젝트 폴더 생성
2. 모든 자산 업로드
3. 공유 가능한 링크 생성

## Phase 3: 작업 생성 (Linear MCP)
1. 개발 작업 생성
2. 작업에 자산 링크 첨부
3. 엔지니어링 팀에 할당

## Phase 4: 알림 (Slack MCP)
1. #engineering에 인계 요약 게시
2. 자산 링크 및 작업 참조 포함

핵심 기법:

• 명확한 단계 분리
• MCP 간 데이터 전달
• 다음 단계로 이동하기 전 검증
• 중앙 집중식 오류 처리

패턴 3: 반복적 정제

사용 시점: 반복을 통해 출력 품질이 향상되는 경우

복사
# 반복적 보고서 생성

## Initial Draft
1. MCP를 통해 데이터 가져오기
2. 첫 번째 초안 보고서 생성
3. 임시 파일에 저장

## Quality Check
1. 검증 스크립트 실행: `scripts/check_report.py`
2. 문제 식별:
   - 누락된 섹션
   - 일관되지 않은 형식
   - 데이터 검증 오류

## Refinement Loop
1. 식별된 각 문제 해결
2. 영향받은 섹션 재생성
3. 재검증
4. 품질 임계값 충족까지 반복

## Finalization
1. 최종 형식 적용
2. 요약 생성
3. 최종 버전 저장

패턴 4: 컨텍스트 인식 도구 선택

사용 시점: 동일한 결과, 컨텍스트에 따라 다른 도구

복사
# 스마트 파일 저장

## Decision Tree
1. 파일 형식 및 크기 확인
2. 최적의 저장 위치 결정:
   - 대용량 파일 (>10MB): 클라우드 저장소 MCP 사용
   - 협업 문서: Notion/Docs MCP 사용
   - 코드 파일: GitHub MCP 사용
   - 임시 파일: 로컬 저장소 사용

## Execute Storage
결정에 따라:
- 적절한 MCP 도구 호출
- 서비스별 메타데이터 적용
- 액세스 링크 생성

## Provide Context to User
그 저장소가 선택된 이유 설명

패턴 5: 도메인별 인텔리전스

사용 시점: 스킬이 도구 액세스 이상의 전문 지식을 추가하는 경우

복사
# 규정 준수 결제 처리

## Before Processing (Compliance Check)
1. MCP를 통해 거래 세부 정보 가져오기
2. 규정 준수 규칙 적용:
   - 제재 목록 확인
   - 관할권 허용 검증
   - 위험 수준 평가
3. 규정 준수 결정 문서화

## Processing
IF 규정 준수 통과:
- 결제 처리 MCP 도구 호출
- 적절한 사기 확인 적용
- 거래 처리
ELSE:
- 검토를 위해 플래그 지정
- 규정 준수 사례 생성

## Audit Trail
- 모든 규정 준수 확인 로그
- 처리 결정 기록
- 감사 보고서 생성

문제 해결

스킬이 업로드되지 않음

Error: "Could not find SKILL.md in uploaded folder"

• 원인: 파일이 정확히 SKILL.md로 명명되지 않음
• 해결책: SKILL.md로 이름 변경 (대소문자 구분)

Error: "Invalid frontmatter"

• 원인: YAML 형식 문제

복사
# 잘못됨 - 구분 기호 누락
name: my-skill
description: Does things

# 잘못됨 - 닫히지 않은 따옴표
name: my-skill
description: "Does things

# 올바름
---
name: my-skill
description: Does things
---

Error: "Invalid skill name"

• 원인: 이름에 공백이나 대문자 포함

복사
# 잘못됨
name: My Cool Skill

# 올바름
name: my-cool-skill

스킬이 트리거되지 않음

증상: 스킬이 자동으로 로드되지 않음

해결책: description 필드 수정

빠른 체크리스트:

• 너무 일반적이지 않은가? ("Helps with projects"는 작동하지 않음)
• 사용자가 실제로 말할 트리거 문구가 포함되어 있는가?
• 해당되는 경우 관련 파일 형식이 언급되어 있는가?

디버깅 접근법:
Claude에 다음 프롬프트를 넣어 확인한다: "[스킬 이름] 스킬은 언제 사용하나요?"  
응답이 description을 어떻게 해석하는지 보고 누락된 트리거 문구를 보강한다.

스킬이 너무 자주 트리거됨

증상: 관련 없는 쿼리에 스킬이 로드됨

해결책 1: 부정적 트리거 추가

복사
description: CSV 파일에 대한 고급 데이터 분석. 통계 모델링, 회귀, 클러스터링에 사용.
단순한 데이터 탐색에는 사용하지 마세요 (대신 data-viz 스킬 사용).

해결책 2: 더 구체적으로

복사
# 너무 광범위함
description: 문서를 처리합니다

# 더 구체적으로
description: 계약 검토를 위해 PDF 법률 문서를 처리합니다

MCP 연결 문제

증상: 스킬은 로드되지만 MCP 호출 실패

체크리스트:

1. MCP 서버가 연결되어 있는지 확인
     - Claude.ai: Settings > Extensions > [Your Service]
     - "Connected" 상태여야 함
2. 인증 확인
     - API 키가 유효하고 만료되지 않음
     - 적절한 권한/범위가 부여됨
     - OAuth 토큰이 새로고침됨
3. MCP 독립적으로 테스트
     - 스킬 없이 Claude에게 MCP 직접 호출 요청
     - "[Service] MCP를 사용하여 내 프로젝트 가져와"
     - 이것이 실패하면 문제는 MCP이지 스킬이 아님

지침이 따르지 않음

증상: 스킬은 로드되지만 Claude가 지침을 따르지 않음

일반적인 원인:

1. 지침이 너무 장황함
     - 지침을 간결하게 유지
     - 글머리 기호 및 번호 매기기 목록 사용
     - 상세한 참조는 별도 파일로 이동

2. 지침이 묻혀 있음
     - 중요한 지침을 맨 위에 배치
     - ## Important 또는 ## Critical 헤더 사용
     - 필요한 경우 핵심 포인트 반복

3. 모호한 언어

복사
❌ 나쁨:
제대로 검증해야 합니다

✅ 좋음:
CRITICAL: create_project 호출 전에 확인:
- 프로젝트 이름이 비어 있지 않음
- 최소한 한 명의 팀 멤버가 할당됨
- 시작 날짜가 과거가 아님

대규모 컨텍스트 문제

증상: 스킬이 느리거나 응답이 저하됨

해결책:

1. SKILL.md 크기 최적화
     - 상세한 문서는 references/로 이동
     - 인라인 대신 참조에 링크
     - SKILL.md를 5,000단어 미만으로 유지
2. 활성화된 스킬 줄이기
     - 20-50개 이상의 스킬이 동시에 활성화되어 있는지 평가
     - 선택적 활성화 권장

---

6장. 리소스 및 참고 자료

공식 문서

Anthropic 리소스:

• Best Practices Guide
• Skills Documentation
• API Reference
• MCP Documentation

블로그 게시물:

• Introducing Agent Skills
• Engineering Blog: Equipping Agents for the Real World
• Skills Explained
• How to Create Skills for Claude
• Building Skills for Claude Code
• Improving Frontend Design through Skills

예제 스킬

공개 스킬 저장소:

• GitHub: anthropics/skills
• Anthropic이 만든 스킬을 사용자 정의할 수 있음

도구 및 유틸리티

skill-creator 스킬:

• Claude.ai에 내장되어 있고 Claude Code에서 사용 가능
• 설명에서 스킬 생성 가능
• 검토 및 권장 사항 제공
• 사용: "skill-creator를 사용하여 스킬을 만들어 도와줘"

검증:

• skill-creator가 스킬 평가 가능
• 다음처럼 요청해 검토한다: "이 스킬을 검토하고 개선 사항을 제안해 줘"

지원 받기

기술 질문:

• 일반 질문: Claude Developers Discord의 커뮤니티 포럼

버그 보고:

• GitHub Issues: anthropics/skills/issues
• 포함: 스킬 이름, 오류 메시지, 재현 단계

---

참조 A: 빠른 체크리스트

시작 전

• 2-3개의 구체적인 사용 사례 식별
• 도구 식별 (내장 또는 MCP)
• 이 가이드 및 예제 스킬 검토
• 폴더 구조 계획

개발 중

• kebab-case로 폴더 명명
• SKILL.md 파일 존재 (정확한 철자)
• YAML frontmatter에 --- 구분 기호 있음
• name 필드: kebab-case, 공백 없음, 대문자 없음
• description에 WHAT과 WHEN 포함
• 어디에도 XML 태그 (< >) 없음
• 지침이 명확하고 실행 가능
• 오류 처리 포함
• 예제 제공
• 참조가 명확하게 링크됨

업로드 전

• 명백한 작업에서 트리거링 테스트
• 바꿔 말한 요청에서 트리거링 테스트
• 관련 없는 주제에서 트리거하지 않음 확인
• 기능 테스트 통과
• 도구 통합 작동 (해당되는 경우)
• .zip 파일로 압축

업로드 후

• 실제 대화에서 테스트
• 과소/과잉 트리거링 모니터링
• 사용자 피드백 수집
• description 및 지침 반복
• metadata에서 버전 업데이트

---

참조 B: YAML frontmatter

필수 필드

복사
---
name: skill-name-in-kebab-case
description: 무엇을 하는지와 언제 사용하는지. 특정 트리거 문구를 포함하세요.
---

모든 선택 필드

복사
name: skill-name
description: [필수 description]
license: MIT  # 선택 사항: 오픈 소스용 라이선스
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 선택 사항: 도구 액세스 제한
metadata:  # 선택 사항: 사용자 정의 필드
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com

보안 참고

허용됨:

• 모든 표준 YAML 타입 (문자열, 숫자, 부울, 목록, 객체)
• 사용자 정의 metadata 필드
• 긴 description (최대 1024자)

금지됨:

• XML 꺾쇠 괄호 (< >) - 보안 제한
• YAML에서 코드 실행 (안전한 YAML 파싱 사용)
• "claude" 또는 "anthropic" 접두사가 있는 스킬 명명 (예약됨)

---

참조 C: 완전한 스킬 예제

이 가이드의 패턴을 확인할 때 참고하기 좋은 스킬:

• Document Skills - PDF, DOCX, PPTX, XLSX 생성
• Example Skills - 여러 워크플로우 패턴 예시
• Partner Skills Directory - Asana, Atlassian, Canva, Figma, Sentry, Zapier 등 파트너 스킬 목록

이 저장소들에는 이 문서보다 더 많은 예제가 들어 있다. 그대로 복제한 뒤, 팀 사용 사례에 맞게 줄이고 바꿔서 템플릿으로 쓰면 된다.

---

원본: The Complete Guide to Building Skills for Claude - Anthropic