Claude Skills 구축을 위한 완벽 가이드

요약

• Anthropic이 작성한 33페이지 PDF 가이드로, Claude Skills의 설계/구조화/테스트/배포 전 과정을 단계별로 다룸
• Skills는 반복 작업을 한 번 정의해 지속 재사용하는 워크플로 지식 패키지로, MCP와 결합 시 “무엇을 할 수 있는지” + “어떻게 해야 하는지”를 모두 제공
• Progressive Disclosure(3단계 정보 로딩), Composability, Portability가 핵심 설계 원칙이며, 상위 23개 워크플로가 정리되어 있다면 1530분 내 첫 스킬 구축 가능

댓글 요약

• Anthropic의 체계적인 문서화 역량에 대한 긍정적 반응

본문

• Claude Skills는 반복되는 작업 흐름을 한 번 정의해 지속적으로 재사용하도록 설계된 워크플로 지식 패키지
• 앤트로픽이 직접 작성한 33p PDF 가이드 로 스킬 설계부터 구조화, 테스트, 배포까지 전 과정을 단계적으로 다룸
• 단독 워크플로 자동화부터 MCP 기반 도구 통합 강화까지 폭넓은 활용 시나리오를 포함
• 실제 운영 환경에서 검증된 패턴과 실패 사례를 기반으로 작성됨
• 상위 23개의 워크플로가 정리되어 있다면, 첫 스킬은 **1530분 내** 구축 및 테스트 가능

Introduction

• 이 가이드는 Claude Skills를 일회성 프롬프트가 아닌, 반복 사용 가능한 워크플로 자산으로 다루는 것을 목표로 함
• Skills는 특정 작업이나 프로세스를 Claude에게 한 번 가르쳐, 이후 모든 대화에서 일관되게 재사용할 수 있도록 설계된 구조로 정의
• 사용자의 선호, 작업 방식, 도메인 지식을 매번 설명하지 않아도 되도록 하여 인지적·운영적 비용을 크게 줄일수 있음

• Skills가 특히 효과적인 상황

  • Skills는 반복 가능하고 구조화된 작업에서 가장 큰 효과를 발휘함
    • 스펙을 기반으로 한 프론트엔드 디자인 생성
    • 일정한 방법론을 따르는 리서치 수행
    • 팀 스타일 가이드를 반영한 문서 작성
    • 여러 단계를 거치는 복합 프로세스 오케스트레이션
  • Claude의 내장 기능(코드 실행, 문서 생성 등)과 자연스럽게 결합됨

• MCP와 Skills의 역할 구분

  • MCP 통합을 사용하는 경우, Skills는 단순한 도구 연결을 넘어 워크플로를 안정화하는 추가 계층으로 설명됨
  • MCP가 “무엇을 할 수 있는지”를 제공한다면, Skills는 “어떻게 해야 하는지”를 고정하는 역할
  • 이를 통해 원시적인 도구 접근을 신뢰 가능한 자동화 경험으로 전환 가능함

• 가이드의 목적과 범위

  • 이 문서는 Skills 구축에 필요한 전 과정을 포괄함
    • 사전 기획과 구조 설계
    • 실제 작성 방식
    • 테스트와 반복 개선
    • 배포와 공유
  • 개인용 스킬, 팀 내부 표준 스킬, 커뮤니티 공유용 스킬까지 모든 활용 범위를 대상으로 함
  • 이론 설명보다는 실무에서 검증된 패턴과 예시를 중심으로 구성됨

• 대상 독자

  • Claude가 특정 워크플로를 항상 같은 방식으로 수행하길 원하는 개발자
  • 반복 작업 자동화를 원하는 파워 유저
  • 조직 단위로 Claude 사용 방식을 표준화하려는 팀
  • MCP 커넥터에 워크플로 지식을 결합하려는 빌더

• 가이드 활용 경로

  • 단독 Skills 구축이 목적이라면:
    • Fundamentals
    • Planning and Design
    • Category 1–2 중심으로 참고 권장
  • MCP 통합 강화를 목표로 한다면:
    • Skills + MCP 섹션
    • Category 3 중심 활용 권장
  • 두 경로는 기술적 요구사항을 공유하며, 필요한 부분만 선택적으로 적용 가능함

