Claude Skills 알아보기

개요

이 문서는 Claude Code의 새로운 기능인 Claude Skills에 대해 설명한다. Skills는 기존의 Custom Commands, Custom Sub-agents와 어떤 차이가 있는지, 그리고 왜 Skills를 사용해야 하는지에 대해 상세히 다룬다.

Claude Skills란 무엇인가?

공식 정의

Anthropic에서 공식으로 제공하는 정의에 따르면, Claude Skills는 다음과 같다:

"Organized folders of instructions, scripts and resources that agent can discover and load dynamically to perform better at specific task"

즉, 에이전트 스킬은 특정 작업에서 더 나은 성능을 발휘할 수 있도록 에이전트가 동적으로 탐색하고 로드할 수 있는 지시문, 스크립트, 리소스가 정리된 폴더이다.

Skills의 역할

Skills를 통해 사용자의 전문 지식을 Claude에 조합 가능한 리소스로 패키징하여 Claude의 기능을 확장할 수 있다. 이를 통해 범용 에이전트를 사용자의 필요에 맞는 특화된 에이전트로 변환할 수 있다.

Skills 아키텍처

MCP와의 관계

Skills는 MCP(Model Context Protocol)와 동일한 레벨의 개념으로 이해할 수 있다. MCP를 등록하면 에이전트가 작업을 하면서 필요한 외부 도구들을 자동으로 불러오는 것처럼, Skills도 완전히 똑같은 방식으로 동작한다.

폴더 구조

Skills의 파일 시스템 구조는 다음과 같다:

.claude/
└── skills/
    ├── pdf/
    │   ├── skill.md          # 필수
    │   ├── reference.md      # 선택적 참조 파일
    │   ├── forms.md          # 선택적 참조 파일
    │   └── scripts/          # 실행 스크립트
    │       └── extract_fields.py
    ├── pptx/
    │   └── skill.md
    └── xlsx/
        └── skill.md

Skills는 다음 단위로 관리할 수 있다:

• 프로젝트 단위
• 사용자 단위
• 플러그인 단위

가장 중요한 규칙은 각 스킬 폴더 안에 skill.md 파일이 반드시 있어야 한다는 것이다. 그 외의 파일들은 자유롭게 추가할 수 있다.

skill.md 파일 구조

Front Matter (메타데이터)

skill.md 파일의 상단에는 YAML 형식의 Front Matter가 위치한다. 필수 항목은 두 가지이다:

---
name: PDF
description: Comprehensive PDF tool for extracting text and tables, merging/splitting documents, and filling up forms
---

• name: 스킬의 이름
• description: 스킬을 언제 사용해야 하는지에 대한 설명

description은 최대한 상세하게 작성하는 것이 권장된다. 여러 스킬이 존재할 경우 에이전트가 어떤 스킬을 사용해야 할지 명확히 판단할 수 있도록 해야 한다.

Markdown Body (본문)

Front Matter 아래에는 실제 스킬이 수행해야 하는 작업에 대한 설명을 마크다운 형식으로 작성한다. 이 부분은 Custom Commands나 Custom Sub-agents와 동일한 방식이다.

Content Referencing (콘텐츠 참조)

파일 참조 방식

skill.md 파일 내에서 다른 파일을 참조할 수 있다:

상세한 예제를 보려면 `./reference.md`를 참조하세요.
PDF 폼 작업 방법은 `./forms.md`를 참조하세요.

이렇게 참조된 파일들은 에이전트가 필요할 때만 읽게 된다. skill.md에 모든 내용을 직접 넣지 않고 별도 파일로 분리하는 이유가 여기에 있다.

스크립트 실행 참조

마크다운 파일에서 실행 가능한 스크립트를 참조할 수도 있다:

폼 필드를 추출하려면 scripts 디렉토리의 스크립트를 실행하세요:
`python ./scripts/extract_fields.py`

Progressive Disclosure

개념 설명

Progressive Disclosure는 Skills의 핵심 개념이다. 이는 파일의 내용들을 단계적으로 에이전트에게 흡수시킨다는 의미이다.

레벨 구조

동작 방식

1. Level 1: Claude Code를 실행하면 모든 스킬의 메타데이터(name, description)가 항상 컨텍스트에 로딩된다. 이를 통해 에이전트는 어떤 스킬들이 존재하고 언제 사용해야 하는지 알 수 있다.

2. Level 2: 에이전트가 특정 스킬을 사용하기로 결정하면, 그때서야 skill.md의 본문을 읽는다.

3. Level 3+: 본문을 읽은 후 추가적인 정보가 필요하면 참조된 파일들을 선택적으로 읽는다. 모든 참조 파일을 한 번에 읽지 않고, 정확히 필요한 파일만 컨텍스트에 넣는다.

