Claude Code의 스킬 시스템이 실제로 작동하는 방식

에이전트 워크플로우 (agentic workflows)를 구축하는 엔지니어링 팀은 도구 통합의 "라스트 마일 (last mile)" 문제로 종종 어려움을 겪습니다. 일반적인 API 호출은 잘 알려져 있지만, 언어 모델 (language model)과 로컬 파일 시스템 (local filesystem) 사이의 가교 역할을 하려면 구조화된 탐색 메커니즘 (discovery mechanism)이 필요합니다. 이는 에이전트가 자신이 거주하는 환경의 구체적인 경계와 역량을 이해하도록 보장합니다. Claude Code는 스킬 (skills)을 프로젝트 계층 구조 내에서 탐색 가능한 자산으로 취급함으로써 이 문제를 해결합니다.

이러한 접근 방식은 중앙 에이전트 래퍼 (agent wrapper) 내부에 하드코딩된 함수를 사용하는 방식에서 벗어납니다. 대신, 도구가 조작하는 코드와 함께 존재하는 분산형 모델 (decentralized model)을 우선시합니다. 에이전트의 역량을 로컬 디렉토리 (local directory)에 고정함으로써, 개발자는 소스 코드나 CI/CD 파이프라인과 마찬가지로 AI의 특정 스킬 세트를 버전 관리 (version-control)할 수 있습니다.

아키텍처 개요: .claude/skills 디렉토리와 로컬 탐색 (Local Discovery)

Claude Code 아키텍처의 핵심은 .claude/skills 디렉토리입니다. CLI가 초기화될 때, 사용 가능한 도구 목록을 작성하기 위해 이 숨겨진 폴더를 재귀적으로 스캔 (recursive scan)합니다. 이 디렉토리 내의 각 파일은 에이전트가 작업 중에 호출할 수 있는 독립적인 기능 (standalone capability) 역할을 합니다. 이러한 로컬 우선 탐색 (local-first discovery) 방식은 에이전트가 벤더가 제공하는 정적이고 미리 정의된 도구 세트에 의존하지 않도록 보장하며, 대신 저장소의 특정 요구 사항에 적응하도록 합니다.

기저 모델의 효능이 이러한 자율 도구 시스템의 성공을 주도합니다. Anthropic Model Release Notes에 따르면, Claude 3.5 Sonnet은 소프트웨어 엔지니어링 작업을 위한 SWE-bench Verified 벤치마크에서 49.1%의 점수를 달성했습니다.

발견 메커니즘(discovery mechanism)은 파일 이름과 메타데이터를 파싱하여 로컬 도구 레지스트리(local tool registry)를 구축하는 방식으로 작동합니다. 개발자가 폴더에 새로운 TypeScript 또는 Python 스크립트를 추가하면, CLI는 다음 실행 시 이를 감지합니다. 이를 통해 핵심 CLI 바이너리(binary)를 다시 컴파일하거나 클라우드 설정을 업데이트할 필요 없이 빠른 반복(iteration)이 가능합니다. Leviathan(leviathanterminal.com)과 같은 시스템도 이와 유사한 패턴을 활용하여, 수동 등록이나 외부 배포 주기 없이도 특화된 스크립트가 실행 중인 에이전트(agent)에게 즉시 사용 가능하도록 보장합니다.

Anthropic Documentation에서는 Claude Code를 코드에 대해 추론하고 사용자를 대신하여 도구를 실행할 수 있는 에이전트 기능(agentic capabilities)을 제공하는 명령줄 도구(command-line tool)로 설명합니다.

# 로컬 스킬 발견을 위한 디렉토리 구조 예시
my-project/
├── .claude/
...

이 아키텍처에서 흔히 발생하는 실패 모드(failure mode) 중 하나는 심볼릭 링크(symlink) 해결 및 디렉토리 권한과 관련이 있습니다. 만약 .claude/skills 폴더가 운영체제에 의해 제한되거나 깨진 심볼릭 링크를 포함하고 있다면, 발견 엔진(discovery engine)은 해당 파일들을 조용히 건너뜁니다. 이로 인해 스크립트가 존재함에도 불구하고 에이전트가 작업을 수행할 수 없다고 주장하는 결과가 발생합니다. 엔지니어는 CLI를 실행하는 프로세스가 전체 숨겨진 디렉토리 구조에 대한 읽기 권한을 가지고 있는지 확인해야 합니다. 이러한 로컬 접근 방식은 에이전트가 관련 없는 프로젝트의 무관한 기능들로 인해 과부하되는 "도구 오염(tool pollution)"을 방지하기 때문에 전역 설정(global configurations)보다 우수합니다.

