Molayo

© 2026 Molayo

Dev.to헤드라인2026. 05. 28. 04:04

첫 번째 Claude Skill 만들기: 20분 만에 완성하는 Gmail-to-GDrive 영수증 분류기

요약

Claude Skill을 활용하여 Gmail의 영수증을 추출하고 Google Drive에 자동 저장하는 파이프라인 구축 방법을 설명하는 튜토리얼입니다. SKILL.md 파일을 통해 Claude의 컨텍스트를 효율적으로 관리하고 자동화하는 기술적 원리를 다룹니다.

핵심 포인트

  • Claude Skill은 SKILL.md 파일과 스크립트로 구성된 재사용 가능한 지침 세트임
  • 설명(description) 필드는 Claude가 스킬을 검색하고 로드하는 핵심 트리거임
  • 스킬 사용 시 버전 관리, 컨텍스트 최적화, 모듈화된 구성이 가능함
  • MCP 서버와 연동하여 Gmail 및 Google Drive와 같은 외부 도구 제어 가능

Gmail 영수증을 분류하고 Google Drive에 저장하는 재사용 가능한 파일 기반 Skill로 Claude를 확장하고 싶은 개발자를 위한 실습 튜토리얼입니다.

저는 영수증을 잃어버립니다. 종이 영수증이 아니라 디지털 영수증 말이죠. Stripe 인보이스, AWS 청구서, Apple 개발자 갱신 비용, 그리고 존재조차 잊고 있었던 무작위 SaaS 구독료 같은 것들 말입니다. 그것들은 Gmail에 영원히 머물러 있다가, 3월이 되면 저는 회계사를 위해 1년 치 지출 내역을 정리하려고 토요일 내내 검색 쿼리를 뒤지며 시간을 허비하곤 합니다.

올해 저는 이를 Claude skill로 해결하기로 했습니다. 그 결과: 제가 "지난달 영수증을 정리해 줘"라고 입력하면, Claude가 Gmail에 접속하여 PDF를 추출하고, 이를 적절한 Google Drive 폴더에 넣은 뒤, CSV 로그에 행을 추가합니다. 이것이 가능한 이유는 이 skill이 제가 이 작업을 어떻게 수행하기를 원하는지 정확히 Claude에게 알려주기 때문입니다. 단 한 번, 파일에 작성해 두면 영원히 지속됩니다.

이 포스트는 해당 skill을 처음부터 구축하는 과정을 안내합니다. 만약 이전에 만들어 본 적이 없다면, 이보다 더 부드러운 입문 과정은 없을 것입니다. 이 글을 다 읽을 때쯤이면 여러분은 실제로 필요한 어떤 이메일 및 Drive 파이프라인(pipeline)에도 적응할 수 있는 작동 가능한 skill을 갖게 될 것입니다.

Claude skill이란 정확히 무엇인가

skill은 단순히 SKILL.md 파일이 들어 있는 폴더일 뿐입니다. 해당 파일에는 YAML 프론트매터(frontmatter, 이름 + 설명)와 프롬프트(prompt) 역할을 하는 마크다운(markdown) 본문이 포함되어 있습니다. 이는 Claude가 관련이 있을 때만 로드할 지침 세트입니다.

~/.claude/skills/receipt-filer/
├── SKILL.md          # 지침(instructions)
└── scripts/          # Claude가 실행할 수 있는 선택적 헬퍼(helpers)
...

결정적인 세부 사항은 다음과 같습니다: skill은 설명(description)을 통해 발견됩니다. 여러분이 Claude에게 무언가를 물어보면, Claude는 skill 설명을 스캔하여 일치하는 것을 컨텍스트(context)로 가져옵니다. 즉, description: 필드는 단순한 문서화가 아니라 실제적인 역할을 수행하며, 검색 대상(retrieval target)이 됩니다. README 서문처럼 쓰지 말고, 누군가가 사용할 법한 검색 쿼리처럼 작성하세요.

Skill이 "그냥 시스템 프롬프트(system prompt)에 집어넣는 것"보다 나은 세 가지 이유는 다음과 같습니다:

  1. 버전 관리 (Versioning). 폴더 내의 파일일 뿐입니다. 커밋(Commit)하세요.
  2. 범위 지정 (Scoping). 트리거될 때만 로드되므로, 언젠가 필요할지도 모르는 14개의 지침 세트로 인해 컨텍스트(Context)가 비대해지지 않습니다.
  3. 구성 (Composition). 스킬은 스크립트를 호출하고, 다른 파일을 참조하며, MCP 서버(Gmail, Drive, GitHub 등 무엇이든)의 존재를 가정할 수 있습니다.

우리가 해결하려는 문제

