AI 에이전트에게 복잡한 작업을 맡기고 싶지만 믿고 맡기기엔 불안한 경험, 다들 있으시죠? Claude Skills는 이 문제에 대한 Anthropic의 답입니다. 자동화의 편리함과 사용자의 통제권, 두 마리 토끼를 잡는 실용적 접근법이죠.

개발자 Han-chung Lee가 Claude Skills의 내부 구조를 역설계(reverse engineering)하여 작성한 심층 분석 글입니다. Skills의 프롬프트 구조, 메타-툴 아키텍처, 실제 API 호출 과정을 상세히 다루며, 개발자들이 직접 활용할 수 있는 구체적인 구현 패턴을 제시합니다.

출처: Claude Agent Skills: A First Principles Deep Dive – leehanchung.github.io

Skills는 코드가 아니라 프롬프트입니다

Claude Skills의 핵심을 한 문장으로 정리하면 이렇습니다. “Skills는 실행 가능한 코드가 아니라 대화 맥락에 주입되는 특수한 프롬프트 템플릿이다.” Python이나 JavaScript를 실행하지 않고, HTTP 서버를 띄우지도 않습니다. 대신 도메인 특화 지시사항을 대화 맥락에 주입해서 Claude의 행동 방식을 변경하죠.

일반 툴들과 비교하면 차이가 명확합니다. Read, Write, Bash 같은 도구들은 즉각적인 동작을 실행하고 결과를 반환해요. 파일을 읽거나, 명령을 실행하거나, 내용을 쓰는 식입니다. Skills는 다르게 작동합니다. 동작을 직접 실행하는 대신 Claude가 특정 문제를 풀 수 있도록 “준비”시키죠.

예를 들어 PDF 처리 skill이 호출되면, 시스템은 “PDF 전문가로서 작동하라”는 상세한 지시사항을 대화에 주입합니다. 어떤 도구를 사용할 수 있는지, 어떤 순서로 작업을 진행해야 하는지, 출력은 어떤 형식으로 해야 하는지 등을 담은 마크다운 문서가 Claude의 맥락에 들어가는 겁니다.

메타-툴 아키텍처: Skill 안에 skills가 있다

Skills 시스템의 영리한 설계는 “메타-툴” 구조에 있습니다. Skill이라는 이름의 대문자 S 툴이 있고, 이것이 개별 skills들(pdf, skill-creator, internal-comms 등)을 관리하는 컨테이너 역할을 합니다.

Claude가 요청을 받으면 세 가지를 받습니다. 사용자 메시지, 사용 가능한 도구들(Read, Write, Bash 등), 그리고 Skill 툴. 이 Skill 툴의 설명에는 모든 사용 가능한 skill들의 이름과 설명이 포맷된 리스트로 들어있어요. Claude는 이 리스트를 읽고 자연어 이해 능력으로 사용자 의도와 매칭시킵니다.

여기서 중요한 점은 알고리즘적 라우팅이 전혀 없다는 겁니다. 임베딩도, 분류기도, 패턴 매칭도 사용하지 않아요. 순수하게 LLM 추론만으로 결정합니다. “로그 작성 skill을 만들어줘”라고 하면 Claude가 skill 설명들을 읽고 internal-comms skill이 맞다고 판단해서 호출하는 식이죠.

두 개의 메시지: 보이는 것과 보이지 않는 것

Skills가 실행되면 대화 기록에 두 개의 사용자 메시지가 주입됩니다. 하나는 메타데이터로 isMeta: false가 설정되어 UI에 표시되고, 다른 하나는 전체 skill 프롬프트로 isMeta: true가 설정되어 UI에는 숨겨지지만 API에는 전송됩니다.

왜 이렇게 나눴을까요? 한 메시지로 처리하면 불가능한 선택을 해야 하기 때문입니다. isMeta: false로 하면 수천 단어의 AI 지시사항이 사용자 채팅창에 쏟아지고, isMeta: true로 하면 어떤 skill이 실행되는지 전혀 알 수 없죠.