기능 정의: YAML 프론트매터(Frontmatter) 및 도구 스키마 생성

Claude Code는 .claude/skills 디렉토리를 스캔하여 YAML 프론트매터 (Frontmatter) 블록을 포함하는 파일을 찾아냄으로써 스킬 (skills)을 발견합니다. 프론트매터는 각 파일의 상단에 위치하며 , - 라인으로 구분되는, 기계가 읽을 수 있는 작은 섹션입니다. 이 블록 내부에서 개발자는 기능 이름, 짧은 설명, 입력 파라미터 (parameters), 그리고 예상되는 출력 타입 (output type)을 선언합니다. Claude Code는 이 메타데이터를 모델에게 도구를 설명하는 JSON 스키마 (JSON schema)로 파싱합니다. 이 스키마는 name, description, parameters, type 필드를 포함하며 OpenAI 호환 도구 정의 형식을 따릅니다. 스키마가 프론트매터로부터 자동으로 생성되기 때문에, 개발자는 단일 진실 공급원 (single source of truth)만 유지하면 됩니다. 즉, 설명이나 파라미터 목록을 변경하면 추가 코드 없이도 모델의 도구 카탈로그 (tool catalog)에 즉시 반영됩니다.

프론트매터는 또한 발견 범위 (discovery scope)를 제어하는 선택적 태그 (tags)를 지원합니다. local: true 또는 mcp: false와 같은 태그는 Claude Code에게 해당 스킬을 호스트 머신에서만 제공할지, 아니면 원격 MCP 서버에 광고할지를 알려줍니다. 스킬이 local: true로 표시되면, 생성된 스키마가 런타임 (runtime) 시 시스템 프롬프트 (system prompt)에 주입되어 모델이 도구를 직접 호출할 수 있게 합니다. mcp: true인 경우, 스키마는 MCP 엔드포인트 (endpoint)로 전송되어 공유 스킬 레지스트리 (skill registry)의 일부가 됩니다. 이러한 이중 모드 (dual-mode) 접근 방식 덕분에 팀은 스킬 구현을 변경하지 않고도 로컬 스크립트와 중앙 관리형 서비스를 혼합하여 사용할 수 있습니다.

구체적인 예시를 통해 이 과정을 살펴보겠습니다. 다음과 같은 프론트매터로 시작하는 list_files.md 파일이 있다고 가정해 봅시다:

, -
name: list_files
description: 디렉토리 내의 파일을 나열하며, 선택적으로 확장자에 따라 필터링할 수 있습니다.
...

프론트매터 (frontmatter) 아래의 파일에는 목록 나열을 수행하는 Bash 스크립트가 포함되어 있습니다. Claude Code는 이 블록을 읽어 도구 스키마 (tool schema)를 구축하고, list_files를 호출 가능한 함수로 등록합니다. 모델이 “src 디렉토리 내의 모든 Python 파일을 보여줘”라는 요청을 받으면, 해당 요청을 list_files 스키마와 매칭하고 path 및 extension 파라미터를 채운 뒤 스크립트를 실행합니다. 결과는 일반 텍스트 리스트 형태로 모델에 반환되며, 이는 최종 답변에 포함될 수 있습니다.

Claude 3.5 Sonnet은 매우 큰 프롬프트 (prompt)를 처리할 수 있기 때문에, 생성된 스키마들을 모델의 컨텍스트 윈도우 (context window)를 소진하지 않고도 시스템 프롬프트에 포함할 수 있습니다.

Anthropic 모델 사양 (Anthropic Model Specifications)에 따르면, Claude 3.5 Sonnet은 최대 200,000 토큰의 컨텍스트 윈도우를 지원합니다. 이러한 용량 덕분에 많은 스킬 스키마를 동시에 임베딩 (embedding)할 수 있습니다.

신뢰할 수 있는 도구 선택을 위해서는 명확하고 간결하며 서술적인 프론트매터가 필수적입니다. 모델은 특정 스킬이 적절한지 결정하기 위해 설명을 참조하며, 모호한 표현은 기회를 놓치거나 잘못된 도구 호출 (tool call)로 이어집니다.