구체적으로는 다음과 같습니다:

  • Gmail로 영수증을 받습니다. 어떤 것은 PDF가 첨부되어 있고, 어떤 것은 PDF 링크가 걸려 있으며, 어떤 것은 PDF로 저장하고 싶은 단순 HTML 이메일입니다.
  • 이 파일들을 Google Drive의 /Receipts/{YYYY}/{MM}/{vendor}-{YYYY-MM-DD}.pdf 경로에 저장하고 싶습니다.
  • /Receipts/log.csv 파일 끝에 date, vendor, amount, currency, drive_link, gmail_link 형식으로 행을 추가하고 싶습니다.
  • 이 과정은 안전해야 합니다: 이메일을 절대 삭제하지 말고, 기존 파일을 덮어쓰지 마세요. 모호한 작업을 수행하기 전에는 반드시 물어보세요.

이 스킬이 이 모든 것을 인코딩할 것입니다.

사전 요구 사항

Gmail 및 Google Drive MCP 커넥터(Connectors)가 활성화된 Claude가 필요합니다. Claude Code 또는 데스크톱 앱에서는 커넥터당 한 번의 인증 흐름(Auth flow)이 필요합니다. 설정에서 "Connectors"를 검색하여 활성화하세요. Claude가 도구 호출(Tool calls) 시 사용할 커넥터 이름은 search_threads, get_thread, download_file_content, create_file 등과 같습니다. 이를 암기할 필요는 없습니다. 스킬이 평이한 영어로 이를 참조하면 Claude가 어떤 도구를 호출할지 판단합니다.

1단계: 스킬 스캐폴딩 (Scaffold)

mkdir -p ~/.claude/skills/receipt-filer/scripts
touch ~/.claude/skills/receipt-filer/SKILL.md

이것이 스캐폴딩 단계의 전부입니다. CLI도, 초기화(init) 명령어도, package.json도 없습니다. 스킬은 하나의 디렉토리입니다.

2단계: SKILL.md 작성

~/.claude/skills/receipt-filer/SKILL.md를 열고 프런트매터(Frontmatter)부터 시작하세요:

name: receipt-filer
description: "Gmail에서 영수증 및 인보이스(Invoice)를 연도/월/업체별로 정리하여 Google Drive에 저장하고, 추적용 CSV에 행을 추가합니다. 사용자가 "영수증 정리해줘", "인보이스 보관해줘", "Gmail 영수증 정리해줘", "영수증을 Drive에 저장해줘"라고 요청하거나 세금 준비, 비용 보고서, 또는 월간 장부 작성을 언급할 때 사용합니다. PDF 첨부 파일, 링크된 PDF, 그리고 HTML 전용 영수증을 처리합니다."
...

두 가지 주목할 점이 있습니다. 설명(Description) 부분은 의도적으로 길고 트리거(Trigger)가 풍부하게 작성되었습니다. 사용자가 이 작업을 요청할 때 사용할 수 있는 모든 문구를 포함했기 때문입니다. 또한, 이 스킬이 무엇을 _처리하는지(handles)_를 명시하며 끝맺음으로써, Claude가 예를 들어 전달받은 레시피 이메일 등에 대해 과도하게 트리거(Over-trigger)되는 것을 방지합니다.

이제 본문입니다. 이것이 Claude가 따르는 실제 지침 세트(Instruction set)입니다. 조각별로 보여드린 후 하나로 합쳐보겠습니다.

Claude에게 성공의 기준을 알려주기

## 목표 (Goal)

사용자가 요청한 각 영수증/인보이스 이메일에 대해, Google Drive에 정확히 하나의 PDF를 생성합니다.
...

모호한 "주의하세요"보다는 구체적인 불변 조건(Invariants)이 더 효과적입니다. Claude는 이를 충실히 따를 것입니다.

무엇을 영수증으로 간주할지 정의하기

## 영수증으로 간주되는 항목 (What counts as a receipt)

포함 항목:
...

이것은 휴리스틱(Heuristic) 계층입니다. 스킬이 잘못 분류하는 이상한 사례를 발견함에 따라 이 목록을 시간이 지나면서 계속 다듬어 나가게 될 것입니다.

절차를 상세히 기술하기

## 절차 (Procedure)

1. **검색 범위 설정.** 사용자가 범위를 지정하지 않는 한, 기본적으로 최근 35일로 설정합니다.
...

번호가 매겨진 절차는 스킬의 핵심입니다. Claude는 이를 놀라울 정도로 충실하게 따르며, 문제가 발생했을 때 어떤 단계를 강화해야 하는지 정확히 지목할 수 있습니다.

안전 장치(Safety rails) 추가하기

## 안전 (Safety)

- Gmail 메시지를 절대 삭제하거나 보관 처리(Archive)하지 마십시오.
...

'50개의 영수증 확인'과 같은 규칙은, 스킬이 새벽 2시에 800개의 항목을 한꺼번에 정리하려고 시도하는 것을 직접 경험해 본 후에야 추가하게 되는 종류의 디테일입니다.

선택 사항: 헬퍼 스크립트 (Helper script)