장점

• 컨텍스트를 효율적으로 아낄 수 있다
• 할루시네이션을 줄일 수 있다
• 필요한 내용만 선택적으로 로딩하므로 성능이 향상된다

Skills vs Custom Commands vs Custom Sub-agents

실행 방식 비교

• Explicit: 사용자가 직접 어떤 기능을 사용할지 명시
• Implicit: Claude가 필요에 따라 알아서 결정

Progressive Disclosure 비교

Custom Commands와 Custom Sub-agents는 실행 시 모든 내용을 한 번에 컨텍스트에 넣지만, Skills는 필요한 것만 선택적으로 로딩한다.

컨텍스트 소모

실행 컨텍스트

서브 에이전트에서 실행되면 메인 에이전트의 컨텍스트를 아낄 수 있지만, 서브 에이전트에서 실행된 내용을 메인 에이전트가 알 수 없다는 단점이 있다.

Deterministic vs Non-deterministic

개념 설명

• Deterministic (결정론적): 같은 입력에 대해 항상 같은 결과가 나오는 것
• Non-deterministic (비결정론적): 같은 입력에 대해 다른 결과가 나올 수 있는 것

LLM은 기본적으로 Non-deterministic이다. "포트폴리오 사이트를 만들어 줘"라고 요청하면 매번 다른 결과가 나온다.

Skills를 통한 Deterministic 동작

Non-deterministic한 LLM의 동작을 Deterministic하게 바꾸는 가장 쉬운 방법 중 하나는 전통적인 코드를 작성하는 것이다. 코드는 같은 입력에 대해 항상 같은 출력을 보장한다.

Skills에서는 실행 가능한 스크립트를 포함할 수 있다:

폼 필드를 추출하려면 다음 스크립트를 실행하세요:
`python ./scripts/extract_fields.py`

이렇게 하면 Claude는 스크립트나 PDF 파일을 컨텍스트에 로딩하지 않고도 해당 명령을 실행할 수 있다. 그리고 미리 작성된 코드를 실행하기 때문에 일관되고 재현 가능한(consistent and repeatable) 결과를 얻을 수 있다.

비교

실습: PDF 스킬 사용하기

스킬 구조

Anthropic에서 제공하는 PDF 스킬 예제의 구조:

.claude/
└── skills/
    └── pdf/
        ├── skill.md
        ├── reference.md
        ├── forms.md
        └── scripts/
            └── extract_fields.py

skill.md 내용

---
name: PDF
description: PDF 텍스트/테이블 추출, 문서 병합/분할, 폼 채우기 등의 작업 시 사용
---

본문에는 각 기능에 대한 설명과 함께 상세 정보가 필요한 경우 참조할 파일 경로가 명시되어 있다:

• 사용법을 알고 싶으면 reference.md 참조
• 폼 작업 방법은 forms.md 참조

스킬 확인

Claude Code에서 스킬을 확인하는 방법:

> tell me what skills you have

결과로 "PDF 스킬이 있다"는 응답을 받을 수 있다. 이는 Front Matter가 항상 로딩되어 있기 때문이다.

스킬 실행

> test.pdf를 이미지로 변환해 줘

이 요청을 하면:

1. 에이전트가 PDF 스킬을 사용하기로 결정
2. skill.md의 본문을 읽음
3. 필요한 참조 파일만 선택적으로 읽음
4. 미리 작성된 스크립트를 실행하여 PDF를 이미지로 변환

결과의 일관성

컨텍스트를 완전히 클리어한 후 동일한 요청을 하더라도:

• 스킬이 동일하게 동작
• 동일한 결과를 생성
• 프로세스도 완전히 동일

이것이 Skills의 Deterministic한 특성이다.

정리

Claude Skills는 다음과 같은 장점을 제공한다:

1. 효율적인 컨텍스트 관리: Progressive Disclosure를 통해 필요한 정보만 선택적으로 로딩
2. Deterministic 결과: 미리 작성된 스크립트를 통해 일관된 결과 보장
3. 자동 스킬 선택: 에이전트가 작업에 적합한 스킬을 자동으로 선택
4. 확장성: 다양한 스킬을 추가하여 에이전트의 기능을 확장 가능

상황에 따라 Custom Commands, Custom Sub-agents, Skills 중 적절한 것을 선택하여 사용하면 된다. Deterministic한 결과가 필요하고 컨텍스트를 효율적으로 관리하고 싶다면 Skills가 가장 유리한 선택이다.

ref : https://www.youtube.com/watch?v=jxzpitU9YBg