도구 설명이 더 좋을수록 모델은 이를 언제 사용할지 더 잘 결정할 수 있습니다. Anthropic 개발자 가이드 - 도구 사용 (Anthropic Developer Guides - Tool Use)에서 언급된 바와 같이, 신뢰할 수 있는 도구 선택을 위해서는 명확하고 간결하며 서술적인 이름과 설명이 필수적입니다.

스킬 도구 루프: 터미널 명령 가로채기 vs 직접 실행

Claude Code는 모델과 로컬 실행 환경 사이의 긴밀한 루프를 유지하며 작동합니다. 프롬프트를 API로 보내기만 하는 단순한 래퍼 (wrapper)와 달리, 이 시스템은 터미널 입력을 잠재적인 도구 트리거 (tool trigger)로 취급합니다. 모델이 특정 작업에 특정 기능이 필요하다고 판단하면, 단순히 명령어를 제안하는 것에 그치지 않고 구조화된 도구 호출 (tool call)을 방출합니다. 클라이언트는 이 호출이 표준 셸 (shell) 환경에 도달하기 전에 이를 가로챕니다.

이러한 가로채기(interception)는 상태(state)와 보안을 유지하는 데 매우 중요합니다. 작업을 스킬 루프(skill loop)를 통해 라우팅함으로써, 시스템은 미리 정의된 스키마(schema)에 따라 인자(arguments)를 검증할 수 있습니다. 만약 사용자가 특정 파일 패턴을 검색해 달라고 요청하면, 모델은 관련 스킬을 호출합니다. 로컬 러너(local runner)가 코드를 실행하고 출력을 캡처하여 이를 대화 기록(conversation history)에 다시 전달합니다. 이는 모델이 각 단계의 성공 또는 실패로부터 학습하는 폐쇄 루프(closed-loop) 시스템을 구축합니다.

Claude 3.5 Sonnet 모델은 이전 반복 버전 대비 도구 사용 선택 정확도에서 2배의 향상을 달성했습니다. Anthropic 기술 보고서(Technical Report)의 이 데이터는 모델이 복잡한 작업을 수행하는 동안 어떤 로컬 스킬을 트리거할지 결정할 때 훨씬 더 신뢰할 수 있음을 나타냅니다.

셸 명령(shell commands)을 직접 실행하는 것은 모델에 컨텍스트(context)가 부족할 수 있기 때문에 위험을 초래합니다. 스킬 루프를 사용함으로써, Claude Code는 파괴적인 작업을 실행하기 전에 사용자에게 확인을 요청하는 권한 계층(permission layer)을 구현할 수 있습니다. 이러한 아키텍처는 모델이 컨트롤러(controller) 역할을 하는 현대적인 에이전틱 프레임워크(agentic frameworks)를 반영합니다. 이는 다단계 작업 중에도 터미널이 안정적인 환경으로 유지되도록 보장합니다.

Model Context Protocol (MCP) 소개에서 언급된 바와 같이, 이 프로토콜을 통해 Claude는 표준화된 인터페이스를 통해 GitHub 및 로컬 데이터베이스와 같은 시스템과 상호 작용할 수 있습니다.

Leviathan(leviathanterminal.com)과 같은 환경에서 이 루프는 자동화된 워크플로(workflows)를 관리하는 데 필수적입니다. 스킬 루프는 버퍼(buffer) 역할을 제공합니다. 이를 통해 호스트 머신에서 어떠한 상태 변화가 일어나기 전에 도구 호출(tool call)이 의도된 스키마와 일치하는지 시스템이 검증할 수 있게 합니다.

