Quick Google Calendar Command Line Interface

Google Calendar via gcalcli: today-only agenda by default, bounded meaning-first lookup via agenda scans, and fast create/delete with verification--optimized...

Security Scan

The skill is internally consistent with its stated purpose (a gcalcli instruction set) and does not request unrelated credentials, installs, or network endpoints beyond what gcalcli normally uses.

Purpose & Capability

Name/description match the runtime instructions: the skill requires the gcalcli binary and all instructions center on using gcalcli to read/search/create/delete calendar events. No unrelated binaries, services, or env vars are requested.

Instruction Scope

The SKILL.md stays within calendar management using gcalcli. One intentional UX choice: the skill will skip explicit user confirmation for destructive actions when it deems a match unambiguous. The SKILL.md documents safeguards (bounded windows, single-match requirement, post-delete verification, disambiguation on ambiguity). This is a policy decision rather than incoherence, but users should be aware of the auto-execution behavior for 'unambiguous' deletes/edits.

Install Mechanism

Instruction-only skill with no install spec. This is low-risk: nothing is downloaded or written by the skill itself. It simply assumes gcalcli is installed already.

Credentials

The skill declares no required environment variables or credentials. README explains that gcalcli itself uses OAuth2 and stores tokens locally; that is expected for a Google Calendar client. Note: README shows an example passing client-id/client-secret on gcalcli command line — this is user configuration guidance, not a declared requirement of the skill, but passing secrets on the command line can expose them via process listings and the operator should avoid that practice.

Persistence & Privilege

Skill does not request persistent/always-on privileges (always: false). It does not modify other skills or system-wide settings. Autonomous invocation (disable-model-invocation: false) is platform default and not excessive here.

Assessment

This skill is coherent for managing Google Calendar via the gcalcli CLI. Before installing: (1) ensure you already have gcalcli installed and authenticated (gcalcli stores OAuth tokens locally); (2) review and accept the policy that the agent may perform unambiguous deletes/edits without an extra confirmation prompt — change the SKILL.md if you prefer always asking; (3) avoid passing client secrets on the command line (the README example does so for demonstration but that can leak via process listings); and (4) run in an environment you trust because the skill will invoke gcalcli which has access to your calendar data via local OAuth tokens.

quick-gcalcli

Use gcalcli to read/search/manage Google Calendar with minimal tool calls and minimal output.

Quick Setup

Before using this skill, please refer to the README.md file in this skill's directory for detailed setup instructions. The setup process includes installing gcalcli, configuring OAuth2 credentials, and setting up the default calendar and timezone.

Rules

CLI flag placement (critical)

• Global flags (--nocolor, --calendar) go BEFORE the subcommand.
• Subcommand-specific flags go AFTER the subcommand name.
• Example: gcalcli --nocolor delete --iamaexpert "query" start end — NOT gcalcli --nocolor --iamaexpert delete ....
• This applies to ALL subcommand flags: --iamaexpert (delete), --noprompt/--allday (add), --use-legacy-import (import), etc.

Output & language

• Don't print CLI commands/flags/tool details unless the user explicitly asks (e.g. "show commands used", "/debug", "/commands").
• If asked for commands: print ALL executed commands in order (including retries) and nothing else.
• Don't mix languages within one reply.
• Be concise. No scope unless nothing found.

Dates & formatting

• Human-friendly dates by default. ISO only if explicitly requested.
• Don't quote event titles unless needed to disambiguate.

Calendar scope

• Trust gcalcli config (default/ignore calendars). Don't broaden scope unless user asks "across all calendars" or results are clearly wrong.

Agenda (today-only by default)

• If user asks "agenda" without a period, return today only.
• Expand only if explicitly asked (tomorrow / next N days / date range).

Weekday requests (no mental math)

If user says "on Monday/Tuesday/..." without a date:

1. fetch next 14 days agenda once,
2. pick matching day/event from tool output,
3. proceed (or disambiguate if multiple).

Finding events: prefer deterministic agenda scan (meaning-first)

When locating events to cancel/delete/edit:

• Prefer agenda over search.
• Use a bounded window and match events by meaning (semantic match) rather than exact text.
• Default locate windows:
  • If user gives an exact date: scan that day only.
  • If user gives a weekday: scan next 14 days.
  • If user gives only meaning words ("train", "lecture", etc.) with no date: scan next 30 days first.
  • If still not found: expand to 180 days and say so only if still empty.

Use gcalcli search only as a fallback when:

• the time window would be too large to scan via agenda (token-heavy), or
• the user explicitly asked to "search".

Search (bounded)

• Default search window: next ~180 days (unless user specified otherwise).
• If no matches: say "No matches in next ~6 months (<from>-><to>)" and offer to expand.
• Show scope only when nothing is found.

Tool efficiency

• Default: use --nocolor to reduce formatting noise and tokens.
• Use --tsv only if you must parse/dedupe/sort.

Actions policy (optimized for conversational speed)

This skill is designed for personal assistant use where the user expects fast, low-friction calendar management. The confirmation policy below is an intentional UX choice — see README.md for rationale and safety guards.

