16. Building Google Skills — Part 1
코딩하지 않았습니다
지난 글(15편)에서 Gmail, Sheets, Drive, Calendar, Tasks 5개 스킬을 보여드렸습니다. 터미널에서 "메일 확인해줘"하면 메일을 읽고, "시트 열어줘"하면 스프레드시트를 가져옵니다.
이걸 만드는 데 Python을 직접 작성한 적이 없습니다. 하지만 "Gmail 스킬 만들어줘"라고만 한 것도 아닙니다. 그 사이에 한 가지 단계가 있습니다.
먼저 할 일: 공식 문서를 저장해둔다
제가 스킬을 만들 때 가장 먼저 하는 건 Claude Code의 공식 문서를 로컬 폴더에 저장해두는 것입니다.
official-docs/
skills-guide.md <- Skills 시스템 공식 가이드 (24KB)
subagents-guide.md <- Subagent 가이드 (27KB)
claude-md-guide.md <- CLAUDE.md 가이드
rules-guide.md <- Rules 가이드
Anthropic의 공식 문서 사이트(code.claude.com/docs)에서 Skills 가이드를 가져와서 마크다운 파일로 저장합니다. SKILL.md의 구조, YAML frontmatter 필드, 베스트 프랙티스, 디버깅 방법 — 전부 이 파일에 있습니다.
왜 이걸 먼저 하냐면. Claude Code에게 "스킬 만들어줘"라고만 하면, Claude가 스킬의 구조를 대충 추측합니다. description에 뭘 넣어야 하는지, allowed-tools를 어떻게 설정하는지, 모호하게 처리합니다.
저장해둔 공식 문서를 @로 참조하면 다릅니다. Claude Code에서 @는 파일을 직접 대화에 첨부하는 기능입니다. @skills-guide.md를 붙이면 Claude가 문서 전체를 읽고, 정확한 구조로 스킬을 만듭니다. description에 트리거 키워드를 넣고, allowed-tools를 필요한 도구만 제한하고, SKILL.md 본문도 Claude가 실행할 수 있는 형태로 작성합니다.
@로 참조합니다. 저는 Google Skills뿐 아니라, 40개 넘는 스킬을 전부 이 방식으로 만들었습니다.Anthropic의 Claude Code 공식 문서에 따르면, Skills의 description 필드가 "Claude가 언제 이 Skill을 사용할지 판단하는 기준"입니다. 이 한 줄을 제대로 쓰려면 공식 가이드를 참조해야 합니다.
스킬의 구조: 파일 2개
공식 문서에 따르면, Claude Code의 스킬은 이 구조입니다:
~/.claude/skills/gmail/
SKILL.md <- Claude가 읽는 매뉴얼
scripts/
gmail.py <- 실제 동작하는 스크립트
SKILL.md는 Claude Code가 "이 스킬을 언제, 어떻게 쓸지" 판단하는 설명서입니다. "메일 확인해줘"라고 입력하면, Claude가 이 파일을 읽고 gmail.py list --unread를 실행합니다.
gmail.py는 Google Gmail API를 호출하는 Python 스크립트입니다. 300줄 정도. 이 코드를 제가 작성한 게 아닙니다.
이 두 파일을 Claude Code가 만듭니다. 공식 문서를 참조하면서.
Step 1. Gmail 스킬 만들기
대화로 시작합니다
Claude Code를 열고 이렇게 말했습니다:
@skills-guide.md 참고해서 Gmail 스킬 만들려고 해.
고려해야 할 부분 이야기해줘.
첫 줄이 핵심입니다. @skills-guide.md. @로 파일을 첨부하면 Claude Code가 공식 문서를 통째로 읽습니다. 읽은 상태에서 뭘 정해야 하는지 알아서 물어봅니다.
Claude Code가 물어온 것들:
- 어떤 기능이 필요하세요? (조회, 검색, 발송, 라벨 관리...)
- 인증은 어떻게 처리할까요?
- 특별히 원하는 출력 형식이 있나요?
미리 다 알 필요 없습니다. 물어보면 답하면 됩니다:
메일 읽고 검색하고 보낼 수 있으면 돼.
라벨별로도 볼 수 있으면 좋겠어.
인증은 google_auth.py 쓸 거야.
이게 전부입니다. API가 뭔지, 스크립트를 어떻게 짤지, SKILL.md에 뭘 넣을지 — 공식 문서를 읽은 Claude Code가 알아서 결정합니다.
Claude가 만든 것
Claude Code가 2분 정도 작업한 후, 두 파일을 만들었습니다.
SKILL.md에는 각 기능의 사용법이 정리되어 있습니다:
# 읽지 않은 메일 조회
python3 ~/.claude/skills/gmail/scripts/gmail.py list --unread
# 메일 검색
python3 ~/.claude/skills/gmail/scripts/gmail.py search "급여변동"
# 메일 발송
python3 ~/.claude/skills/gmail/scripts/gmail.py send \
--to "[email protected]" --subject "급여대장" --body "첨부합니다"
gmail.py에는 Google Gmail API를 호출하는 코드가 들어있습니다. 300줄 정도. 저는 이 코드를 한 줄도 작성하지 않았습니다.
테스트와 수정
첫 결과가 완벽하지 않았습니다. 테스트해보고 수정을 요청했습니다.
1회차 — 메일 목록에 발신자 이름이 안 보였습니다.
메일 목록에 발신자 이름도 보여줘.
Claude가 출력 포맷을 수정했습니다. 발신자 이름, 제목, 날짜가 테이블로 정리되었습니다.
2회차 — 날짜가 미국식(2/18/2026)으로 나왔습니다.
날짜 포맷을 한국식으로 바꿔줘. 2026-02-18 형태로.
3회차 — 검색할 때 기간 필터가 없었습니다.
검색할 때 기간 필터도 넣어줘. --days 옵션으로 최근 며칠 내 메일만 검색.
3번 왕복에 10분. 이게 전부입니다.
카페에서 신메뉴를 개발할 때와 비슷합니다. 레시피 초안을 만들고, 맛을 보고, "단맛 좀 줄여볼까", "산미가 부족한데" 하면서 3-4번 조정합니다. Python 문법을 아는 게 아니라, 원하는 결과를 말로 설명하는 겁니다.
Step 2. Google Sheets 스킬 만들기
Gmail이 작동하면, 같은 방식으로 다음 스킬을 만듭니다.
@skills-guide.md 참고해서 Google Sheets 스킬 만들려고 해.
시트 읽고 쓰는 기능이 필요해. 인증은 google_auth.py 쓸 거야.
두 번째부터는 좀 더 간결해집니다. 패턴을 알았으니까요. Claude Code가 "범위 지정 읽기도 넣을까요?", "행 추가 기능은요?" 물어봅니다. "응, 다 넣어줘." Claude Code가 gsheets.py와 SKILL.md를 만들었습니다.
수정은 1번:
시트를 읽을 때 JSON 출력 옵션도 추가해줘.
다른 스킬에서 데이터를 가져갈 때 편하게.
Sheets 스킬은 급여 처리에서 핵심입니다. 직원 DB 시트에서 이름, 시급, 근무시간을 읽어오는 데 씁니다. 15편에서 보여드린 "직원 DB에서 동교동 직원 보여줘"가 이 스킬입니다.
Step 3. Google Drive 스킬 만들기
@skills-guide.md 참고해서 Google Drive 스킬 만들려고 해.
파일 검색하고 다운로드하고 이동할 수 있으면 돼.
여기서 Claude Code가 중요한 질문을 했습니다. "폴더 구조가 있나요?"
이 질문에 제 상황을 이야기했습니다:
사업장별로 폴더가 나뉘어 있어. 동교동/인사동/구로.
각 사업장 아래에 월별 폴더, 그 안에 처리대기/처리완료 폴더야.
이게 차이를 만듭니다. 일반적인 Drive 기능은 Claude가 공식 문서를 보고 알아서 넣지만, 본인만의 폴더 구조는 대화에서 나와야 합니다. Claude Code가 물어봤고, 제가 답했고, 폴더 경로를 자동으로 처리하는 코드가 들어갔습니다.
수정은 2번:
폴더 아이디가 아니라 폴더 이름으로 검색할 수 있게 해줘.
"처리대기" 폴더에 뭐 있어? 라고 물으면 알아서 찾도록.
파일 다운로드 위치를 ~/Downloads/로 기본 설정해줘.
Drive 스킬은 영수증 관리에 씁니다. n8n이 영수증 사진을 Drive에 올리면, 터미널에서 "처리대기 폴더에 뭐 있어?" 하고 확인하고, 처리 후 "처리완료로 옮겨줘" 합니다.
대화에서 발견한 패턴
세 스킬을 만들고 나서 돌아보니, 매번 대화에서 같은 5가지가 정해졌습니다:
| 요소 | Gmail | Sheets | Drive |
|---|---|---|---|
| 1. 공식 문서 | @skills-guide.md | @skills-guide.md | @skills-guide.md |
| 2. 어떤 기능 | 메일 읽기/검색/발송 | 시트 읽기/쓰기 | 파일 검색/다운로드/이동 |
| 3. 인증 | google_auth.py | google_auth.py | google_auth.py |
| 4. 저장 경로 | gmail/ | google-sheets/ | google-drive/ |
| 5. 내 상황 | 라벨별 조회, 한국식 날짜 | JSON 출력 | 사업장별 폴더 구조 |
1번은 제가 매번 붙입니다. @skills-guide.md. 이게 대화의 출발점입니다.
2~4번은 Claude Code가 물어봅니다. 어떤 기능, 인증, 경로. 미리 정해놓지 않아도, 대화하면서 정해집니다.
5번만 제가 이야기합니다. Gmail에서 라벨별 조회가 필요한 건 저만의 사정이고, Drive의 사업장별 폴더 구조도 저만의 상황입니다. Claude Code가 물어볼 때도 있고, 제가 먼저 말할 때도 있습니다.
@로 공식 문서가 틀을 잡고, 대화가 디테일을 채웁니다.자주 묻는 질문
Q: 처음부터 뭐가 필요한지 다 알아야 하나요?
아닙니다. 저도 "Gmail 스킬 만들려고 해"로 시작했습니다. Claude Code가 뭘 정해야 하는지 물어봅니다. 모르면 "일단 기본으로 해줘"라고 하면 됩니다.
만든 후에 써보면서 "발신자 이름도 보여줘", "날짜를 한국식으로 바꿔줘" — 이런 대화를 3-4번 하면 됩니다. 미리 다 아는 것보다, 써보면서 고치는 게 더 빠릅니다.
Q: Python을 모르는데 에러가 나면 어떻게 하나요?
에러 메시지를 그대로 Claude Code에게 보여주면 됩니다. "이 에러 고쳐줘"가 가장 효과적인 프롬프트입니다. Anthropic의 Claude Code 공식 문서에 따르면, "Claude는 에러를 분석하고 자동으로 수정 코드를 제안"합니다. 저도 import 에러, 경로 에러, API 응답 에러를 전부 이 방식으로 해결했습니다.
Q: 3개 스킬을 다 만들어야 하나요?
필요한 것부터 하나씩. Gmail만 먼저 만들고, Sheets가 필요하면 그때 추가하면 됩니다. 프롬프트 구조가 같으니까, 하나를 만들어보면 나머지는 5분입니다.
Q: SKILL.md는 왜 필요한가요?
SKILL.md가 없으면 Claude Code가 스킬의 존재를 모릅니다. "메일 확인해줘"라고 말해도, SKILL.md가 없으면 Claude는 gmail.py를 실행할 줄 모릅니다. SKILL.md는 사람이 읽는 설명서가 아니라, Claude가 읽는 설명서입니다.
Q: 공식 문서는 어디서 가져오나요?
Anthropic의 Claude Code 문서 사이트(code.claude.com/docs)에서 Skills 가이드 페이지를 가져옵니다. 브라우저에서 전문을 복사해서 마크다운 파일로 저장하면 됩니다. 한 번 저장해두면 이후 모든 스킬을 만들 때 @skills-guide.md로 참조합니다. 저는 Skills, Subagents, CLAUDE.md, Rules 가이드를 전부 로컬 폴더에 저장해두고 있습니다.
다음 글에서
Gmail, Sheets, Drive — 데이터를 다루는 3개 스킬을 만들었습니다. 다음은 시간과 행동을 다루는 2개입니다.
Google Calendar로 일정을 관리하고, Google Tasks로 할 일을 폰과 동기화합니다. 15편의 아침 루틴과 할 일 관리 시나리오가 이 2개 스킬에서 나옵니다.
그리고 5개 스킬 모두, 아직 Google과 연결되지 않았습니다. 스킬의 "틀"만 만든 상태입니다. Google에게 "이 앱을 허용해주세요"라고 등록하는 인증 과정은 18편에서 다룹니다.
Tags: #Claude-Code #Season2 #Google-Skills #Gmail #Google-Sheets #Google-Drive #스킬만들기 #프롬프트 #비개발자