16. Google 도구를 AI와 만들며 고친 것들

16. Google 도구를 AI와 만들며 고친 것들

코딩하지 않았습니다

앞서 Gmail과 Sheets, Drive를 업무에 연결하는 모습을 보여드렸습니다. 지금은 gws 같은 기존 연결 도구를 사용하는 경로도 살펴봤고요.

처음 제가 Google용 도구를 만들 때는 서비스별로 스킬과 실행 프로그램을 구성했습니다. 이걸 만드는 데 Python을 직접 작성한 적은 없습니다. 하지만 ‘Gmail 스킬 만들어줘’라고만 한 것도 아닙니다.

그 사이에 제가 한 일이 있습니다. 무엇을 근거로 만들지 알려주고, 원하는 결과를 이야기하고, 써보면서 고쳤습니다.

이번 글은 당시 도구를 만들고 고친 과정입니다. 지금 독자가 Google 서비스마다 프로그램을 새로 만들어야 한다는 뜻은 아닙니다. 그때 제가 어떤 부분을 판단했는지 보시면 됩니다.

먼저 공식 문서를 보게 했습니다

제가 스킬을 만들 때 하던 일은 Claude Code의 공식 가이드를 로컬 폴더에 저장해두는 것이었습니다.

official-docs/
├── skills-guide.md
├── subagents-guide.md
├── claude-md-guide.md
└── rules-guide.md

당시에는 이렇게 주제별로 모아두고 필요한 문서를 참조했습니다. 스킬을 만들 때는 @skills-guide.md를 붙여 그 자료를 보게 했습니다. @로 로컬 파일을 지정하는 방식이었습니다.

이유는 간단합니다. 제가 형식을 외워 설명하는 대신 무엇을 근거로 구성해야 하는지 알려주고 싶었습니다. SKILL.md에 어떤 내용을 적고, 각 필드가 어떤 역할인지 공식 안내와 대조하게 한 겁니다.

다만 한 번 저장한 문서가 계속 최신인 것은 아닙니다. 제품은 바뀝니다. 지금 같은 작업을 한다면 공식 문서의 현재 내용과 확인일을 함께 보게 하고, 저장한 자료가 오래됐다면 갱신해야 합니다. 자료를 붙였다고 결과가 자동으로 정확해지는 것도 아니고요.

독자가 문서를 전부 수동으로 복사할 필요는 없습니다. AI에게 현재 스킬 가이드를 확인하고, 근거와 달라진 부분을 설명하게 할 수 있습니다.

당시 구조는 지침과 실행 프로그램이었습니다

제가 만들었던 Gmail 도구는 이런 역할로 나뉘었습니다. 아래는 당시 구성의 핵심을 줄인 그림입니다.

gmail/
├── SKILL.md          ← 언제, 어떤 순서와 기준으로 쓸지
└── scripts/
    └── gmail.py      ← Google API를 요청하는 실행 프로그램

SKILL.md는 Claude가 읽는 업무 지침입니다. 어떤 요청에 쓰고, 어떤 기능을 어떻게 실행할지 적었습니다. gmail.py는 실제 Gmail API에 요청을 보내는 Python 프로그램이었고요.

그래서 ‘메일을 확인해줘’라는 요청을 받으면, 지침을 참고해 필요한 기능을 실행하고 그 결과를 읽는 식으로 이어졌습니다.

이것이 모든 스킬의 필수 파일 두 개라는 뜻은 아닙니다. 실행 프로그램은 필요할 때 두는 구성입니다. 이미 있는 도구로 일을 할 수 있다면, 스킬에는 그 도구를 사용하는 절차와 판단 기준을 적을 수도 있습니다. SKILL.md가 없다고 일반 명령 실행 자체가 불가능해지는 것도 아닙니다.

지침과 실행 도구를 나눠 생각하면, 무엇을 고쳐야 할지도 보입니다. 자료를 못 가져오면 연결과 호출을 보고, 가져온 자료를 제 업무에 맞게 보여주지 못하면 출력이나 판단 기준을 봅니다.

Step 1. Gmail에서 원하는 결과를 맞췄습니다

당시 대화는 이렇게 시작했습니다.

@skills-guide.md 참고해서 Gmail 스킬 만들려고 해.
고려해야 할 부분 이야기해줘.

AI가 어떤 기능이 필요한지, 인증은 어떻게 할지, 출력은 어떤 형태가 좋은지 물었습니다. 저는 메일 읽기와 검색, 발송, 라벨별 조회가 필요하다고 답했고, 당시 쓰던 인증 모듈도 알려줬습니다.