• 기대 결과

  • 이 가이드를 따라가면 한 번의 세션에서 실용적인 Skill 하나를 완성할 수 있도록 설계됨
  • 상위 23개의 명확한 워크플로가 있는 경우, 첫 Skill은 **약 1530분 내 구축 및 테스트 가능**
  • Introduction은 이후 모든 챕터가 전제하는 핵심 관점, 즉 “Skills는 프롬프트가 아니라 재사용 가능한 작업 지식” 이라는 인식을 명확히 함

Chapter 1: 기본 개념 (Fundamentals)

• Claude Skills를 이해하기 위한 개념적 토대와 설계 철학을 설명
• Skills를 단순한 프롬프트 묶음이 아니라, 지속적으로 재사용되는 작업 지식 단위로 정의하고
• 이후 챕터에서 다루는 설계·테스트·배포 논의의 전제가 되는 핵심 원칙을 정리

• Skill이란 무엇인가

  • Skill은 Claude에게 특정 작업이나 워크플로를 수행하는 방법을 한 번 가르쳐 반복 사용할 수 있게 하는 구조
  • 사용자의 선호, 절차, 도메인 지식을 매번 설명하지 않아도 되도록 설계됨
  • 반복성이 높은 작업에서 가장 큰 효과를 발휘함
  • 예시:
    • 스펙 기반 프론트엔드 디자인 생성
    • 일관된 방식의 리서치 수행
    • 팀 스타일 가이드를 따르는 문서 작성
    • 다단계 프로세스 자동 실행

• Skill의 기본 구성 요소

  • Skill은 하나의 폴더 단위로 구성됨
  • 필수 구성:
    • SKILL.md: YAML frontmatter와 Markdown 지침을 포함한 핵심 파일
  • 선택 구성:
    • scripts/: Python, Bash 등 실행 코드
    • references/: 필요 시 참조되는 문서와 가이드
    • assets/: 출력물에 사용되는 템플릿, 리소스
  • 이 구조는 단순함과 확장성을 동시에 만족하도록 설계됨

• 핵심 설계 원칙 1: Progressive Disclosure

  • Skills는 3단계 정보 로딩 구조를 따름

  • 1단계: YAML frontmatter

    • Claude의 시스템 프롬프트에 항상 로드됨
    • 스킬이 언제 사용되어야 하는지 판단하는 최소 정보만 포함
    • 불필요한 컨텍스트 로딩을 방지하는 역할

  • 2단계: SKILL.md 본문

    • Claude가 스킬이 관련 있다고 판단할 때 로드됨
    • 실제 작업 절차와 지침이 포함됨

  • 3단계: 연결된 파일

    • references, scripts, assets 등
    • Claude가 필요하다고 판단한 경우에만 탐색
    • 토큰 사용량을 최소화하면서 전문성 유지
  • 이 구조를 통해 컨텍스트 비용과 작업 정확성의 균형을 달성함

• 핵심 설계 원칙 2: Composability

  • Claude는 여러 Skills를 동시에 로드할 수 있음
  • 따라서 각 Skill은:
    • 단독 실행을 전제로 가정하지 않아야 하며
    • 다른 Skill과 충돌하지 않도록 설계되어야 함
  • 스킬 간 협업이 가능한 환경을 기본 전제로 삼음

• 핵심 설계 원칙 3: Portability

  • Skills는 Claude.ai, Claude Code, API 환경에서 동일하게 동작하도록 설계됨
  • 한 번 만든 Skill을 플랫폼별 수정 없이 재사용 가능
  • 단, 스크립트나 네트워크 접근 등은 실행 환경의 제약을 받음

• MCP와 Skills의 관계

  • MCP를 사용하는 경우, Skills는 지식 계층(knowledge layer) 역할을 수행함
  • MCP는 도구와 데이터 접근을 제공
  • Skills는 그 도구를 어떻게 사용해야 하는지를 정의함

  • 주방 비유

    • MCP: 주방, 재료, 조리 도구
    • Skills: 레시피
    • 둘이 결합될 때 사용자는 복잡한 과정을 직접 설계하지 않아도 됨