스크립트가 반드시 필요한 것은 아닙니다. 하지만 적절한 인용 부호(quoting)를 포함한 CSV 쓰기처럼 Claude가 지시사항(instructions)만으로는 잘 수행하지 못하는 작업의 경우, 작은 Python 헬퍼(helper) 스크립트가 유용합니다. Skill은 자신의 디렉토리에 있는 스크립트를 참조할 수 있으며, Claude는 자신의 셸(shell) 도구를 통해 이를 실행합니다.

# ~/.claude/skills/receipt-filer/scripts/log.py
import csv, sys, pathlib

...

그 다음 SKILL.md에 다음을 추가합니다:

## Helpers

CSV 행을 작성할 때는 직접 만드는 대신 `scripts/log.py`(이 skill의 디렉토리에 있음)를 사용하세요.
...

3단계: 실행해 보기

Claude 클라이언트를 재시작하여 skill 폴더를 다시 스캔하게 한 다음, 다음과 같이 입력하세요:

file my receipts from the last 30 days (지난 30일간의 내 영수증들을 정리해줘)

Claude가 receipt-filer skill을 사용한다고 알리는 것을 볼 수 있을 것입니다 (Claude Code는 이를 출력하며, 데스크톱 앱은 칩(chip) 형태로 보여줍니다). Claude가 무엇을 하는지 지켜보세요. 첫 실행은 skill이 제 역할을 다하는지, 아니면 지시사항의 빈틈을 보여주는지 확인하는 단계입니다.

제 경우, 첫 실행 결과는 다음과 같았습니다:

  • 11개의 Stripe 및 AWS 인보이스(invoices)를 정확하게 가져왔습니다.
  • 결제가 완료되지 않은 Apple Store 주문 확인서를 분류했습니다. 저는 "제외(Exclude)" 섹션을 더 강화했습니다.
  • 금액이 이미지로 렌더링되어 있었기 때문에 Vercel 영수증에서 막혔습니다. 저는 이메일 본문의 일반 텍스트(plain-text) 합계 금액을 대체 수단으로 사용하도록 지시사항을 추가했습니다.

세 번의 반복(iterations)을 거쳤고, 각 단계마다 SKILL.md를 한 줄씩 수정했을 뿐인데, 그 이후로 이 skill은 조용하고 신뢰할 수 있게 작동하고 있습니다.

무엇이 좋은 skill을 만드는가

이런 것들을 몇 개 만들어 본 후, 저는 다음과 같은 짧은 목록을 내면화했습니다:

  • 설명(Description)은 검색 계층(Retrieval layer)입니다. 유의어를 포함하여 사용자가 실제로 사용할 법한 단어들로 가득 채우세요. 잘못된 설명은 Skill이 트리거되지 않는 가장 큰 원인입니다.
  • 성공과 실패를 구체적으로 정의하세요. "Drive에 저장하세요"보다는 "영수증당 정확히 하나의 PDF"가 훨씬 낫습니다. Claude는 정밀한 규칙을 따르는 데는 뛰어나지만, "정리된" 상태가 무엇을 의미하는지 추론하는 데는 평범합니다.
  • 안전(Safety) 섹션은 주니어 개발자에게 열쇠를 건네주는 것처럼 작성하세요. 되돌릴 수 없는 작업은 무엇인가? 확인이 필요한 작업은 무엇인가? 영향 범위(Blast radius)는 어디까지인가?
  • 채팅창이 아닌 파일 내에서 수정하세요. Skill이 제대로 작동하지 않을 때, 그 순간 Claude와 논쟁하지 말고 파일을 수정하세요. 미래의 당신이 현재의 당신에게 감사할 것입니다.
  • 미리 최적화하지 마세요. 순수한 지침(Instructions)으로 시작하세요. 지침만으로는 확실하게 처리할 수 없는 문제에 부딪혔을 때만 스크립트(Scripts)를 추가하세요.

다음 단계

이 패턴은 일반화될 수 있습니다. 동일한 템플릿으로 제가 만든 몇 가지 Skill은 다음과 같습니다:

  • pr-digest — 지난 일주일간의 GitHub 알림 이메일을 가져와서 "내가 처리해야 할 것 / 다른 사람이 처리해야 할 것 / 머지(Merged)된 것"이 담긴 Drive 문서를 생성합니다.
  • vendor-onboarding — DocuSign을 통해 계약서 PDF가 도착하면, 업체명으로 된 Drive 폴더를 생성하고, 계약서를 파일링하며, 내부 Slack 메시지 초안을 작성합니다.

이 모든 것들은 동일한 형태를 가집니다: 폴더 하나, SKILL.md, 선택적 스크립트, 명확한 절차, 그리고 명명된 안전 가드레일(Safety rails). 하나를 만들고 나면, 두 번째는 10분이면 충분합니다.

영수증 분류기는 제가 만든 것입니다. 가져다 쓰셔도 좋고, 포크(Fork)하셔도 좋습니다. "영수증" 대신 여러분이 위임하고 싶은 Gmail 형태의 어떤 혼돈이든 교체해서 사용하세요.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0