# Claude Skills 구축을 위한 완벽 가이드 > Clean Markdown view of GeekNews topic #26328. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=26328](https://news.hada.io/topic?id=26328) - GeekNews Markdown: [https://news.hada.io/topic/26328.md](https://news.hada.io/topic/26328.md) - Type: news - Author: [neo](https://news.hada.io/@neo) - Published: 2026-02-02T10:02:01+09:00 - Updated: 2026-02-02T10:02:01+09:00 - Original source: [claude.com](https://claude.com/blog/complete-guide-to-building-skills-for-claude) - Points: 95 - Comments: 2 ## Summary **Claude Skills**는 반복되는 작업 흐름을 한 번 정의해 지속적으로 재사용할 수 있도록 설계된 **워크플로 지식 패키지**입니다. 앤트로픽이 공개한 33쪽짜리 가이드 문서로 스킬의 설계·테스트·배포 전 과정을 실무 중심으로 다루며, MCP 통합을 통해 “무엇을 할 수 있는가”보다 “**어떻게 해야 하는가**”를 고정하는 구조를 제시합니다. ## Topic Body - **Claude Skills**는 반복되는 작업 흐름을 한 번 정의해 **지속적으로 재사용**하도록 설계된 워크플로 지식 패키지 - 앤트로픽이 직접 작성한 **[33p PDF 가이드](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.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가 아니라, **패턴 선택과 반복 개선을 통해 성숙해지는 운영 대상**” ## Comments ### Comment 50450 - Author: kaydash - Created: 2026-02-02T12:19:32+09:00 - Points: 1 앤트로픽이 짱이다 정말 ### Comment 50497 - Author: pluto - Created: 2026-02-03T07:34:33+09:00 - Points: 1 - Parent comment: 50450 - Depth: 1 진짜