제가 API 호출 코드를 설계한 것은 아닙니다. 제게 필요한 일을 말했고, 구현은 AI가 맡았습니다.

첫 결과가 완벽하지는 않았습니다. 실제로 사용하면서 고쳤습니다.

첫 번째, 발신자 이름이 없었습니다.

메일 제목만 봐서는 어느 담당자가 보낸 것인지 바로 알기 어려웠습니다.

메일 목록에 발신자 이름도 보여줘.

두 번째, 날짜가 미국식으로 나왔습니다.

날짜를 매번 다시 해석하지 않도록 제가 익숙한 형식으로 바꿨습니다.

날짜 포맷을 한국식으로 바꿔줘. 2026-02-18 형태로.

세 번째, 검색 기간을 줄일 수 없었습니다.

급여 변동처럼 최근에 온 내용을 찾아야 할 때는 기간 조건이 필요했습니다.

검색할 때 기간 필터도 넣어줘.
최근 며칠 안에 온 메일만 검색할 수 있게.

카페에서 신메뉴를 개발할 때와 비슷합니다. 레시피 초안을 만들고 맛을 봅니다. ‘단맛 좀 줄여볼까’, ‘산미가 부족한데’ 하면서 조정합니다. Python 문법을 아는 것이 아니라 원하는 결과를 말로 설명하는 것입니다.

지금 gws로 메일을 다룬다면 같은 기능을 가진 프로그램부터 다시 만들 필요는 없습니다. 기존 도구가 주는 정보와 검색 조건을 먼저 확인하고, 그 결과를 어떤 형태로 정리할지 맞추면 됩니다. 실제 제목과 발신자가 필요하다면 목록 ID만 받은 것으로 끝내지 않고 메시지 상세까지 읽었는지도 봐야 합니다.

Step 2. Sheets는 다음 작업이 읽을 수 있게 했습니다

다음에는 Google Sheets를 다루는 도구를 만들었습니다. 시트 읽기와 쓰기, 범위 지정, 행 추가 같은 필요한 기능을 이야기했습니다.

여기서는 이런 수정을 요청했습니다.

시트를 읽을 때 JSON 출력 옵션도 추가해줘.
다른 스킬에서 데이터를 가져갈 때 편하게.

사람이 보기에는 표가 편합니다. 하지만 그다음 작업에서 항목별 값을 가져다 쓸 때는 이름과 값의 구조가 일정한 데이터가 편할 수 있습니다. 제가 확인할 화면과 후속 작업에 전달할 자료를 구별한 겁니다.

보기 좋게 출력됐다고 모든 일이 끝난 것은 아닙니다. 그 결과를 어디에 쓸지에 따라 필요한 형식이 달라집니다. 메일에서 읽은 변동 사항을 직원 자료와 대조하는 일이라면, 다음 단계에서 어떤 값을 찾아야 하는지도 생각해야 하겠죠.

Step 3. Drive에는 제 폴더의 사정이 있었습니다

Drive를 다루는 도구를 만들 때 AI가 물었습니다. ‘폴더 구조가 있나요?’

저는 사업장별로 나뉘고, 그 아래 월별 폴더와 처리대기·처리완료 폴더가 있다고 답했습니다.

일반적인 파일 검색 기능은 공식 자료를 보고 만들 수 있습니다. 하지만 제 자료가 어떤 이유로 나뉘어 있는지는 대화에서 알려줘야 합니다.

그래서 이런 수정을 요청했습니다.

폴더 아이디가 아니라 폴더 이름으로 검색할 수 있게 해줘.
‘처리대기’ 폴더에 뭐 있어? 라고 물으면 찾을 수 있도록.

다운로드한 파일을 어디에 둘지도 맞췄습니다. 저는 기본 다운로드 위치를 사용하도록 했습니다. 자료를 읽어온 뒤 제가 확인하고 다음 작업을 하기 편한 자리였기 때문입니다.

여기서도 사람이 폴더 ID를 외우는 것이 핵심은 아닙니다. 어떤 자료를 찾는지 설명하고 AI가 위치를 찾게 하면 됩니다. 다만 같은 이름의 폴더가 여러 개라면 사업장이나 상위 폴더를 확인해야 합니다. 이름 하나가 같다고 같은 대상이라고 볼 수는 없으니까요.

이런 차이를 지침에 남길 수 있습니다

