Skills 패턴 및 트러블슈팅

초기 사용자와 내부 팀이 만든 스킬에서 관찰된 5가지 워크플로 패턴과 일반적인 문제 해결법.

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

문제 우선: “프로젝트 워크스페이스를 설정해야 해” → 스킬이 올바른 MCP 호출을 조율
도구 우선: “Notion MCP가 연결되어 있어” → 스킬이 최적의 워크플로와 모범 사례를 교육

5가지 워크플로 패턴

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

다단계 프로세스가 특정 순서로 필요할 때.


## 새 고객 온보딩
1단계: 계정 생성 → create_customer
2단계: 결제 설정 → setup_payment_method (확인 대기)
3단계: 구독 생성 → create_subscription (1단계 customer_id 사용)
4단계: 환영 이메일 → send_email

핵심: 명시적 단계 순서, 단계 간 의존성, 각 단계 유효성 검사, 실패 시 롤백 명령어.

패턴 2: 다중 MCP 조율

워크플로가 여러 서비스에 걸쳐 있을 때.


## 디자인-to-개발 핸드오프
1단계: 디자인 내보내기 (Figma MCP) → 자산 + 사양 생성
2단계: 자산 저장 (Drive MCP) → 폴더 생성 + 업로드 + 링크 생성
3단계: 작업 생성 (Linear MCP) → 개발 작업 + 자산 링크 첨부
4단계: 알림 (Slack MCP) → #engineering에 요약 게시

핵심: 명확한 단계 분리, MCP 간 데이터 전달, 단계 간 유효성 검사, 중앙화된 오류 처리.

패턴 3: 반복적 개선

반복을 통해 출력 품질이 향상될 때.


## 보고서 생성
초안 작성 → 품질 확인 (scripts/check_report.py) → 개선 루프 → 최종화

핵심: 명시적 품질 기준, 유효성 검사 스크립트, 반복 종료 조건.

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

동일한 결과에 컨텍스트에 따라 다른 도구를 선택할 때.


## 스마트 파일 저장 결정 트리
- 대용량 (>10MB): 클라우드 저장소 MCP
- 협업 문서: Notion/Docs MCP
- 코드 파일: GitHub MCP
- 임시 파일: 로컬 저장소

핵심: 명확한 결정 기준, 폴백 옵션, 선택에 대한 투명성.

패턴 5: 도메인 특화 지능

도구 접근 이상의 전문 지식을 추가할 때.


## 컴플라이언스 포함 결제 처리
처리 전: 제재 목록 확인, 관할권 허용 확인, 위험 수준 평가
처리: 컴플라이언스 통과 → 결제 처리 / 실패 → 검토 표시
감사: 모든 확인 로그, 처리 결정 기록

핵심: 도메인 전문 지식 내장, 작업 전 컴플라이언스, 포괄적 문서화.

트러블슈팅

업로드 오류

오류	원인	해결
”SKILL.md를 찾을 수 없음”	파일명이 정확히 `SKILL.md`가 아님	대소문자 확인 후 이름 변경
”잘못된 프론트매터”	YAML 형식 문제 (구분자 없음, 닫히지 않은 따옴표)	`---` 구분자 확인
”잘못된 스킬 이름”	이름에 공백이나 대문자	kebab-case로 변경

스킬이 트리거되지 않음

빠른 체크리스트:

description이 너무 일반적이지 않은가?
사용자가 실제로 말할 트리거 문구가 포함되었나?
관련 파일 형식이 언급되었나?

디버깅: Claude에게 “[스킬 이름] 스킬을 언제 사용하겠어?”라고 물어보면 description을 다시 인용하므로 빠진 것을 파악할 수 있다.

스킬이 너무 자주 트리거됨

부정적 트리거 추가: “간단한 데이터 탐색에는 사용하지 마세요”
더 구체적으로: “문서 처리” → “계약 검토를 위한 PDF 법률 문서 처리”
범위 명확화: “온라인 결제 워크플로에만 사용하며, 일반적인 금융 쿼리에는 사용하지 마세요”

MCP 연결 문제

MCP 서버 연결 상태 확인 (설정 > 확장 프로그램)
API 키 유효성 및 권한 확인
MCP 독립 테스트 (스킬 없이 직접 호출)
도구 이름 확인 (대소문자 구분)

명령어가 따르지 않음

원인	해결
명령어가 너무 장황	간결하게, 글머리 기호/번호 목록, 상세 참조는 `references/`로
명령어가 묻혀 있음	중요한 것을 맨 위에, `## 중요` 헤더 사용
모호한 언어	”올바르게 검사” → 구체적 확인 항목 나열
모델 “게으름”	`scripts/`에 검증 코드 번들링 (결정론적)

대용량 컨텍스트 문제

SKILL.md를 5,000단어 이하로 유지
상세 문서는 references/로 이동
동시 활성 스킬 20-50개 이상이면 선택적 활성화 권장
관련 기능을 위한 스킬 “팩” 고려

빠른 체크리스트

개발 중

업로드 전

트리거 테스트 (명백한 작업 + 다른 표현)
비트리거 테스트 (관련 없는 주제)
기능 테스트 통과
.zip 압축

업로드 후

실제 대화에서 테스트
과도/부족 트리거 모니터링
사용자 피드백 수집, 반복

Skills 개요 — 스킬 개념, 설계 원칙
Skills 개발 가이드 — 사용 사례, 명령어 작성법
Skills 테스트 — 테스트, skill-creator
Skills 배포 — 배포 모델, API