🛠️ 클로드 스킬 완전 정복 — AI에게 업무 매뉴얼을 폴더째 주입하는 법

 

"또 처음부터 설명해야 해요?" AI와 일하다 보면 반드시 부딪히는 벽

AI를 매일 쓰다 보면 이상하게 피곤해지는 순간이 옵니다.

분명 어제도 같은 작업을 했는데, 오늘 새 대화를 열면 또 처음부터 설명해야 해요. "우리 회사는 이런 톤으로 써야 해요." "보고서 형식은 이렇게 해주세요." "이 용어는 이런 의미예요." 클로드는 분명 똑똑한데, 대화가 새로 시작되면 이 모든 게 초기화됩니다.

그리고 결국 사람이 AI의 매뉴얼 역할을 반복합니다.

이 문제를 근본적으로 해결하는 기능이 있어요. 바로 클로드 스킬(Claude Skills), 또는 에이전트 스킬(Agent Skills)입니다. Anthropic이 2025년 10월 16일에 공개한 이 기능은 클로드에게 업무 매뉴얼을 폴더째로 주입하는 방법입니다. 한 번 만들어두면 관련 작업이 들어올 때마다 클로드가 자동으로 꺼내 씁니다.

개발자 출신이라면 이게 왜 강력한지 바로 감이 옵니다. 함수 하나 잘 짜놓고 매번 import해서 쓰는 것과 같은 논리입니다.

클로드 스킬이 정확히 뭐냐고요

한마디로 설명하면, 스킬은 폴더 하나입니다. 그 안에 SKILL.md 파일 하나만 있으면 최소한의 스킬로 작동합니다.

기본 구조는 이렇습니다. 최상단에 SKILL.md 파일이 있고, 선택적으로 scripts 폴더(Python, Bash 등 실행 스크립트), references 폴더(API 가이드, 참고 문서), assets 폴더(템플릿, 폰트, 아이콘)를 넣을 수 있습니다.

주의할 사항이 있습니다. 폴더명은 반드시 소문자 하이픈 방식인 kebab-case로 작성해야 합니다. "my-skill"은 되지만 "My Skill"이나 "my_skill"은 안 됩니다. 파일명도 정확히 "SKILL.md"여야 하고, 소문자로 쓰면 인식이 안 됩니다. 그리고 스킬 폴더 안에 README.md를 넣으면 안 됩니다. 모든 설명은 SKILL.md 안에 담아야 합니다.

핵심 중의 핵심은 description 작성법

SKILL.md 파일 맨 위에는 YAML 형식의 프론트매터가 들어갑니다. 이 부분이 스킬 자동 활성화의 전부를 결정합니다.

name 필드는 kebab-case로만 쓸 수 있고, description은 1024자 이내입니다. description에는 반드시 두 가지가 들어가야 합니다. 이 스킬이 무엇을 하는지, 그리고 언제 쓰는지입니다. 둘 중 하나라도 빠지면 클로드가 이 스킬을 꺼내야 할 타이밍을 판단하지 못합니다.

나쁜 예시는 이렇습니다. "블로그 작성을 도와줍니다." 이 설명으로는 클로드가 언제 써야 할지 전혀 감을 못 잡습니다.

좋은 예시는 이렇습니다. "한국어 블로그 글을 SEO 최적화해서 작성합니다. 블로그 써줘, 네이버 포스트, 티스토리 글 등을 언급할 때 사용합니다." 언제 발동되는지를 명확히 적어주는 게 핵심이에요.

스킬이 너무 자주 발동될 때는 부정 트리거를 추가합니다. "간단한 텍스트 정리에는 사용하지 마세요" 같은 문구를 description 안에 넣으면 됩니다. 반대로 잘 안 발동된다면 트리거 키워드를 더 구체적으로 늘려주면 됩니다.

점진적 공개라는 설계 원리, 왜 중요할까요

스킬의 핵심 설계 원리는 "점진적 공개(Progressive Disclosure)"입니다. 20~50개 스킬을 동시에 깔아도 컨텍스트 창이 불필요하게 낭비되지 않는 이유가 여기 있어요.

3단계로 작동합니다.

1단계는 YAML 프론트매터로, 항상 클로드의 시스템 프롬프트에 포함됩니다. 스킬이 존재한다는 최소 정보만 줍니다.

