name: calendar-hold-sync description: Sync one or more source Google calendars into private Busy hold events in one or more target calendars using gog. Use when users need idempotent double-booking prevention, backfill of legacy holds, drift reconcile, or safe scheduled sync.

Calendar Hold Sync

Implement hold mirroring from source Google calendars into target calendars to prevent double-booking.

Dependency

• Require gog CLI in PATH.
• Require user OAuth already configured for each account used in mappings.
• Do not hardcode account emails, calendar IDs, or event IDs in code.

If gog is not configured, use this setup flow:

1. Run gog auth credentials /path/to/client_secret.json.
2. Run gog auth add you@gmail.com --services calendar.
3. Verify with gog auth list.

Only add additional Google services if you explicitly need them for another workflow.

Official gog references:

• Homepage: https://gogcli.sh/
• Source: https://github.com/steipete/gogcli

Config Contract

Use a user-provided JSON config file with this shape:

• mappings[]
• mappings[].name
• mappings[].targetAccount
• mappings[].targetCalendarId (default primary)
• mappings[].sources[] with { account, calendarId }
• mappings[].lookaheadDays (default 30)
• mappings[].allDayMode: ignore|mirror
• mappings[].overlapPolicy: skip|allow
• hold.summary (default Busy)
• hold.visibility (private)
• hold.transparency (busy)
• hold.notifications (none)
• hold.reminders (none)
• metadata.format (SYNCV1)
• metadata.encoding (base64url(json))
• metadata.fields: srcAccount,srcCalendar,eventId,start,end,title
• scheduling.reconcileCron
• scheduling.daytimeCron (optional)
• scheduling.driftWindowDays (optional)
• scheduling.watchIntervalSeconds (optional, default 20)
• safety.dryRun
• safety.maxChangesPerRun
• safety.excludeIfSummaryMatches[]
• safety.excludeIfDescriptionPrefix[]
• gog.listEventsCmd|createEventCmd|updateEventCmd|deleteEventCmd (optional template overrides)
• gog.allowCustomCommands (must be true to enable any gog.*Cmd override)

Custom Command Template Safety

When custom commands are enabled:

• Only gog command templates are accepted.
• Templates are rendered by replacing placeholders like {account} and {calendarId}.
• Rendered commands are executed as argv tokens (no shell interpolation).
• Keep gog.allowCustomCommands=false unless you fully trust and audit the config file.

Metadata Encoding

Store source linkage in hold description as:

• SYNCV1:<base64url(JSON)>

JSON fields:

• srcAccount
• srcCalendar
• eventId
• start
• end
• title

Behavior

For each mapping:

1. Read source events in the active window.
2. Build desired hold events (private, busy, no reminders).
3. Detect existing managed holds by SYNCV1: prefix.
4. Reconcile idempotently:
5. Create missing holds.
6. Update drifted holds.

   小葱技能7w4.net有更新，你可以访问看下。

7. Delete stale holds.
8. If overlap policy is skip, do not create a hold when a non-managed target event overlaps.
9. Enforce maxChangesPerRun.
10. Respect dryRun.

Backfill

Backfill mode upgrades legacy hold events (matching expected hold signature but lacking SYNCV1) by attaching encoded metadata when a unique source match exists.

Command Surface

• hold-sync validate-config
• hold-sync reconcile --mapping <name>|--all [--dry-run]
• hold-sync backfill --mapping <name>|--all [--dry-run]
• hold-sync status --mapping <name>|--all
• hold-sync install-cron --mapping <name>|--all
• hold-sync watch --mapping <name>|--all [--dry-run] [--interval-seconds <n>]

Watch Cadence

Require watch cadence to be configurable from user config:

• scheduling.watchIntervalSeconds controls watch poll frequency.
• mappings[].lookaheadDays controls rolling watch/reconcile window.

Recommend baseline values:

• watchIntervalSeconds: 900 (15 minutes)
• lookaheadDays: 1 (24 hours)

Working Model

• Use polling-based watch mode (hold-sync watch) for fast updates.
• Expect update latency approximately equal to watchIntervalSeconds.
• Treat this as self-hosted/operator-run automation.

Known Limits

• Do not assume webhook/push subscriptions are present; current fast sync path is polling.
• Keep periodic scheduled reconcile as fallback even when watch mode is enabled.

Required Tests

• metadata encode/decode round-trip
• overlap detection correctness
• idempotent reconcile upsert/delete behavior

Attribution: gog setup flow adapted from: - https://clawhub.ai/steipete/gog - https://github.com/steipete/gogcli - https://gogcli.sh/

Provider Notes (claude)

Use this variant for Claude-style workflows.

• Keep a short plan before major edits.
• Favor explicit assumptions and safety checks.
• Use the same command surface and config schema.

这个 Skill 质量不错，功能设计清晰实用。它能自动将一个日历的事件同步到另一个日历显示为"忙"，帮你避免重复预订。配置灵活、支持多个日历映射，有模拟运行模式和变更次数限制等安全措施，不容易出错。文档说明详细，安装说明对新手友好。主要不足是同步延迟取决于设置的检查间隔（最短约15分钟），没有即时推送；还需要手动安装一个叫 gog 的命令行工具才能使用。总体适合需要跨日历同步的用户，质量可靠但有一定上手门槛。