async function executeToolLoop(toolCall: ToolCall) {
  const tool = findSkill(toolCall.name);
  if (!tool) throw new Error("Skill not found");
...

위 코드는 가로채기 로직 (interception logic)을 보여줍니다. 시스템은 실행 전에 스키마 (schema)를 기준으로 인자 (arguments)를 파싱합니다. 이는 모델이 쉘 명령 (shell command)에 잘못된 플래그 (flags)를 전달하는 것을 방지하며, 이는 더 단순한 구현체에서 흔히 발생하는 실패 지점입니다. 이러한 구조적 접근 방식은 런타임 에러 (runtime errors)의 빈도를 줄이고 에이전트적 동작 (agentic behavior)의 예측 가능성을 높입니다.

정적 라우팅 vs 동적 라우팅: 슬래시 명령 (slash commands)과 자율적 도구 호출 (autonomous tool calls)의 차이

Claude Code는 스킬 (skill)을 호출하기 위한 두 가지 경로를 구분합니다. 첫 번째는 정적 라우팅 (static routing)으로, 리터럴 슬래시 명령 (예: /build)을 .claude/skills 디렉토리 내의 파일에 매핑합니다. 이 매핑은 Claude가 요청을 확인하기 전에 클라이언트 (client)에 의해 해결되므로, 모델은 어떤 도구를 사용할지 추론할 필요가 없습니다. 이 경로는 명령 문자열이 알려진 스킬 파일을 직접 인덱싱하기 때문에 결정론적 (deterministic)이며, 지연 시간이 낮고, 감사 (audit)하기 쉽습니다.

두 번째 경로는 동적 라우팅 (dynamic routing)입니다. 여기서는 Claude가 주변 프롬프트 (prompt)와 내부 정책 (internal policy)을 바탕으로 도구를 호출해야 한다고 결정합니다. Claude는 구조화된 도구 사용 블록 (structured tool-use block)을 생성하고, 클라이언트가 해당 블록을 파싱하여 지정된 실행 파일 (executable)을 실행한 뒤 그 결과를 다시 Claude에게 전달합니다. 결정이 모델에 의해 이루어지기 때문에, 라우팅은

동적 라우팅 (Dynamic routing)은 또한 도구 (tool)에 엄격한 출력 규약 (output contract)을 부과합니다. 루프가 여러 번 반복되더라도 후속 파싱 (parsing)이 안정적으로 유지될 수 있도록, 결과는 반드시 JSON으로 캡슐화된 tool_result 객체로 감싸져야 합니다.

Claude는 JSON으로 캡슐화된 tool_result 형식의 도구 결과 (tool results)를 기대합니다. 이 표준은 Anthropic API Docs에 문서화되어 있으며, 장시간 실행되는 에이전트 루프 (agentic loops)를 안정적으로 유지하는 데 도움을 줍니다.

구체적인 예시는 Leviathan 터미널에서 확인할 수 있습니다. Leviathan은 /git status로 호출되는 정적 스킬 (static skill)인 git_status.yaml을 정의합니다. 동일한 저장소에는 함수 이름을 코드베이스에서 검색할 수 있는 동적 스킬 (dynamic skill)도 포함되어 있습니다. 사용자가 “process_data의 정의를 찾아줘”라고 요청하면, Claude는 슬래시 명령 (slash command)을 입력하지 않았음에도 불구하고 검색 실행 파일 (search executable)을 위한 도구 사용 (tool-use) 블록을 생성합니다. 클라이언트는 검색 도구를 실행하고 JSON 결과를 반환하며, Claude는 해당 코드 스니펫 (snippet)을 답변에 포함합니다.

명령 공간 (command space)이 작고, 잘 알려져 있으며, 보안이 중요한 경우에는 정적 라우팅 (static routing)이 더 바람직합니다. 동적 라우팅 (dynamic routing)은 요청이 모호할 때, 스킬 세트 (skill set)가 방대할 때, 또는 모델이 요청을 충족하기 위해 여러 도구를 조합해야 할 때 빛을 발합니다. 엔지니어는 예측 가능한 작업에는 정적 슬래시 명령 (static slash commands)을 기본으로 사용해야 하며, 모델의 문맥적 추론 (contextual reasoning)이 측정 가능한 가치를 더하는 경우에만 자율적인 도구 호출 (autonomous tool calls)을 예약해야 합니다.

문맥적 주입 (Contextual Injection): 스킬이 시스템 프롬프트 (System Prompt)로 직렬화되는 방식

로컬 스크립트와 모델 동작 사이의 가교는 직렬화 (serialization)입니다. Claude Code는 단순히 디스크에 스킬 파일이 존재한다고 모델에게 알려주는 것에 그치지 않습니다. 각 스킬의 YAML 프론트매터 (frontmatter)와 함수 시그니처 (function signature)를 구조화된 도구 정의 (tool definition)로 변환합니다. 이 정의는 에이전트 루프 (agentic loop)가 초기화되는 동안 시스템 프롬프트 (system prompt)에 직접 주입됩니다.