2단계는 SKILL.md 본문으로, 이 스킬이 지금 필요하다고 클로드가 판단할 때만 전체 내용을 불러옵니다. 상세 지침, 단계별 절차, 에러 처리 방법이 여기 들어갑니다.

3단계는 references 폴더 안의 파일들로, 실제로 필요할 때만 클로드가 찾아서 읽습니다.

덕분에 SKILL.md는 5,000 단어 이내로 유지하고, 상세 문서는 references 폴더에 넣고 링크만 걸어두는 것이 권장 방식입니다.

스킬 없을 때와 있을 때, 실제로 얼마나 차이 날까요

Anthropic의 공식 비교 자료를 보면 수치가 나옵니다.

스킬 없이 처리했을 때는 사용자가 매번 지침을 직접 제공해야 하고, 대화 왕복이 15회 발생하며, API 호출 실패가 3건, 토큰 소비는 12,000개였습니다.

스킬이 있을 때는 자동 워크플로우가 실행되고, 확인 질문이 2회, API 호출 실패 0건, 토큰 소비 6,000개였습니다.

토큰이 절반으로 줄고, 대화 왕복은 7분의 1 수준으로 줄었습니다. 반복 업무일수록, 도메인 전문 지식이 필요한 작업일수록 이 차이는 더 극명하게 나타납니다.

한국 개발자들이 별도로 진행한 테스트 결과도 흥미롭습니다. 단순 키워드 훅 방식의 자동 활성화율이 50% 수준에 그친 반면, 클로드가 스킬의 적합성을 명시적으로 판단하도록 유도하는 방식을 쓰면 80~84%까지 올라간다는 결과가 나왔습니다. description을 얼마나 구체적으로 쓰느냐가 그 차이를 만드는 겁니다.

실무에서 바로 쓸 수 있는 스킬 유형 3가지

Anthropic이 분류한 세 가지 카테고리가 있습니다. 내 업무에 어떤 스킬이 필요한지 여기서 판단하면 됩니다.

첫 번째는 문서와 산출물 생성입니다. 회의록, 제안서, 보고서, 블로그 글처럼 특정 형식이 반복되는 작업에 씁니다. 브랜드 가이드와 스타일 가이드를 한 번 심어두면 매번 일관된 결과물이 나옵니다.

두 번째는 워크플로우 자동화입니다. 여러 단계를 순서대로 처리해야 하는 작업입니다. "뉴스 URL 받아서 요약, 핵심 키워드 추출, 보고서 형식으로 정리"처럼 다단계 프로세스를 하나의 스킬로 묶을 수 있어요. 각 단계마다 검증 게이트를 두고, 실패 시 재시도 로직을 포함하는 것이 좋습니다.

세 번째는 MCP 연동 강화입니다. Notion, GitHub, Asana 같은 외부 서비스를 MCP로 연결했을 때, 그 서비스를 어떻게 써야 하는지 노하우를 스킬로 심어두는 방식입니다. MCP가 주방 도구를 제공한다면, 스킬은 레시피를 제공합니다. 둘이 합쳐져야 요리가 완성됩니다.

Anthropic 엔지니어가 실제로 쓰는 5가지 스킬 패턴

Anthropic 내부 팀이 수백 개의 스킬을 운영하면서 발견한 것은, 잘 작동하는 스킬들은 뚜렷한 카테고리 안에 속한다는 점입니다. 경계가 모호한 스킬일수록 잘 작동하지 않았습니다.

패턴 1은 순차적 워크플로우 오케스트레이션으로, 다단계 작업을 정해진 순서로 처리합니다. 각 단계를 번호로 명시하고, 단계 간 의존성과 롤백 조건을 지정합니다.

패턴 2는 다중 MCP 조율입니다. Figma에서 에셋 추출 후 Google Drive에 업로드하고, Linear에 개발 태스크를 만들고, Slack에 알림을 보내는 식의 멀티 서비스 연동 흐름입니다.

패턴 3은 반복 정제 방식입니다. 초안 생성, 검증, 이슈 식별, 수정, 재검증 루프입니다. 언제 반복을 멈출지 기준을 명시하는 것이 중요합니다.

패턴 4는 컨텍스트 인식 도구 선택으로, 파일 크기에 따라 저장 위치를 결정하거나, 문서 유형에 따라 처리 방식을 달리하는 식입니다.