첫 번째 메시지는 간결한 XML 구조입니다.

<command-message>The "pdf" skill is loading</command-message>
<command-name>pdf</command-name>
<command-args>report.pdf</command-args>

사용자는 “PDF skill이 로딩 중”이라는 상태만 봅니다. 보통 50~200자 정도죠.

두 번째 메시지는 완전히 다릅니다. SKILL.md 파일의 전체 내용을 로드해서 500~5,000단어에 달하는 상세 가이드를 Claude에게 제공합니다. 작업 맥락, 워크플로우, 사용 가능한 도구, 출력 형식, 환경별 경로 등을 담고 있어요. isMeta: true 덕분에 이 프롬프트는 API로 전송되지만 사용자 화면에는 나타나지 않습니다.

SKILL.md 구조: 프론트매터와 콘텐츠

Skill을 만드는 핵심은 SKILL.md 파일입니다. 이 파일은 두 부분으로 나뉩니다. 프론트매터(YAML 형식)가 “어떻게” 실행할지 설정하고, 마크다운 콘텐츠가 “무엇을” 할지 Claude에게 알려줍니다.

프론트매터의 필수 필드는 name과 description입니다. description이 가장 중요한데, Claude가 skill을 선택할 때 주요 신호로 사용하기 때문이죠. “이 skill은 사용자가 새 skill을 만들고 싶을 때 사용해야 합니다”처럼 명확하고 행동 지향적인 언어가 효과적입니다.

allowed-tools 필드는 skill이 사용자 승인 없이 사용할 수 있는 도구들을 정의합니다. 쉼표로 구분된 문자열인데, "Read,Write,Bash,Glob,Grep,Edit" 같은 식으로 넓은 권한을 줄 수도 있고, "Bash(git status:*),Bash(git diff:*)" 처럼 특정 git 명령만 허용할 수도 있어요. 보안상 실제로 필요한 것만 포함하는 게 중요합니다.

model 필드로 특정 모델을 요청할 수도 있습니다. 기본값은 현재 세션의 모델을 상속받지만, 복잡한 코드 리뷰 같은 작업에는 "claude-opus-4-20250514" 같은 더 강력한 모델을 지정할 수 있죠.

마크다운 콘텐츠는 Claude가 받는 실제 프롬프트입니다. 5,000단어 이내로 유지하고, 명령형 언어를 사용하며, 상세한 내용은 외부 파일을 참조하는 게 좋습니다. {baseDir} 변수를 사용하면 skill 설치 디렉토리를 동적으로 참조할 수 있어요.

실행 맥락 수정: 도구 권한과 모델 전환

Skills의 진짜 힘은 실행 맥락(execution context)을 수정한다는 점입니다. Skill이 호출되면 대화 맥락에 프롬프트를 주입할 뿐만 아니라 도구 권한을 변경하고 모델을 전환합니다.

예를 들어 PDF skill이 allowed-tools: "Bash(pdftotext:*),Read,Write"를 지정했다면, 이 도구들은 skill 실행 중 자동 승인됩니다. 사용자가 매번 “이 명령을 실행해도 될까요?”라는 프롬프트를 받지 않아도 되죠. 권한은 skill 실행 기간에만 유효하고, 작업이 끝나면 정상 상태로 돌아갑니다.

기술적으로 이건 contextModifier 함수를 통해 구현됩니다. Skill 툴이 결과를 반환할 때 이 함수도 함께 반환하는데, 이 함수가 맥락 객체를 수정해서 허용된 도구들을 사전 승인 규칙에 추가하고, 필요시 모델을 오버라이드합니다.

contextModifier(context) {
  let modified = context;

  if (allowedTools.length > 0) {
    modified = {
      ...modified,
      async getAppState() {
        const state = await context.getAppState();
        return {
          ...state,
          toolPermissionContext: {
            ...state.toolPermissionContext,
            alwaysAllowRules: {
              ...state.toolPermissionContext.alwaysAllowRules,
              command: [
                ...state.toolPermissionContext.alwaysAllowRules.command || [],
                ...allowedTools  // 이 도구들을 사전 승인
              ]
            }
          }
        };
      }
    };
  }

  return modified;
}