당시에는 서비스별 도구를 만들었지만, 지금 제가 설명하고 싶은 핵심은 사용하며 맞춘 기준을 다음 작업에서도 쓰게 하는 것입니다.

아래는 이를 설명하려고 새로 만든 최소 SKILL.md 예시입니다. 제 Gmail 스킬이나 실행 프로그램을 제공하는 것이 아닙니다. 이미 가져온 메일 정보를 어떻게 정리할지 보여주는 공개 예시입니다.

---
name: mail-review-output
description: 가져온 메일 정보를 발신자와 날짜 중심의 검토용 목록으로 정리할 때 사용한다.
---

# 메일 검토 목록

1. 가져온 정보에 발신자, 제목, 날짜가 있는지 확인한다.
2. 날짜를 YYYY-MM-DD로 맞추고 발신자와 제목을 함께 보여준다.
3. 없는 정보는 추측해 채우지 말고 확인이 필요하다고 표시한다.
4. 요청한 기간과 실제로 조회한 범위를 결과에 함께 적는다.

위쪽 --- 사이의 내용은 스킬의 이름과 사용 시점을 설명하는 메타데이터입니다. 아래쪽은 사용할 때 따를 작업 지침입니다.

예를 들어 ‘보낸 사람: A회사 담당자, 날짜: 2026-02-18, 제목: 자료 전달’이라는 정보를 가져왔다면, 그 항목을 일정한 순서와 날짜 형식으로 보여주도록 한 겁니다. 이는 설명용 입력이며 실제 메일을 조회한 결과가 아닙니다. 발신자 정보가 없다면 이 지침은 없는 이름을 지어내지 않고 부족하다고 표시하는 쪽으로 안내합니다.

기간도 마찬가지입니다. 최근 5일을 부탁했는데 한 페이지의 일부만 읽었다면 그 차이가 보여야 합니다. ‘정리된 표가 나왔다’와 ‘필요한 범위를 확인했다’는 다른 문제입니다.

현재 Claude Code는 이 메타데이터의 모든 필드를 선택 사항으로 허용하고 description을 권장합니다. 공통 Agent Skills 규격에서는 name과 description이 필수입니다. 이 예시는 둘을 포함했지만 ‘Claude Code에서는 두 필드가 없으면 절대 사용할 수 없다’는 뜻은 아닙니다. Claude Code 형식 안내 · 공통 Agent Skills 규격

한 가지 더 구별할 부분이 있습니다. allowed-tools는 해당 스킬을 호출한 턴에서 지정한 도구를 승인 요청 없이 사용할 수 있게 하는 필드입니다. 그 밖의 도구를 모두 막는 제한 목록은 아닙니다. 기존 권한 규칙도 적용됩니다. 이번 예시에는 필요하지 않아 넣지 않았습니다.

대화에서 정해지는 것

Gmail, Sheets, Drive를 만들며 반복해서 정한 것은 비슷했습니다.

정할 것 제가 다룬 내용
근거 스킬 형식과 연결 기능의 공식 안내
원하는 기능 메일 검색, 시트 읽기, 파일 찾기와 이동
실행 조건 당시 인증 방식과 사용할 도구
결과가 놓일 곳 제가 다음 작업을 하기 편한 위치
내 업무의 사정 발신자 확인, 날짜 형식, 검색 기간, 사업장별 폴더

처음부터 다 알 필요는 없습니다. AI가 물으면 답하고, 실제로 써본 뒤 어긋난 부분을 고치면 됩니다.

다만 ‘잘 만들어줘’만으로는 제가 중요하게 보는 것이 드러나지 않습니다. 발신자가 빠졌는지, 어느 기간을 봤는지, 이름이 같은 폴더를 잘 골랐는지. 결과를 보며 이런 차이를 알려주는 것이 제 역할이었습니다.

공식 문서가 형식을 잡고, 대화가 제 업무의 세부를 채웠습니다. 마지막으로 실제 결과가 그 기준에 맞는지 봤고요.

지금 시작하는 분이라면

Google을 연결하려는 분은 현재 연결 안내인 18편을 먼저 보면 됩니다. 이 회고 속 자체 인증 모듈과 Python 프로그램을 다시 만드는 과정이 필수는 아닙니다.

스킬 개념부터 보고 싶은 분은 12편으로 이어가세요. 다음 제작 회고에서는 Calendar와 Tasks를 다루며 시간과 할 일의 기준을 어떻게 정했는지 살펴보겠습니다.

Subscribe to 비개발자를 위한 Claude Code | 일을 잘하기 위한 AI Workspace

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
[email protected]
Subscribe