Google Calendar Sync Skill

Google Calendar Sync

Overview

여러 Google 계정(회사, 개인 등)의 캘린더를 한 번에 조회하여 통합된 일정을 제공한다.

사전 인증된 refresh token 사용 (매번 로그인 불필요)
Subagent 병렬 실행으로 빠른 조회
계정 간 일정 충돌 감지

트리거 조건

조회

"오늘 일정", "이번 주 일정 알려줘"
"캘린더 확인", "스케줄 뭐야"
"다음 미팅", "내일 뭐 있어"
"일정 충돌 확인해줘"

생성

"새 일정 만들어줘", "미팅 추가해줘"
"내일 3시에 회의 잡아줘"
"다음 주 월요일 팀 미팅 생성"

수정

"일정 시간 변경해줘", "미팅 시간 바꿔줘"
"sync 미팅 14시 21분으로 변경"
"회의 제목 수정해줘"

삭제

"일정 삭제해줘", "미팅 취소해줘"
"이벤트 지워줘"

사전 요구사항

1. Google Cloud 프로젝트 설정

Google Cloud Console에서 프로젝트 생성
Calendar API 활성화
OAuth 2.0 Client ID 생성 (Desktop 유형)
credentials.json 다운로드 → references/credentials.json에 저장

2. 계정별 인증 (최초 1회)

# 회사 계정
uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account work

# 개인 계정
uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account personal

브라우저에서 Google 로그인 → refresh token이 accounts/{name}.json에 저장됨

워크플로우

1. 등록된 계정 확인

ls .claude/skills/google-calendar/accounts/
# → work.json, personal.json

2. Subagent 병렬 실행

각 계정별로 Task 도구를 병렬로 호출:

# 병렬 실행 - 단일 메시지에 여러 Task 호출
Task(subagent_type="general-purpose", prompt="fetch calendar for work account")
Task(subagent_type="general-purpose", prompt="fetch calendar for personal account")

각 subagent는 다음을 실행:

uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account {account_name} \
  --days 7

3. 결과 통합

모든 계정의 이벤트를 시간순 정렬
동일 시간대 이벤트 = 충돌로 표시
계정별 색상/아이콘 구분

출력 형식

📅 2026-01-06 (월) 일정

[09:00-10:00] 🔵 팀 스탠드업 (work)
[10:00-11:30] 🟢 치과 예약 (personal)
[14:00-15:00] 🔵 고객 미팅 - 삼양 (work)
              ⚠️ 충돌: 개인 일정과 겹침
[14:00-14:30] 🟢 은행 방문 (personal)

📊 오늘 총 4개 일정 (work: 2, personal: 2)
   ⚠️ 1건 충돌

실행 예시

사용자: "이번 주 일정 알려줘"

1. accounts/ 폴더 확인
   └── 등록된 계정: work, personal

2. Subagent 병렬 실행
   ├── Task: work 계정 이벤트 조회
   └── Task: personal 계정 이벤트 조회

3. 결과 수집 (각 subagent 완료 대기)
   ├── work: 8개 이벤트
   └── personal: 3개 이벤트

4. 통합 및 정렬
   └── 11개 이벤트, 2건 충돌 감지

5. 출력
   └── 일별로 그룹화하여 표시

에러 처리

| 상황 | 처리 | |------|------| | accounts/ 폴더 비어있음 | 초기 설정 안내 (setup_auth.py 실행 방법) | | 특정 계정 토큰 만료 | 해당 계정 재인증 안내, 나머지 계정은 정상 조회 | | API 할당량 초과 | 잠시 후 재시도 안내 | | 네트워크 오류 | 연결 확인 요청 |

Scripts

| 파일 | 용도 | |------|------| | scripts/setup_auth.py | 계정별 OAuth 인증 및 token 저장 | | scripts/fetch_events.py | 특정 계정의 이벤트 조회 (CLI) | | scripts/manage_events.py | 이벤트 생성/수정/삭제 (CLI) | | scripts/calendar_client.py | Google Calendar API 클라이언트 라이브러리 |

일정 관리 (생성/수정/삭제)

일정 생성

uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "팀 미팅" \
    --start "2026-01-06T14:00:00" \
    --end "2026-01-06T15:00:00" \
    --account work

종일 일정 생성

uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "연차" \
    --start "2026-01-10" \
    --end "2026-01-11" \
    --account personal

일정 수정

uv run python .claude/skills/google-calendar/scripts/manage_events.py update \
    --event-id "abc123" \
    --summary "팀 미팅 (변경)" \
    --start "2026-01-06T14:21:00" \
    --account work

일정 삭제

uv run python .claude/skills/google-calendar/scripts/manage_events.py delete \
    --event-id "abc123" \
    --account work

옵션

| 옵션 | 설명 | |------|------| | --summary | 일정 제목 | | --start | 시작 시간 (ISO format: 2026-01-06T14:00:00 또는 2026-01-06) | | --end | 종료 시간 | | --description | 일정 설명 | | --location | 장소 | | --attendees | 참석자 이메일 (쉼표 구분) | | --account | 계정 (work, personal 등) | | --adc | gcloud ADC 사용 | | --timezone | 타임존 (기본값: Asia/Seoul) | | --json | JSON 형식 출력 |

References

| 문서 | 내용 | |------|------| | references/setup.md | 초기 설정 상세 가이드 | | references/credentials.json | Google OAuth Client ID (gitignore) |

파일 구조

.claude/skills/google-calendar/
├── SKILL.md                    # 이 파일
├── scripts/
│   ├── calendar_client.py      # API 클라이언트
│   ├── setup_auth.py           # 인증 설정
│   ├── fetch_events.py         # 이벤트 조회 CLI
│   └── manage_events.py        # 이벤트 생성/수정/삭제 CLI
├── references/
│   ├── setup.md                # 설정 가이드
│   └── credentials.json        # OAuth Client ID (gitignore)
└── accounts/                   # 계정별 토큰 (gitignore)
    ├── work.json
    └── personal.json

보안 주의사항

accounts/*.json: refresh token 포함, 절대 커밋 금지
references/credentials.json: Client Secret 포함, 커밋 금지
.gitignore에 추가 필수

Agent Skills: Google Calendar Sync

Install this agent skill to your local

Skill Files