• MCP 없이 사용하는 경우

  • MCP 없이도 Skills는 충분히 유용함
  • Claude의 내장 기능(문서 생성, 코드 실행 등)만으로도:
    • 반복 작업 표준화
    • 품질 일관성 확보
    • 작업 속도 개선 가능

• 이 장의 핵심 메시지

• Skills는 단기적인 프롬프트 최적화가 아니라, 지속적으로 축적되는 작업 자산
• “무엇을 할 수 있는가”보다 “어떻게 해야 하는가를 고정하는 것”이 핵심
• 이후 챕터들은 이 개념을 바탕으로, 실제 설계·운영 단계로 확장됨

챕터 2: 계획과 설계 (Planning and Design)

• 이 장은 Skills 구축의 성패가 작성 단계 이전의 설계 품질에서 거의 결정된다는 점을 전제로 함
• 기술 구현보다 먼저, 어떤 문제를 해결할지와 어떤 흐름을 고정할지를 명확히 해야 함
• 잘 설계된 Skill은 구현이 단순해지고, 테스트와 유지보수 비용도 크게 줄게 됨

• 출발점: 사용 사례 정의

  • 스킬을 작성하기 전, 반드시 2~3개의 구체적인 사용 사례(use case) 를 정의해야 함
  • 사용 사례는 추상적인 목적이 아니라, 실제 사용자가 말할 문장과 결과까지 포함해야 함

  • 좋은 사용 사례의 구성 요소

    • 사용자가 달성하고자 하는 목표
    • 사용자가 말할 법한 트리거 문장
    • 내부적으로 수행해야 할 단계적 작업
    • 사용되는 도구(Claude 기본 기능 또는 MCP)
    • 최종 결과 상태
  • 예시를 통해, “스프린트 계획 수립”처럼 시작 조건–처리 단계–완료 상태가 명확한 정의가 중요함을 강조함

• 설계 전 자문해야 할 핵심 질문

  • 사용자는 무엇을 끝내고 싶은가
  • 그 결과를 위해 어떤 다단계 워크플로가 필요한가
  • 어떤 단계에서 어떤 도구가 필요한가
  • 사람의 판단이 필요한 도메인 지식이나 모범 사례를 어디에 내재화할 것인가
  • 이 질문에 명확히 답하지 못하면 Skill로 고정할 준비가 되지 않은 상태임

• 관찰된 주요 Skill 사용 사례 유형

  • Category 1: 문서 및 자산 생성

    • 일관된 품질이 중요한 산출물 생성에 사용됨
    • 문서, 프레젠테이션, 디자인, 코드, UI 산출물 등이 포함됨
    • 특징:
      • 스타일 가이드와 브랜드 규칙 내장
      • 출력 템플릿 활용
      • 최종 품질 체크리스트 포함
    • 외부 도구 없이 Claude 기본 기능만으로 완결 가능

  • Category 2: 워크플로 자동화

    • 여러 단계를 반복적으로 수행해야 하는 프로세스에 적합
    • 예: skill-creator
    • 특징:
      • 단계별 진행과 검증 지점 포함
      • 구조화된 템플릿 제공
      • 중간 리뷰와 개선 루프 내장
    • 결과보다 과정의 안정성을 중시하는 유형으로 설명됨

  • Category 3: MCP 강화

    • MCP 서버가 제공하는 도구 접근을 실제 사용 가능한 워크플로로 전환
    • 특징:
      • 여러 MCP 호출을 순차적으로 조합
      • 사용자가 직접 명시하지 않아도 되는 컨텍스트 자동 보완
      • MCP 오류 상황에 대한 처리 내장
    • 단순 자동화가 아니라 전문화된 사용법 캡슐화로 정의됨

• 성공 기준 정의의 중요성

  • Skill은 “잘 작동하는 것처럼 보임”이 아니라, 개선 효과가 있는지로 평가해야 함
  • 성공 기준은 정밀한 수치가 아니라, 방향성을 가진 기준으로 제시됨

  • 정량적 기준

    • 의도된 요청의 대부분에서 자동으로 트리거됨
    • 스킬 사용 시 도구 호출 수와 토큰 사용량 감소
    • MCP 호출 실패 없이 워크플로 완료

  • 정성적 기준

    • 사용자가 다음 단계를 지시하지 않아도 진행됨
    • 반복 실행 시 결과 구조와 품질이 일관됨
    • 신규 사용자도 첫 시도에서 성공 가능
  • 평가에는 어느 정도 감각적 판단(vibes) 이 포함될 수 있음을 인정하되, 비교 기준은 유지해야 함을 명시함

