apple-calendar
Read and create Calendar.app events through a local macOS helper. Use when the user wants to inspect Apple Calendar calendars, summarize a day, check upcoming events, or create a new Calendar.app event from Codex.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- apple-calendar
- description
- Read and create Calendar.app events through a local macOS helper. Use when the user wants to inspect Apple Calendar calendars, summarize a day, check upcoming events, or create a new Calendar.app event from Codex.
03 SKILL.md 正文
Apple Calendar
Overview
Use this skill to work with the local macOS Calendar app through the bundled helper at ../../scripts/apple_calendar.py. The helper now uses an EventKit/Swift backend for data operations. Prefer the quick commands today, tomorrow, agenda, free, and add over lower-level calls unless you need raw JSON or direct lifecycle operations like update-event, delete-event, reminder changes, or .ics export/import.
Workflow
- Confirm the task is meant for Apple Calendar on macOS, not Google Calendar or Outlook.
- Never run Calendar helper commands in parallel. The helper now serializes access to Calendar.app, and parallel calls only add latency.
- For daily summaries, start with
todayortomorrow. These default to the configured personal calendars in../../config.jsoninstead of scanning every subscribed calendar. - Use
agendaorlist-eventsonly when you need a specific date window or raw JSON payload. - Normalize relative dates into exact local timestamps before reasoning about conflicts or creating an event.
- Prefer
add --if-freefor new events so overlapping slots are blocked unless the user explicitly wants a conflict. - For changing an existing event, use
find-eventsfirst when you do not already have the eventuid.
Commands
List calendars and configured aliases:
/usr/bin/python3 ../../scripts/apple_calendar.py list-calendars
Today's agenda across the configured personal calendars:
/usr/bin/python3 ../../scripts/apple_calendar.py today
Tomorrow's agenda:
/usr/bin/python3 ../../scripts/apple_calendar.py tomorrow
List one day's events from a named calendar or alias:
/usr/bin/python3 ../../scripts/apple_calendar.py list-events \
--calendar "prace" \
--date today
Human-readable agenda for a specific day:
/usr/bin/python3 ../../scripts/apple_calendar.py agenda \
--date 2026-03-27
Find free windows:
/usr/bin/python3 ../../scripts/apple_calendar.py free \
--date today \
--slot-minutes 30
Quick-add a new event with conflict protection:
/usr/bin/python3 ../../scripts/apple_calendar.py add \
--calendar "doma" \
--title "Design Review" \
--date tomorrow \
--start-time 15:00 \
--duration-minutes 30 \
--location "Zoom" \
--notes "Bring the launch checklist." \
--if-free
Find an event by title and day:
/usr/bin/python3 ../../scripts/apple_calendar.py find-events \
--calendar doma \
--title "Stolní Tenis" \
--date today
Update an event:
/usr/bin/python3 ../../scripts/apple_calendar.py update-event \
--calendar doma \
--title "Stolní Tenis" \
--date today \
--set-location "Velká nad Veličkou 276"
Replace reminders:
/usr/bin/python3 ../../scripts/apple_calendar.py set-reminder \
--calendar doma \
--title "Stolní Tenis" \
--date today \
--minutes-before 30
Clear reminders:
/usr/bin/python3 ../../scripts/apple_calendar.py clear-reminders \
--calendar doma \
--title "Stolní Tenis" \
--date today
Export to .ics:
/usr/bin/python3 ../../scripts/apple_calendar.py export-ics \
--calendar doma \
--date tomorrow \
--days 1 \
--output /tmp/my-events.ics
Import from .ics:
/usr/bin/python3 ../../scripts/apple_calendar.py import-ics \
--calendar doma \
--input /tmp/my-events.ics \
--if-free
Delete an event:
/usr/bin/python3 ../../scripts/apple_calendar.py delete-event \
--calendar doma \
--title "Stolní Tenis" \
--date today
Safety
- Treat
addandcreate-eventas write operations. - Do not invent calendar names. Use the exact name or alias returned by
list-calendars. - The helper serializes Calendar.app access with a lock and timeout; avoid parallel tool calls into the helper.
- Use
--if-freeby default for new events. Use--allow-conflictonly when the user explicitly wants an overlapping event. - Duplicate detection defaults to
title+start+end. Set--dedupe-by noneonly when a true duplicate is intended. - macOS may prompt for Calendar automation access the first time the helper runs.
Output Conventions
- Use exact dates and local times in the response.
- Summaries should explain why a window is free or blocked instead of dumping raw JSON.
- When creating an event, echo the final title, calendar, start, end, and any location or notes that were applied.
- When
today,tomorrow,agenda, orfreeis sufficient, prefer those outputs over raw JSON.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.