--- title: "calendar" description: "아이클라우드·네이버(및 커스텀 CalDAV) 캘린더에서 일정을 조회·검색·추가·수정·삭제하고 빈 시간을 찾아주는 스킬입니다. \"내일 3시 회의 추가해줘\", \"이번 주 일정 보여줘\", \"다음 주에 1시간 빈 시간 찾아줘\", \"OO 프로젝트 회의 다 찾아줘\", \"그 약속 취소해줘\"처럼 말하면 됩니다. 반복 일정·알림·시간대(KST)와 ETag 동시성, 삭제 확인 게이트를 지원합니다. [책임 경계] 본 스킬은 일정 CRUD·빈 시간 탐색 전담 — 아침 브리핑 페이지(오늘 일정+미회신 메일 한 장)는 itda-work:morning-brief, 메일 읽기·발송은 itda-work:email." pack: itda-work slug: calendar status: active tags: ["calendar", "caldav", "icloud", "apple", "naver", "event", "schedule", "recurrence", "rrule", "valarm", "alarm", "reminder", "timezone", "etag", "ical", "icalendar", "multi-account", "custom-caldav", "free-slots", "availability", "search"] --- # calendar 사용 가이드 네이버·아이클라우드(및 표준 CalDAV) 캘린더의 일정을 자연어로 조회·검색·추가·수정·삭제하고, 빈 시간도 찾아줍니다. **아래처럼 `/calendar` 뒤에 지침을 붙여 입력하면 됩니다** — `/calendar 이번 주 일정 보여줘`, `/calendar 내일 3시 회의 추가해줘`, `/calendar 다음 주에 1시간 빈 시간 찾아줘`처럼요. 자연어로 말해도 동작합니다. 터미널 명령을 직접 입력할 필요는 없습니다. --- ## 지원하는 캘린더 :::cards - [네이버 캘린더](https://calendar.naver.com) — 네이버 ID(전체 이메일) + 앱 비밀번호 - [아이클라우드 캘린더](https://www.icloud.com/calendar) — Apple 계정 + 앱 전용 비밀번호 - 커스텀 CalDAV — [Fastmail](https://www.fastmail.com) · [Nextcloud](https://nextcloud.com) · [mailbox.org](https://mailbox.org) · [Posteo](https://posteo.de) · [Zoho](https://www.zoho.com/calendar/) 등 · 서버 주소 + 앱 비밀번호 ::: 세 종류 모두 **표준 CalDAV 프로토콜**과 **앱(전용) 비밀번호**로 연결합니다. itda-email로 네이버·아이클라우드 메일을 이미 쓰고 있다면, **그때 발급한 앱 비밀번호를 그대로 재사용**할 수 있습니다(추가 발급 불필요). > **구글 캘린더는 이 스킬에서 지원하지 않습니다.** 구글 캘린더는 Claude의 **공식 Google Calendar 커넥터**로 연결해 쓰세요(이미 지원됩니다). 마이크로소프트(Outlook)·카카오 캘린더도 인증 방식이 달라 현재 지원하지 않습니다. --- ## 처음 설정하기 — 네이버 캘린더 네이버는 **메일과 같은 앱 비밀번호**를 씁니다. itda-email로 네이버 메일을 이미 쓰고 있다면 같은 앱 비밀번호를 그대로 사용하면 됩니다(추가 발급 불필요). ### 1. 2단계 인증 켜기 앱 비밀번호는 **2단계 인증**이 켜져 있어야 발급됩니다. 네이버 → **내 정보 → 보안 설정 → 2단계 인증**에서 켭니다. ### 2. 앱 비밀번호 발급 **내 정보 → 보안 설정 → 애플리케이션 비밀번호 관리 → 발급** (메일·캘린더 공용으로 동작합니다). ### 3. 자격증명 등록 발급받은 값을 **`.env` 파일에 넣어 두면 (권장)** 스킬이 자동으로 찾아 읽습니다. 로그인 아이디는 **전체 이메일**을 씁니다. - **`.env` 파일 (권장)** — 작업 폴더(Cowork 연결 폴더 / Claude Code 프로젝트 루트)(연결한 폴더가 여러 개면 아무 폴더나) 루트에 `.env` 파일을 만들고 아래 줄을 넣어 둡니다. 점(`.`)으로 시작하는 파일을 만들기 어렵다면 **`환경변수.txt`** 라는 이름으로 만들어도 똑같이 읽힙니다(메모장이 `.txt` 를 붙여 `.env.txt` 가 되어도 됩니다). - **Claude Code를 쓰면** — 프로젝트 `CLAUDE.md`에 아래 줄을 적어두면 됩니다. ```dotenv NAVER_EMAIL=you@naver.com NAVER_APP_PASSWORD=발급된_앱비밀번호 ``` > 네이버 앱 비밀번호 발급 절차는 [네이버 앱 비밀번호 발급 가이드](https://itda.work/credentials/naver-app-password/)를 참고하세요. Claude Desktop의 "Claude 지침"(설정 → 일반)이나 Claude Code의 `CLAUDE.md`에 적는 방식도 동작하지만, 대화 컨텍스트에 값이 노출되므로 `.env` 파일을 권장합니다. (개발자는 셸 환경변수도 가능합니다.) ### 4. 연결 확인 설정이 끝나면 `/calendar 네이버 캘린더 연결됐는지 확인해줘`라고 입력해보세요. 연결 상태와 캘린더 개수를 알려줍니다. > 네이버는 일정 조회 방식이 아이클라우드보다 제한적이라 내부적으로 보정 로직이 동작하지만, 사용법은 동일합니다. 다만 일정이 많을수록 조회가 느려집니다(아래 "조회가 느릴 때" 참고). --- ## 아이클라우드(iCloud) 캘린더 캘린더는 **애플 메일과 같은 앱 전용 비밀번호**를 씁니다. 이미 itda-email로 아이클라우드 메일을 쓰고 있다면, 그때 발급한 같은 앱 전용 비밀번호를 그대로 사용하면 됩니다(추가 발급 불필요). ### 1. 2단계 인증 켜기 (필수) 앱 전용 비밀번호는 Apple 계정에 **2단계 인증(2FA)** 이 켜져 있어야 발급됩니다. `아이폰 설정 → [내 이름] → 로그인 및 보안 → 2단계 인증`에서 켭니다. ### 2. 앱 전용 비밀번호 발급 1. 웹브라우저에서 [account.apple.com](https://account.apple.com) 로그인 2. **로그인 및 보안 → 앱 전용 비밀번호** 선택 3. **앱 전용 비밀번호 생성** → 이름 입력(예: `itda-calendar`) → 생성 4. 화면에 나온 16자리 비밀번호(`xxxx-xxxx-xxxx-xxxx`)를 복사 (다시 볼 수 없으니 바로 저장) ### 3. 자격증명 등록 발급받은 값을 **`.env` 파일에 넣어 두면 (권장)** 스킬이 자동으로 찾아 읽습니다. Claude Desktop의 "Claude 지침"(설정 → 일반) 또는 `CLAUDE.md`(Claude Code)에 적는 방식도 동작하지만, 대화 컨텍스트에 값이 노출되므로 `.env`를 권장합니다. ```dotenv ICLOUD_EMAIL=you@icloud.com ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx ``` > 앱 전용 비밀번호 발급 절차는 [iCloud 앱 전용 비밀번호 발급 가이드](https://itda.work/credentials/icloud-app-password/)를 참고하세요. > 앞뒤 하이픈 포함/제외 모두 동작하지만, 발급 화면에 보인 그대로 넣는 것을 권장합니다. (개발자는 셸 환경변수도 쓸 수 있습니다.) ### 4. 연결 확인 `/calendar 아이클라우드 캘린더 연결됐는지 확인해줘`라고 입력하면 연결 상태와 캘린더 개수를 알려줍니다. --- ## 커스텀 CalDAV (Fastmail · Nextcloud · mailbox.org · Posteo · Zoho …) 표준 CalDAV 서버는 서버 주소(`CALDAV_URL`)로 직접 연결합니다. 대부분 2단계 인증을 켜면 **앱 비밀번호**가 필요합니다(일반 비밀번호는 거부될 수 있음). 아래 값을 **`.env` 파일에 넣어 두면 (권장)** 스킬이 자동으로 찾아 읽습니다. Claude Desktop의 "Claude 지침"(설정 → 일반) 또는 `CLAUDE.md`(Claude Code)에 적는 방식도 동작하지만, 대화 컨텍스트에 값이 노출되므로 `.env`를 권장합니다(개발자는 셸 환경변수도 가능). ```dotenv CALDAV_URL=https://caldav.fastmail.com/dav/calendars/user/you@fastmail.com/ CALDAV_USER=you@fastmail.com CALDAV_PASSWORD=앱비밀번호 ``` 서버별 CalDAV 주소 예시: | 서비스 | CALDAV_URL 예시 | 비고 | |--------|-----------------|------| | Fastmail | `https://caldav.fastmail.com/dav/...` | 앱 비밀번호 필수 | | Nextcloud | `https://<호스트>/remote.php/dav` | 앱 비밀번호 권장 | | mailbox.org | `https://dav.mailbox.org` | 2FA 시 앱 비밀번호 | | Posteo | `https://posteo.de:8443/` | **포트 8443 명시** | > 포트가 443이 아닌 서버(Posteo `:8443` 등)는 주소에 포트를 반드시 포함하세요. --- ## 자주 쓰는 요청 자연어로 편하게 말해도 동작합니다. 아래처럼 `/calendar` 뒤에 원하는 내용을 붙이면 그대로 실행됩니다. | 하고 싶은 것 | 이 지침을 입력하세요 | |--------------|-----------------| | 일정 확인 | `/calendar 이번 주 일정 보여줘`, `/calendar 오늘 뭐 있어?`, `/calendar 6월 일정 알려줘` | | 특정 캘린더만 | `/calendar 강의 일정 캘린더만 보여줘` | | 일정 검색 | `/calendar OO 프로젝트 회의 다 찾아줘`, `/calendar 강남에서 하는 일정 찾아줘` | | 빈 시간 찾기 | `/calendar 다음 주에 1시간 빈 시간 찾아줘`, `/calendar 이번 주 오후에 회의 잡을 수 있는 시간 알려줘` | | 일정 상세 | `/calendar 그 회의 자세히 보여줘` | | 일정 추가 | `/calendar 내일 오후 3시 강의 일정 추가`, `/calendar 금요일 점심 약속 잡아줘` | | 겹침 확인하며 추가 | `/calendar 겹치는 일정 없는지 확인하고 내일 2시에 회의 잡아줘` (겹쳐도 일정은 만들어지고, 겹침을 알려줍니다) | | 반복 일정 | `/calendar 매주 월요일 9시 스탠드업 추가` | | 알림 | `/calendar 회의 10분 전에 알림 설정해서 추가` | | 수정 | `/calendar 그 회의 30분 미뤄줘`, `/calendar 제목 바꿔줘` | | 삭제 | `/calendar 토요일 약속 취소해줘` (삭제 전 확인을 거칩니다) | | 반복 중 한 번만 취소 | `/calendar 다음 주 월요일 스탠드업만 빼줘` (그 회차만 사라지고 매주 반복은 유지됩니다) | | 여러 계정일 때 | `/calendar 회사 네이버 계정으로 이번 주 일정 보여줘` | --- ## 안 될 때 | 증상 | 원인 / 해결 | |------|-------------| | "자격증명이 없다"는 안내 (`credentials_missing`) | **`.env` 파일**(또는 Claude 지침·`CLAUDE.md`)에 해당 캘린더의 이메일·앱 비밀번호가 비어 있음. 위 "처음 설정하기" 확인 | | "인증 실패" 안내 (`auth_failed`) | 일반 비밀번호를 넣었거나 앱 비밀번호 오타. **앱(전용) 비밀번호**를 다시 발급 | | "어느 계정인지 모르겠다"는 안내 (`account_required`) | 같은 서비스에 계정이 여러 개. "회사 계정으로"처럼 어느 계정인지 함께 말하세요 | | "다른 곳에서 바뀌었다"는 안내 (`etag_conflict`) | 그 사이 다른 기기에서 일정을 바꿈. "다시 조회해줘" 후 수정 | | 네트워크/인증서 오류 | 잠시 후 다시 시도. 커스텀 서버는 주소·포트를 확인 | | 일정이 안 보임 | `/calendar 지난달부터 다음 달까지 보여줘`처럼 기간을 넓히거나, `/calendar 내 캘린더 목록 보여줘`로 캘린더 이름을 확인 | | 빈 시간에 종일 일정이 걸림 | 배송 예정 같은 정보성 종일 일정도 기본은 '바쁨'으로 봅니다. `/calendar 종일 일정은 빼고 빈 시간 찾아줘`라고 말하면 제외합니다 | | 빈 시간이 내 기대와 다름 | 기본은 **평일 09~18시, 내 캘린더 기준**입니다. "주말 포함해서", "저녁 시간대로"처럼 조건을 함께 말하세요. 다른 사람의 일정은 볼 수 없습니다 | --- ## 조회가 느릴 때 - 전체 캘린더를 한꺼번에 보면 캘린더 수에 비례해 느려집니다. 자주 보는 캘린더가 있으면 "○○ 캘린더만 보여줘"처럼 좁히세요. - **네이버는 일정이 많을수록 느려집니다**(서버가 기간 필터를 지원하지 않아 전체를 불러옵니다). 한 캘린더를 지정하는 것을 권장합니다. 아이클라우드는 일정 수에 둔감합니다. - 캘린더를 새로 추가/삭제했는데 목록에 안 보이면 `/calendar 캘린더 목록 새로 고쳐서 보여줘`라고 입력하세요(평소엔 캐시 덕분에 더 빠릅니다). ## 안전장치 - **삭제는 항상 확인을 거칩니다.** 어떤 일정을 지울지 먼저 보여주고, 동의해야 실제로 삭제합니다. - **수정 충돌 방지.** 조회한 뒤 그 사이 다른 곳에서 같은 일정이 바뀌었다면, 덮어쓰지 않고 알려줍니다. - **개인정보 보호.** 외부에서 받은 초대 일정의 제목·설명은 Claude에 전달하기 전에 정화(sanitize)됩니다.