• 기술 요구사항 개요

  • Skill은 고정된 디렉터리 구조를 따라야 함
  • SKILL.md 파일은 필수이며, 이름은 정확히 일치해야 함
  • 폴더명과 name 필드는 kebab-case 사용
  • Skill 폴더 내부에 README.md를 두지 않음

• YAML frontmatter의 역할

  • frontmatter는 Claude가 스킬을 언제 로드할지 판단하는 핵심 신호
  • 최소 요구 필드:
    • name
    • description
  • description은 반드시 다음을 포함해야 함:
    • 스킬이 무엇을 하는지
    • 언제 사용하는지
    • 사용자가 말할 법한 구체적 표현
  • 기술적 설명보다 사용자 관점의 언어가 중요함

• frontmatter 설계 원칙

  • 1024자 이내 유지
  • XML 태그 사용 금지
  • 보안 이유로 특정 이름(claude, anthropic) 사용 제한
  • 메타데이터는 선택 사항이나, 버전·작성자 정보 포함 권장

• SKILL.md 본문 설계 방향

  • 단계별로 명확하고 실행 가능한 지침 제공
  • 예시와 기대 결과를 함께 제시
  • 자주 발생하는 오류와 해결 방법 포함
  • 과도한 설명은 references 디렉터리로 분리
• Chapter 2는 Skills를 “프롬프트 묶음”이 아니라, 의도를 가진 워크플로 설계 산출물로 다뤄야 한다는 게 핵심

챕터 3: 테스트와 반복 개선 (Testing and Iteration)

• 이 장은 Skills를 실제로 신뢰할 수 있는 수준으로 끌어올리는 과정에 초점을 둠
• 스킬은 작성 자체보다, 언제 로드되고 어떻게 실행되며 결과가 개선되는지를 검증하는 과정이 핵심
• 사용 범위와 영향도에 따라 테스트 강도를 조절해야 한다는 점이 중요

• 테스트 수준 선택

  • Skills 테스트는 요구되는 품질과 배포 범위에 따라 서로 다른 수준으로 수행 가능함

  • 수동 테스트 (Claude.ai)

    • Claude.ai에서 직접 질의를 입력해 동작 확인
    • 별도 설정 없이 빠른 반복 가능
    • 초기 설계 검증과 빠른 수정에 적합

  • 스크립트 기반 테스트 (Claude Code)

    • Claude Code 환경에서 테스트 케이스를 자동화
    • 변경 사항이 누적되는 경우 회귀 테스트에 유용
    • 내부 팀 사용 스킬에 적합

  • API 기반 프로그램 테스트

    • Skills API를 활용해 정의된 테스트 세트를 자동 실행
    • 정량적 비교와 체계적 검증 가능
    • 대규모 배포, 엔터프라이즈 환경에 적합
• 내부용 소규모 스킬과 외부 공개 스킬은 동일한 테스트 기준을 요구하지 않음

• 권장 접근법: 하나의 어려운 작업부터

  • 효과적인 스킬 제작자는 하나의 까다로운 작업에 집중해 반복 개선함
  • Claude가 해당 작업을 안정적으로 성공시키는 순간의 접근 방식을 추출해 Skill로 고정
  • 광범위한 테스트보다 강한 신호를 주는 단일 사례 반복이 더 빠른 학습을 제공함
  • 이후에야 다양한 케이스로 확장 테스트 수행