Unambiguous actions: execute immediately

For cancel/delete/edit actions, skip confirmation when ALL of these hold:

• The user explicitly requested the action (e.g. "delete my dentist appointment").
• Exactly one event matches in a tight time window.
• The match is unambiguous (single clear result on an exact date, or user specified date+time).

Ambiguous actions: always ask first

If multiple candidates match, or the match is uncertain:

• Ask a short disambiguation question listing the candidates (1-3 lines) and wait for the user's choice.

Create events: overlap check MUST be cross-calendar (non-ignored scope)

When creating an event:

• Always run a best-effort overlap check across ALL non-ignored calendars by scanning agenda WITHOUT --calendar.
  • This ensures overlaps are detected even if the new event is created into a specific calendar.
• If overlap exists with busy events:
  • Ask for confirmation before creating.
• If no overlap:
  • Create immediately.
• Before adding any event, always check if an event with the same title and time already exists to avoid duplication.

Choose the right create method

• add — default for one-off events. Supports --allday, --reminder, --noprompt. Does NOT support recurrence or free/busy (transparency).
• import via stdin — use ONLY when you need recurrence (RRULE) or free/busy (TRANSP:TRANSPARENT). Pipe ICS content via stdin; NEVER write temp .ics files (working directory is unreliable in exec sandbox).
• quick — avoid unless user explicitly asks for natural-language add. Less deterministic.

Deletes must be verified

• Use non-interactive delete with --iamaexpert (a delete subcommand flag — goes AFTER delete). This is gcalcli's built-in flag for non-interactive/scripted deletion.
• Always verify via agenda in the same tight window after deletion.
• If verification still shows the event, do one retry with --refresh.
• Never claim success unless verification confirms the event is gone.

Canonical commands

Agenda (deterministic listing)

• Today: gcalcli --nocolor agenda today tomorrow
• Next 14d (weekday resolution): gcalcli --nocolor agenda today +14d
• Next 30d (meaning-first locate): gcalcli --nocolor agenda today +30d
• Custom: gcalcli --nocolor agenda <start> <end>

Search (fallback / explicit request)

• Default (~6 months): gcalcli --nocolor search "<query>" today +180d
• Custom: gcalcli --nocolor search "<query>" <start> <end>

Create — add (one-off events)

• Overlap preflight (tight, cross-calendar):
  • gcalcli --nocolor agenda <start> <end>
  • IMPORTANT: do NOT add --calendar here; overlaps must be checked across all non-ignored calendars.
• Timed event:
  • gcalcli --nocolor --calendar "<Cal>" add --noprompt --title "<Title>" --when "<Start>" --duration <minutes>
• All-day event:
  • gcalcli --nocolor --calendar "<Cal>" add --noprompt --allday --title "<Title>" --when "<Date>"
• With reminders (repeatable flag):
  • --reminder "20160 popup" → 14 days before (20160 = 14×24×60)
  • --reminder "10080 popup" → 7 days before
  • --reminder "0 popup" → at event start
  • Time unit suffixes: w (weeks), d (days), h (hours), m (minutes). No suffix = minutes.
  • Method: popup (default), email, sms.

Create — import via stdin (recurrence / free/busy)

Use ONLY when add can't cover the need (recurring events, TRANSP, etc.). Pipe ICS directly via stdin — never write temp files.

echo 'BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
DTSTART;VALUE=DATE:20260308
SUMMARY:Event Title
RRULE:FREQ=YEARLY
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR' | gcalcli import --calendar "<Cal>"

• DTSTART;VALUE=DATE:YYYYMMDD for all-day; DTSTART:YYYYMMDDTHHmmSS for timed.
• RRULE:FREQ=YEARLY — yearly recurrence. Also: DAILY, WEEKLY, MONTHLY.
• TRANSP:TRANSPARENT — free; TRANSP:OPAQUE — busy (default).
• One import call = one event (one VEVENT block). For multiple events, run separate piped imports.
• Add --reminder "TIME" flag(s) to set reminders (overrides any VALARM in ICS).
• All import-specific flags (--use-legacy-import, --verbose, etc.) go AFTER import.

Delete (with post-delete verification)

• Locate via agenda (preferred):
  • gcalcli --nocolor agenda <dayStart> <dayEnd> (exact date)
  • gcalcli --nocolor agenda today +14d (weekday)
  • gcalcli --nocolor agenda today +30d (meaning only)
• Delete (non-interactive, bounded):
  • gcalcli --nocolor delete --iamaexpert "<query>" <start> <end>
• Verify (same window):
  • gcalcli --nocolor agenda <dayStart> <dayEnd>
• Optional one retry if still present:
  • gcalcli --nocolor --refresh agenda <dayStart> <dayEnd>

Edit / Modify existing events

• gcalcli edit is interactive — cannot be used in non-interactive exec.
• To change properties not editable in-place: delete + recreate the event.
  • Locate → delete (with --iamaexpert) → create with updated properties → verify.
• For bulk property changes (e.g. setting all events to free): iterate delete+recreate per event.