리소스 번들링: scripts/, references/, assets/

Skills는 SKILL.md만으로도 작동하지만, 지원 리소스를 함께 번들링하면 훨씬 강력해집니다. 표준 구조는 세 디렉토리를 사용합니다.

scripts/ 디렉토리에는 실행 가능한 Python이나 Bash 스크립트를 넣습니다. 자동화 스크립트, 데이터 프로세서, 검증기 같은 것들이죠. skill-creator의 init_skill.py 스크립트가 좋은 예입니다. 새 skill 디렉토리를 생성하고, SKILL.md 템플릿을 만들고, 예제 리소스 디렉토리를 추가하는 작업을 자동화합니다.

references/ 디렉토리는 Claude가 맥락에 읽어들일 문서를 저장합니다. 마크다운 파일, JSON 스키마, 설정 템플릿 같은 텍스트 콘텐츠입니다. SKILL.md에 모든 걸 넣으면 너무 길어지니까, 상세한 문서는 여기 두고 필요할 때 Read({baseDir}/references/best_practices.md) 같은 식으로 로드합니다.

assets/ 디렉토리는 Claude가 경로만 참조하고 맥락에는 로드하지 않는 파일들입니다. HTML 템플릿, CSS 파일, 이미지, 설정 보일러플레이트 같은 것들이죠. 10KB 마크다운 파일을 references/에 두면 맥락 토큰을 소비하지만, 10KB HTML 템플릿을 assets/에 두면 소비하지 않습니다.

실전 활용 패턴

글에서는 여러 실용적 패턴을 소개합니다.

스크립트 자동화 패턴은 복잡한 다단계 작업을 Python이나 Bash 스크립트로 처리합니다. skill 프롬프트가 Claude에게 스크립트를 실행하고 출력을 처리하라고 지시하죠.

읽기-처리-쓰기 패턴은 가장 단순합니다. 입력을 읽고, 지시사항에 따라 변환하고, 출력을 씁니다. 형식 변환이나 데이터 정리에 유용해요.

검색-분석-보고 패턴은 코드베이스를 분석할 때 씁니다. Grep으로 패턴을 찾고, 매칭된 파일을 읽고, 결과를 분석해서 구조화된 보고서를 생성합니다.

마법사 스타일 다단계 워크플로우는 사용자 입력이 필요한 복잡한 프로세스를 단계별로 나눕니다. 각 단계마다 명시적인 확인을 받으면서 진행하죠.

한계와 의미

이 설계에는 트레이드오프가 있습니다. Skills는 동시성 안전하지 않고, 각 호출마다 1,500토큰 이상의 오버헤드가 있으며, 모든 걸 프롬프트로 표현해야 하는 제약이 있습니다. 하지만 그 대가로 유연성, 안전성, 조합 가능성을 얻습니다.

특수 지식을 “실행되는 코드”가 아니라 “맥락을 수정하는 프롬프트”와 “권한을 변경하는 설정”으로 다루면서, 전통적인 함수 호출로는 어려운 유연함을 달성했습니다. 사용자가 통제권을 유지하면서도 복잡한 워크플로우를 자동화할 수 있는 실용적 접근법이죠.

개발자 관점에서 보면 이건 AI 에이전트의 미래 방향을 보여줍니다. “모든 걸 자동화하라”가 아니라 “중요한 결정은 사람이, 반복 작업은 AI가” 하는 협업 모델입니다. 그리고 그걸 코드가 아니라 프롬프트로 구현한다는 게 흥미롭죠.

참고자료:

• Introducing Agent Skills – Anthropic
• Equipping Agents for the Real World with Agent Skills – Anthropic Engineering Blog
• Claude Code Documentation – Claude Docs
• Skill Creator Skill – GitHub

Like?