• 핵심 테스트 영역

  • 1. 트리거 테스트

    • 목적: 스킬이 적절한 상황에서만 자동 로드되는지 검증
    • 포함 항목:
      • 명확한 요청에서 트리거됨
      • 표현이 바뀐 요청에서도 트리거됨
      • 무관한 요청에서는 로드되지 않음
    • 트리거 품질은 description 필드 설계와 직결됨

  • 2. 기능 테스트

    • 목적: 스킬이 의도한 결과를 정확히 생성하는지 확인
    • 검증 대상:
      • 출력 결과의 정확성
      • MCP 호출 성공 여부
      • 오류 처리 동작
      • 엣지 케이스 대응
    • 단순 성공 여부가 아니라 전체 워크플로 완결성을 기준으로 평가함

  • 3. 성능 비교 테스트

    • 목적: 스킬 사용 전후의 실질적 개선 효과 확인
    • 비교 항목:
      • 메시지 왕복 횟수
      • MCP 호출 실패 여부
      • 총 토큰 사용량
    • 스킬은 “작동함”이 아니라 “더 나아짐”을 증명해야 함

• skill-creator를 활용한 테스트와 개선

  • skill-creator는 스킬 설계와 개선을 돕는 메타 도구
  • 주요 기능:
    • 자연어 설명 기반 스킬 초안 생성
    • SKILL.md 형식과 frontmatter 자동 생성
    • 트리거 과다/부족 위험 탐지
    • 목적에 맞는 테스트 케이스 제안
  • 실행 테스트나 정량 평가를 대신하지는 않음

• 피드백 기반 반복 개선

  • Skills는 고정 산출물이 아닌 지속적으로 다듬어야 할 대상

  • 트리거 부족 신호

    • 스킬이 자동으로 로드되지 않음
    • 사용자가 수동으로 스킬을 켬
    • “이건 언제 쓰는 건가”라는 질문 발생
    • 해결책: description에 구체적 표현과 용어 추가

  • 트리거 과다 신호

    • 무관한 질문에도 스킬이 로드됨
    • 사용자가 스킬을 끄는 경우 발생
    • 목적 혼란 발생
    • 해결책: 범위 축소, 부정 트리거 추가

  • 실행 문제 신호

    • 결과 일관성 부족
    • MCP 오류 또는 재시도 발생
    • 사용자 수정 개입 필요
    • 해결책: 지침 명확화, 오류 처리 강화

• 테스트 단계의 핵심 메시지

  • 테스트는 스킬의 정확성뿐 아니라 신뢰성을 검증하는 과정임
  • “스킬이 실행된다”는 기준은 충분하지 않음
  • “사용자가 다음 지시를 하지 않아도 끝까지 완주하는가”가 최종 판단 기준
• Chapter 3은 Skills를 실험적 도구에서 운영 가능한 워크플로 자산으로 전환하는 단계

챕터 4: 배포와 공유 (Distribution and Sharing)

• Skills는 MCP 커넥터의 가치를 완성하는 요소로, 동일한 도구 연결이라도 스킬이 함께 제공되는 경우 더 빠른 가치 도달이 가능함
• 사용자 입장에서는 MCP만 제공되는 커넥터보다, 즉시 실행 가능한 워크플로를 포함한 커넥터를 선호하는 경향이 나타남
• 이 장은 2026년 1월 기준의 배포 방식, 조직 단위 배포, API 활용, 그리고 권장 운영 전략을 정리함

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

  • 개인 사용자 기준 배포 방식

    • Skill 폴더를 로컬에 다운로드
    • 필요 시 폴더 전체를 zip 파일로 압축
    • Claude.ai에서 Settings → Capabilities → Skills 경로로 업로드
    • 또는 Claude Code 환경의 skills 디렉터리에 직접 배치
    • 업로드 이후 사용자가 직접 스킬을 활성화해야 함

  • 조직 단위 배포

    • 관리자가 워크스페이스 전체에 스킬을 배포 가능
    • 2025년 12월 18일부터 조직 단위 배포 기능 제공
    • 중앙 집중식 관리와 자동 업데이트 지원
    • 조직 내부 표준 워크플로를 강제하거나 일관되게 유지하는 데 적합함

• 오픈 스탠다드로서의 Skills

  • Agent Skills는 MCP와 동일하게 오픈 스탠다드로 공개됨
  • 특정 플랫폼에 종속되지 않고, 동일한 스킬이 여러 AI 도구에서 동작하는 것을 목표로 함
  • 일부 스킬은 특정 플랫폼 기능을 적극 활용할 수 있으며, 이 경우 compatibility 필드에 환경 제약을 명시 가능
  • 생태계 참여자들과 협업을 통해 표준을 발전시키는 중임