패턴 5는 도메인 전문 지식 내장입니다. 보험 심사 기준, 결제 컴플라이언스 규칙처럼 도메인 지식이 경쟁력인 업종에서 특히 강력합니다. 이 패턴이야말로 스킬이 단순 자동화 툴을 넘어서는 지점입니다.

GPT 커스텀 GPTs와는 뭐가 다른가요

비슷해 보이는 개념들이 있어서 헷갈리는 분들이 많습니다.

CLAUDE.md는 "우리 회사에서는 항상 한국어로, 이 톤으로"처럼 모든 대화에 전역 적용되는 기본 원칙입니다. 스킬은 "블로그 글 쓸 때만 이 매뉴얼을"처럼 특정 상황에서만 켜지는 전문 지침이고요.

GPT의 커스텀 GPTs는 고정된 설정으로 배포되는 방식이지만, 클로드 스킬은 오픈 스탠다드 폴더 구조입니다. Claude.ai, Claude Code, API 어디서든 동일하게 작동합니다. 그리고 2025년 12월, Anthropic이 스킬 형식을 오픈 스탠다드로 공개하면서 OpenAI가 Codex CLI와 ChatGPT에 동일한 포맷을 채택하기도 했습니다. 같은 스킬 폴더가 여러 AI 플랫폼에서 돌아가는 시대가 온 겁니다.

스킬 배포와 팀 공유는 어떻게 하나요

개인이 만든 스킬은 Settings > Capabilities > Skills에서 zip 파일로 업로드합니다. 스킬 폴더를 압축하면 됩니다.

팀 단위로는 관리자가 워크스페이스 전체에 일괄 배포할 수 있습니다. 중앙에서 스킬을 관리하고 자동 업데이트가 가능하니, 조직 내 AI 사용 방식을 표준화하는 데 직접 활용할 수 있어요.

Git 저장소를 마켓플레이스처럼 운영하는 방법도 있습니다. 사내 Git 저장소에 스킬들을 올려두고 팀원들이 클론해서 쓰는 방식입니다. 최신 버전이 커밋될 때마다 팀 전체가 업데이트를 받을 수 있어서, 조직의 AI 업무 방식을 버전 관리할 수 있게 됩니다.

개발자라면 API 방식도 씁니다. /v1/skills 엔드포인트로 스킬을 관리하고, Messages API 호출 시 container.skills 파라미터로 지정합니다. CI 파이프라인에 스킬 업데이트를 자동화하는 것도 가능합니다.

스킬 시스템이 가져올 변화

Anthropic 엔지니어링 팀의 표현을 빌리면, 스킬은 "에이전트를 실전에 투입하기 위한 장비를 갖추는 것"입니다. AI가 단순 도구에서 실제 업무 파트너로 전환되는 시점에, 스킬이 그 전환을 가능하게 하는 인프라 역할을 합니다.

기업 입장에서는 조직의 업무 노하우를 스킬로 코드화하는 것이 점점 경쟁력이 됩니다. 신입이 들어와도 스킬 몇 개 활성화하면 시니어 수준의 맥락으로 AI를 쓸 수 있게 됩니다. 팀 전체가 일관된 방식으로 AI를 쓰면 산출물 품질 편차도 줄어듭니다.

Simon Willison 같은 AI 커뮤니티의 주요 인사들은 스킬이 MCP보다 더 큰 파급력을 가질 수도 있다고 평가합니다. 이유는 단순합니다. 포맷이 훨씬 간단하고, 별도 서버 설치 없이 폴더 하나만 만들면 되기 때문입니다.

마무리

클로드 스킬은 AI에게 업무 매뉴얼을 한 번 만들어주는 방법입니다. SKILL.md 파일 하나로 시작하고, description에 "무엇을 하는지 + 언제 쓰는지"를 구체적으로 써두는 것이 전부입니다.

프롬프트를 매번 새로 쓰는 건 소모이고, 스킬로 만들어두면 자산입니다. AI 도구의 경쟁력은 모델 자체보다 "얼마나 내 업무에 맞게 길들였냐"로 갈리고 있습니다. 반복되는 워크플로우가 하나라도 있다면, 지금 당장 스킬 하나를 만들어보세요. 15~30분이면 첫 번째 스킬이 완성됩니다.