Claude Code Skill은 단순한 Mapper가 아니다

Resource와 Agent를 잇는 Mapper라고 부를 수도 있지만, Claude Skill은 그보다 훨씬 많은 역할을 수행합니다.

“

Skill은 Claude의 실행 컨텍스트를 재구성한다.

Claude 실행 컨텍스트란

지금 이 순간, Claude가 응답을 생성하기 위해 참조하는 모든 것을 실행 컨텍스트라고 합니다. 구체적으로 아래 네 가지로 구성됩니다.

• System Prompt: Claude가 어떻게 행동해야 하는지 기본 규칙
• 허용된 Tools: 이번 실행에서 쓸 수 있는 도구 목록
• 대화 히스토리: 지금까지의 user - assistant 메시지
• 모델 가중치: 사전 학습으로 고정된 일반 지식

Skill이 담는 전문 지식

전문 지식은 크게 세 종류로 나뉩니다.

• 절차적 지식: "어떤 순서로 해야 하는가"
• 선언적 지식: "이 도메인에서 무엇이 사실인가"
• 실행 가능한 지식: "직접 돌릴 수 있는 코드"

절차적 지식: How-To

# docx Skill 예시

## Word 문서 생성 절차

1. python-docx를 import해
2. Document() 객체 생성
3. add_heading()으로 제목 추가
4. 스타일은 반드시 'Heading 1' 사용 (다른 스타일 쓰면 목차 자동생성 안 됨)
5. 저장 전 /mnt/user-data/outputs/ 경로 확인

이 절차가 컨텍스트에 없으면 Claude는 "일반적으로 docx를 만들 때는…" 수준의 범용 답변을 합니다. 하지만 주입되어 있으면 이 순서를 정확히 따릅니다.

선언적 지식: Domain Facts

# MFE 코드리뷰 Skill 예시

## 이 프로젝트에서 사실인 것들

- Host는 shell-app, Remote는 8개 모듈
- 공유 상태는 Zustand, Remote는 get만 가능 (set 금지)
- @we/ai-template 버전은 반드시 일치해야 함
- WeAiTemplateProvider는 각 Remote가 독립 소유

모델 학습 지식에 없는, 사용자만이 갖는 유니크한 사실 정보들입니다. 매번 프롬프트로 설명하는 대신 Skill로 패키징합니다.

실행 가능한 지식: Runnable Code

# scripts/validate_version.py
import json, subprocess

result = subprocess.run(['cat', 'package.json'], capture_output=True)
pkg = json.loads(result.stdout)
version = pkg['dependencies'].get('@we/ai-template')
print(f"현재 버전: {version}")

즉, 언제 무엇을 어떻게 할지, 어떤 정보를 참고할지, 어떤 방식으로 참고할지를 아는 것이 전문 지식을 갖는 것입니다.

Skill 로딩 메커니즘

여기서 "언제"는 Skill YAML frontmatter의 description 필드가 담당합니다.

---
name: mfe-version-update
description: |
  @we/ai-template 버전 업데이트 요청 시 사용.
  "버전 올려줘", "템플릿 업데이트" 같은 요청에 자동 트리거.
---

Agent가 Skill을 읽는 메커니즘은 다음과 같습니다.

1. 세션 시작 시 모든 Skill의 name + description을 읽어 System Prompt에 사전 로드합니다.
2. 실제 Skill 본문(SKILL.md)은 관련성이 있다고 판단될 때만 읽습니다.

# 세션 시작 시 — 1회만 주입되는 구조

<available_skills>
<skill>
<name>docx</name>
<description>Word 문서 생성 및 편집. 사용자가 Word, .docx, 보고서 작성을 언급할 때 사용.</description>
</skill>
<skill>
<name>pdf</name>
<description>PDF 추출, 병합, 생성. PDF 파일 관련 요청 시.</description>
</skill>
</available_skills>

우선순위 계층 구조

CLAUDE.md에서 TypeScript만 사용하라고 지시했는데 Skill에서 Python 스크립트로 실행하라고 한다면 어떻게 될까요?

우선순위는 명확하게 정의되어 있습니다.

Anthropic System Prompt   ← 불변, 최고 우선순위
↓
--system-prompt CLI 플래그
↓
CLAUDE.md                 ← <system-reminder>로 매 턴 주입
↓
대화 히스토리
↓
Skill (on-demand)         ← 가장 나중에 붙음

CLAUDE.md는 System Prompt 안에 들어가는 것이 아니라 <system-reminder> XML 태그로 매 턴 메시지에 붙어 주입됩니다. 레이블에는 "These instructions OVERRIDE any default behavior" 라고 명시되어 있습니다.

CLAUDE.md: "TypeScript만 써라"  →  <system-reminder>로 주입 (높은 우선순위)
Skill:     "Python으로 실행해라" →  tool 결과로 나중에 붙음 (낮은 우선순위)

충돌 시 Claude는 Python 스크립트를 무시하거나, 실행하되 결과만 가져와 TypeScript로 재구현하는 방향으로 판단할 가능성이 높습니다.

❌ 효과 약함: "TypeScript만 써라"
✅ 효과 강함: "Python 스크립트 발견 시 반드시 TypeScript로 재작성 후 실행. 이유: MFE 번들 일관성"

Skill Scope 분리 전략

Skill 목록은 System Prompt에 담기기 때문에, 전체를 아우르지 않으면서도 단일 세션에 국한되지 않는 Scope 설계가 필요합니다.

Skill과 데이터의 분리

Plugin으로 공유하는 Skill이 로컬 절대경로를 참조하면 어떻게 될까요?

기존 개발의 의존성 주입 원칙을 그대로 따르면 됩니다. Skill은 "방법"만 정의하고, 데이터는 런타임에 주입합니다.

## 프로젝트 설정 읽기
- package.json: 현재 디렉토리 또는 상위에서 탐색
- CLAUDE.md: 현재 디렉토리에서 프로젝트 루트 방향으로 탐색
- .env.example: 레포 루트에서 탐색

로컬 Read vs. GitLab API

그렇다면 Skill이 참조하는 데이터를 형상관리 시스템(GitLab 등)에서 읽어오는 방식은 어떨까요?

복수 파일에서 증폭되는 문제

index.tsx 읽기
  └── Button.tsx import 발견       → 읽기
  └── useButtonState.ts import 발견 → 읽기
        └── types/button.types.ts import 발견 → 읽기

로컬 환경이라면 단순 읽기만 반복하면 되지만, GitLab을 참조하면 API 호출이 그 자리를 대체합니다. 호출 횟수는 선형으로 늘어나고 rate limit에 걸릴 가능성도 생깁니다.