• API를 통한 Skills 활용

  • API 활용 목적

    • 애플리케이션, 자동화 파이프라인, 에이전트 시스템 등 프로그램 기반 사용 시나리오에 적합
    • UI를 통한 수동 사용이 아닌, 시스템 레벨에서 스킬을 제어 가능

  • 주요 기능

    • /v1/skills 엔드포인트를 통해 스킬 목록 조회 및 관리
    • Messages API 요청 시 container.skills 파라미터로 스킬 지정
    • Claude Console을 통한 버전 관리 및 배포 제어
    • Claude Agent SDK와 연동해 커스텀 에이전트 구성 가능

  • 사용 환경 선택 가이드

    • Claude.ai / Claude Code:
      • 최종 사용자 직접 사용
      • 개발 중 수동 테스트 및 빠른 반복
      • 개인 단위, 비정기적 워크플로
    • API:
      • 애플리케이션 내장
      • 대규모 프로덕션 배포
      • 자동화된 에이전트 및 파이프라인

  • 주의 사항

    • API 기반 Skills 사용 시 Code Execution Tool 베타 필요
    • 보안된 실행 환경이 전제됨

• 권장 배포 전략

  • 1. GitHub 공개 저장소 운영

    • 스킬 자체는 하나의 폴더로 관리
    • 저장소 루트에는 사람을 위한 README 제공
    • 설치 방법, 사용 목적, 예시 스크린샷 포함 권장
    • Skill 폴더 내부에는 README.md를 포함하지 않음

  • 2. MCP 문서와 연계

    • MCP 커넥터 문서에서 Skill을 함께 소개
    • MCP 단독 사용 대비 Skill 결합 시의 가치를 명확히 설명
    • 빠른 시작 가이드 제공

  • 3. 설치 가이드 제공

    • 스킬 다운로드 방법 명시
    • Claude.ai 또는 Claude Code에 설치하는 단계별 안내
    • MCP 서버 연결 확인 절차 포함
    • 간단한 테스트 프롬프트 예시 제공

• 스킬 포지셔닝 원칙

  • 기능이 아닌 결과 중심 설명

    • 내부 구현이나 기술 구조 설명보다, 사용자가 얻는 결과를 강조
    • 시간 절약, 오류 감소, 일관성 확보 같은 효과를 전면에 배치

  • MCP + Skills 조합이 중요

    • MCP는 도구 접근을 제공
    • Skills는 해당 도구를 어떻게 써야 하는지에 대한 지식을 제공
    • 두 요소가 결합될 때 AI 기반 자동화가 완성됨
• 배포와 공유는 단순 전달이 아니라, 사용자가 스킬의 가치를 이해하고 즉시 활용할 수 있도록 만드는 과정

Chapter 5: 패턴과 문제 해결 (Patterns and Troubleshooting)

• 이 장은 초기 Skills 사용자와 내부 팀 사례에서 반복적으로 효과가 입증된 설계 패턴과, 실제 운영 중 자주 발생하는 문제 해결 방법을 정리함
• 제시된 패턴은 규범이 아니라 검증된 접근 방식의 묶음이며, 각 스킬의 목적에 맞게 선택·조합하는 것을 전제로 함
• 핵심 메시지는 “도구를 연결하는 것”이 아니라, 문제를 해결하는 흐름을 설계하는 것에 있음

• 접근 방식 선택: 문제 중심 vs 도구 중심

  • Skills 설계는 두 가지 관점 중 하나를 택하는 것이 중요함

  • 문제 중심(Problem-first)

    • 사용자는 달성하고 싶은 결과를 말함
    • 스킬이 내부적으로 적절한 MCP 도구와 호출 순서를 결정함
    • 예: “프로젝트 워크스페이스를 만들어줘” → 스킬이 모든 도구 호출을 처리
    • 결과 지향적 경험에 적합

  • 도구 중심(Tool-first)

    • 사용자는 이미 MCP 연결을 알고 있음
    • 스킬은 해당 도구를 어떻게 잘 쓰는지에 대한 전문 지식을 제공
    • 예: Notion MCP 사용법, 최적 워크플로 안내
    • 전문가 사용자, 내부 도구 가이드에 적합
