▲

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

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

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 하나를 완성할 수 있도록 설계됨
    • 상위 2~3개의 명확한 워크플로가 있는 경우, 첫 Skill은 약 15~30분 내 구축 및 테스트 가능
    • 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 3시간전  [-]

앤트로픽이 짱이다 정말

답변달기