skills/lstpsche_gcalcli-calendar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit with translated description

Browse Source
This commit is contained in:
zlei9
2026-03-29 10:22:58 +08:00
commit e739a7d779
3 changed files with 234 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
README.md Normal file
View File

@@ -0,0 +1,65 @@
# gcalcli-calendar
An OpenClaw skill for managing Google Calendar via [gcalcli](https://github.com/insanum/gcalcli).
## What this skill does
Teaches the agent to read, search, create, and delete Google Calendar events using the `gcalcli` CLI. Optimized for low tool calls, minimal token usage, and fast conversational calendar management.
## About gcalcli
[gcalcli](https://github.com/insanum/gcalcli) is a well-established open-source CLI for Google Calendar (5k+ GitHub stars, actively maintained). It authenticates via OAuth2 and stores credentials locally. This skill does not handle authentication — gcalcli must be set up and authenticated before use.
## Prerequisites
- Python 3.6+
- `gcalcli` — install via `pip install gcalcli` or `brew install gcalcli`
- Google Calendar OAuth2 credentials (set up via `gcalcli init` or `gcalcli list` on first run)
## Actions policy — design rationale
**This skill intentionally skips user confirmation for unambiguous destructive actions (delete/edit).** This is a deliberate UX decision, not an oversight. Here's why and how it's kept safe:
### Why skip confirmation?
This skill is designed for personal assistant use via messaging apps (Telegram, WhatsApp, etc.), where:
- The user has already stated their intent explicitly (e.g. "delete my dentist appointment on Thursday").
- An extra "Are you sure?" round-trip adds latency and friction with no real safety benefit when the target is unambiguous.
- The interaction model is conversational — the user's message *is* the confirmation.
### Safety guards in place
The skill does NOT blindly delete. All of these must hold before executing without confirmation:
1. **Explicit user request** — the user must have asked for the action in their message.
2. **Single unambiguous match** — exactly one event matches in a tight, bounded time window.
3. **Post-action verification** — after every delete, the agent verifies via agenda that the event is actually gone. It never claims success without verification.
4. **Disambiguation for ambiguous cases** — if multiple events match, the agent always stops and asks the user to choose before proceeding.
5. **Overlap checks for creates** — before creating events, the agent checks for scheduling conflicts across all calendars and asks for confirmation if an overlap exists.
### If you prefer confirmation for all actions
You can modify the "Actions policy" section in SKILL.md to require confirmation for all destructive actions. Change the "Unambiguous actions" rule to always ask before executing.
## Network access
This skill invokes `gcalcli`, which communicates with:
- `https://www.googleapis.com/calendar/` — Google Calendar API (authenticated via local OAuth2 tokens)
- `https://oauth2.googleapis.com/` — OAuth2 token refresh
No other network access is made. The skill itself makes no HTTP requests — all API communication is handled by gcalcli. OAuth2 credentials are stored locally by gcalcli (typically in `~/.gcalcli_oauth`).
## Commands used
All `gcalcli` commands used by this skill:
- `gcalcli agenda` — list events in a time window (read-only)
- `gcalcli search` — search events by text query (read-only)
- `gcalcli add` — create a one-off event
- `gcalcli import` — create events via ICS (for recurrence/free-busy)
- `gcalcli delete` — delete events (uses `--iamaexpert` flag for non-interactive mode, which is gcalcli's built-in flag for scripted/automated use)
No other commands or subcommands are used. No file system writes are performed (ICS content is piped via stdin, never written to disk).
## License
This skill is MIT licensed. [gcalcli](https://github.com/insanum/gcalcli) is MIT licensed.

163
SKILL.md Normal file
View File

@@ -0,0 +1,163 @@
---
name: gcalcli-calendar
description: "通过gcalcli使用Google日历。"
metadata: {"openclaw":{"emoji":"📅","requires":{"bins":["gcalcli"]}}}
---
# gcalcli-calendar
Use `gcalcli` to read/search/manage Google Calendar with minimal tool calls and minimal output.
## 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.
### 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.

6
_meta.json Normal file
View File

@@ -0,0 +1,6 @@
{
"ownerId": "kn757ghzsay7zhsft6rb14jhwn80d28q",
"slug": "gcalcli-calendar",
"version": "3.0.0",
"publishedAt": 1770939510320
}