• 대부분의 스킬은 이 중 한쪽에 더 가까우며, 이를 명확히 인식하는 것이 설계 품질을 좌우함

• 패턴 1: 순차 워크플로 오케스트레이션

  • 정해진 순서로 여러 단계를 반드시 수행해야 하는 경우에 적합
  • 각 단계는 이전 단계 결과에 의존함
  • 단계별 검증과 실패 시 롤백 지침 포함 가능
  • 온보딩, 계정 생성, 구독 설정 같은 업무에 적합

• 패턴 2: 다중 MCP 협업

  • 하나의 결과를 위해 여러 서비스(MCP)를 연속적으로 사용해야 하는 경우
  • 단계별로 MCP를 분리하고, 데이터 전달 흐름을 명확히 정의
  • 다음 단계로 넘어가기 전 검증 필수
  • 디자인 → 저장 → 태스크 생성 → 알림 같은 복합 워크플로에 적합

• 패턴 3: 반복 개선(Iterative Refinement)

  • 초기 결과보다 반복을 통해 품질이 크게 개선되는 작업에 적합
  • 초안 생성 → 검증 → 수정 → 재검증 루프를 명시적으로 설계
  • 품질 기준과 반복 종료 조건을 명확히 정의해야 함
  • 보고서 생성, 문서 품질 개선 작업에 효과적

• 패턴 4: 상황 인식 기반 도구 선택

  • 같은 목표라도 상황에 따라 최적 도구가 달라지는 경우에 사용
  • 파일 크기, 타입, 협업 여부 등 명확한 판단 기준 필요
  • 선택 이유를 사용자에게 설명해 신뢰성 확보
  • 스토리지, 문서 관리, 코드 저장 흐름에 적합

• 패턴 5: 도메인 특화 지능 내장

  • 단순 도구 호출을 넘어 전문 지식과 규칙을 내재화한 스킬
  • 작업 수행 전 판단·검증 단계가 핵심
  • 모든 결정 과정을 기록해 감사 추적 가능
  • 금융, 컴플라이언스, 보안 등 고위험 영역에 적합

• 문제 해결 가이드

  • 업로드 실패

    • SKILL.md 파일명이 정확하지 않은 경우 발생
    • YAML 구분자(---) 누락, 따옴표 미종료 등 형식 오류가 원인
    • name 필드에 대문자, 공백 포함 시 업로드 거부됨

  • 스킬이 트리거되지 않는 경우

    • description이 너무 추상적이거나 사용자 표현을 반영하지 못한 경우
    • 실제 사용자가 말할 법한 문구를 포함하도록 수정 필요
    • Claude에게 “이 스킬은 언제 사용하나”를 물어 디버깅 가능

  • 스킬이 과도하게 트리거되는 경우

    • 범위가 지나치게 넓은 description이 원인
    • 부정 트리거(Do NOT use when…) 추가
    • 처리 대상과 제외 대상을 명확히 구분

  • MCP 호출 실패

    • MCP 서버 연결 상태 확인
    • 인증 정보(API 키, OAuth 토큰) 점검
    • 스킬 없이 MCP 단독 호출로 문제 원인 분리
    • 도구 이름의 대소문자 정확성 확인

  • 지침이 잘 지켜지지 않는 경우

    • 지침이 지나치게 장황하거나 핵심이 묻힌 경우
    • 중요한 조건은 상단에 배치하고 반복 강조
    • 모호한 표현 대신 검증 가능한 조건 목록 사용
    • 중요한 검증은 스크립트로 구현하는 것이 더 안정적임

  • 대규모 컨텍스트로 인한 성능 저하

    • SKILL.md가 과도하게 큰 경우 발생
    • 상세 문서는 references로 분리
    • 동시에 활성화된 스킬 수가 과도한 경우 축소 권장
    • 20~50개 이상의 스킬 동시 활성화는 성능 저하 가능성 존재
• “스킬은 한 번 만들고 끝나는 artefact가 아니라, 패턴 선택과 반복 개선을 통해 성숙해지는 운영 대상”

댓글

kaydash 28일전 앤트로픽이 짱이다 정말

pluto 27일전 진짜