agentleFS
AxectAxect/skills/morgen/SKILL.md

morgen

Skill4 starsChanged 20 days agoMITView on GitHub

Manage calendars, events, tasks, and tags through the Morgen API (docs.morgen.so). Use when the user mentions Morgen, asks to list/create/update/delete calendar events or tasks across Google Calendar, Microsoft 365, iCloud, Fastmail, or CalDAV accounts connected through Morgen, or wants to query connected integrations and tags. Credentials live at `~/.config/morgen-skill/credentials.json`.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before any operation, check the credentials file exists:

    line 32
  2. Distinctive:

    If it does not exist, run the skill-orchestrated setup flow below.

    line 36
  3. Distinctive:

    Check if credentials already exist:

    line 50
  4. Distinctive:

    If they exist, ask whether to re-register (re-run only if the user confirms).

    line 54
  5. Distinctive:

    Ask the user to paste their Morgen API key, including this exact caveat:

    line 56
  6. Distinctive:

    Do not: run setup unprompted. The triggers are: explicit user request ("set up Morgen", "configure Morgen"), or a blocked operation that …

    line 68
  7. Very specific:

    All scripts live in this skill directory's scripts/ folder.

    line 93
  8. Very specific:

    All modes verify the key against /v3/calendars/list before writing ~/.config/morgen-skill/credentials.json (mode 600).

    line 101
  9. Very specific:

    No automatic sync, no conflict resolution — if you (or the mobile app) diverges, the next sync wins.

    line 168
  10. Very specific:

    When to prefer tasks.sh instead:

    line 175
  11. Very specific:

    Do not hardcode accountId or calendarId — resolve them fresh from calendars list or integrations accounts because IDs can change if a user …

    line 192
  12. Distinctive:

    If any script exits non-zero, show its stderr to the user verbatim.

    line 200

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Morgen

Unified calendar + task operations via the Morgen REST API v3. Morgen is a single surface over Google Calendar, Microsoft 365, iCloud, Fastmail, and CalDAV accounts, plus native Morgen tasks. This skill wraps the HTTP API with curl + jq helpers.

Trigger conditions

Invoke this skill when the user says any of:

  • "list my calendars" / "what calendars do I have in Morgen" → scripts/calendars.sh list
  • "show my events for <date range>" / "what's on my calendar" → scripts/events.sh list
  • "create an event" / "schedule a meeting" → scripts/events.sh create
  • "update event" / "delete event" / "move event" → scripts/events.sh update|delete
  • "what's on my TODO list" / "show my todos" / "today's tasks" / "overdue tasks" → scripts/todos.sh list|today|overdue
  • "add a todo" / "new task for ..." → scripts/todos.sh add
  • "mark X done" / "complete X" / "reopen X" → scripts/todos.sh done|reopen
  • "sync my tasks" / "refresh todos" → scripts/todos.sh sync
  • "list my tasks" / "raw tasks list" (API passthrough without cache) → scripts/tasks.sh list
  • "create a task" / "add a task" → scripts/tasks.sh create (or prefer todos.sh add which also updates the cache)
  • "complete task" / "close task" / "reopen task" → scripts/tasks.sh close|reopen
  • "list integrations" / "what accounts are connected" → scripts/integrations.sh accounts
  • "list tags" / "create a tag" → scripts/tags.sh list|create
  • "set up Morgen" / "configure Morgen" / credentials file missing → follow the Setup flow section below (Claude orchestrates via scripts/setup.sh --stdin)

For personal TODO workflows, prefer todos.sh over the raw tasks.sh: it caches the task list locally (~/.cache/morgen-skill/todos.json) so filtered reads cost 0 rate-limit points.

Prerequisites

Before any operation, check the credentials file exists:

test -f ~/.config/morgen-skill/credentials.json

If it does not exist, run the skill-orchestrated setup flow below.

Dependencies: curl, jq. If missing, the scripts exit 127 with a message.

Setup flow (skill-orchestrated)

setup.sh supports three modes:

  1. Interactive (TTY only) — bash scripts/setup.sh. User runs this themselves in a terminal when Claude can't.
  2. Non-interactive via stdin — bash scripts/setup.sh --stdin <<< "$KEY". Preferred for skill orchestration; the key never appears in this script's argv.
  3. Non-interactive via flag — bash scripts/setup.sh --key <KEY>. Convenient but the key is briefly visible in /proc/<pid>/cmdline. Acceptable on a personal single-user machine only.

When the user says "set up Morgen" (or any operation is blocked by missing credentials)

  1. Check if credentials already exist:
    test -f ~/.config/morgen-skill/credentials.json
    • If they exist, ask whether to re-register (re-run only if the user confirms).
    • If missing, proceed.
  2. Ask the user to paste their Morgen API key, including this exact caveat:

    Your key will be stored at ~/.config/morgen-skill/credentials.json (mode 600). Only paste it here if you trust this terminal and session transcript. Get the key at https://platform.morgen.so → Developers API.

  3. Once the user replies with the key, run the --stdin mode so the key stays out of argv. Quote the key literally inside the here-string:
    bash scripts/setup.sh --stdin <<< '<PASTED_KEY>'
    The script verifies the key against /v3/calendars/list (HTTP 200 = valid) and writes the credentials file with mode 600.
  4. On success, confirm to the user with the Setup complete. line the script emits, and suggest the natural next step (e.g. todos.sh sync or calendars.sh list).
  5. On failure (non-zero exit), show the stderr verbatim and ask whether to retry with a fresh key.

Do not echo the API key back in your own messages, and do not log it. If you must reference it, say "the key you provided".

Do not run setup unprompted. The triggers are: explicit user request ("set up Morgen", "configure Morgen"), or a blocked operation that encountered exit code 2 (missing credentials) / 3 (rejected key).

Authentication

Morgen uses a static API key sent as:

Authorization: ApiKey <KEY>

The key is stored at ~/.config/morgen-skill/credentials.json as:

{"api_key": "..."}

There is no OAuth refresh flow — if the key is revoked, re-run setup.sh.

Rate limits

  • 100 points per 15-minute window, per user.
  • /list endpoints cost 10 points each. All other endpoints cost 1 point.
  • Response headers to watch: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After.
  • On 429, respect Retry-After (seconds) before retrying. The helper surfaces the 429 response body so you can see the wait period.

Practical implication: avoid looping list calls. Cache accountId and calendarId values from one calendars list or integrations accounts call and reuse them for the whole session.

Script usage

All scripts live in this skill directory's scripts/ folder.

setup.sh — one-time API key registration

bash scripts/setup.sh                    # interactive (TTY required)
bash scripts/setup.sh --stdin <<< "$K"   # non-interactive, key via stdin
bash scripts/setup.sh --key "$K"         # non-interactive, key via argv (argv visible in /proc briefly)

All modes verify the key against /v3/calendars/list before writing ~/.config/morgen-skill/credentials.json (mode 600). See the Setup flow section above for the end-to-end skill-orchestrated flow.

calendars.sh — calendars

bash scripts/calendars.sh list
bash scripts/calendars.sh update <accountId> <calendarId> <metadata_json>

list returns the calendars[] array. Each calendar has id, accountId, integrationId, name, color, myRights, and morgen.so:metadata. Always call this once per session to resolve (accountId, calendarId) pairs — events endpoints require both.

events.sh — calendar events

bash scripts/events.sh list <accountId> <calendarIds> <startISO> <endISO>
bash scripts/events.sh create <json_body>
bash scripts/events.sh update <json_body> [seriesUpdateMode]
bash scripts/events.sh delete <accountId> <calendarId> <eventId> [seriesUpdateMode]
  • calendarIds is a comma-separated list.
  • start / end are ISO 8601; max window is 6 months.
  • seriesUpdateMode ∈ {single (default), all, future} for recurring events.
  • create body requires accountId, calendarId, title, start, duration (ISO 8601 duration like PT1H), timeZone, showWithoutTime.
  • update body requires accountId, calendarId, and either id or (masterEventId + recurrenceId).
  • Update gotcha: start, duration, timeZone, and showWithoutTime form an atomic group — if you send any one of them, you must send all four, or the API returns HTTP 400 (MRG_ERR_VALIDATION_FAILED: Properties start, duration, timeZone and showWithoutTime must be provided together). To patch just one time field (e.g. change duration), include the existing values for the other three. timeZone may be null for floating events. Other fields (title, description, location, etc.) can be patched individually without this constraint.

tasks.sh — Morgen tasks

bash scripts/tasks.sh list [limit] [updatedAfterISO]
bash scripts/tasks.sh get <taskId>
bash scripts/tasks.sh create <json_body>
bash scripts/tasks.sh update <json_body>
bash scripts/tasks.sh move <taskId> [previousId] [parentId]
bash scripts/tasks.sh close <taskId> [occurrenceStart]
bash scripts/tasks.sh reopen <taskId> [occurrenceStart]
bash scripts/tasks.sh delete <taskId>
  • create requires title; optional: description, due, timeZone, priority, progress, tags, relatedTo.
  • update requires id; other fields are patch-style.
  • close/reopen take an optional occurrenceStart for recurring task instances.
  • Mutation endpoints return HTTP 204 (no body) on success — the helper prints {"ok":true}.

integrations.sh — connected accounts and providers

bash scripts/integrations.sh accounts
bash scripts/integrations.sh providers
  • accounts: lists the user's connected accounts with accountId, provider, auth status.
  • providers: lists available integration providers (no auth required).
  • Connecting or disconnecting accounts must be done in the Morgen app, not via API.

todos.sh — cached TODO workflow (recommended for personal task management)

bash scripts/todos.sh sync                 # refresh local cache (1 list call, 10 pts)
bash scripts/todos.sh list [--all] [--tag <id>] [--priority <n>]
bash scripts/todos.sh today                # tasks due today
bash scripts/todos.sh overdue              # not completed, due before now
bash scripts/todos.sh show <idOrPrefix>
bash scripts/todos.sh add <title> [--due <ISO>] [--priority <n>] [--tz <IANA>] [--description <text>]
bash scripts/todos.sh done <idOrPrefix>
bash scripts/todos.sh reopen <idOrPrefix>
bash scripts/todos.sh delete <idOrPrefix>

Design: manual sync, cache-first reads, API-first writes.

  • sync is the only command that calls /tasks/list (10 pts). Do it once per session.
  • list, today, overdue, show read from the local cache → 0 rate-limit points, instant.
  • add, done, reopen, delete hit the API (1 pt each) and then patch the local cache in place. If the API call fails, the cache is untouched.
  • Short-ID prefixes (e.g. aaaa1111) resolve against the cache. Ambiguous prefixes error out with the list of matches.
  • Stale-cache warning fires automatically when the cache is older than MORGEN_STALE_SECONDS (default 3600 = 1 hour). Output still works; only a stderr notice appears.
  • No automatic sync, no conflict resolution — if you (or the mobile app) diverges, the next sync wins. For personal use this is almost always what you want.

Environment overrides:

  • MORGEN_CACHE_DIR — cache directory (default ~/.cache/morgen-skill)
  • MORGEN_STALE_SECONDS — stale-warning threshold in seconds (default 3600)

When to prefer tasks.sh instead:

  • you explicitly want a fresh read-through to the API
  • you're scripting something that doesn't need the local cache
  • you need non-TODO task features (move, recurring occurrence closes, etc.)

tags.sh — tags

bash scripts/tags.sh list [limit] [updatedAfterISO]
bash scripts/tags.sh get <tagId>
bash scripts/tags.sh create <name> [hexColor]
bash scripts/tags.sh update <tagId> [name] [hexColor]
bash scripts/tags.sh delete <tagId>

delete is a soft-delete — the tag reappears in sync payloads with deleted: true.

Path rules & invariants

  • Do not hardcode accountId or calendarId — resolve them fresh from calendars list or integrations accounts because IDs can change if a user reconnects an account.
  • Event start is an ISO 8601 local datetime without offset (e.g. 2026-04-21T14:00:00). The separate timeZone field carries the offset. Do not pass a Z-suffixed UTC string in start.
  • duration is ISO 8601 duration, not seconds. PT25M, PT1H, PT1H30M.
  • Event list start/end are ISO 8601 UTC (with Z), unlike event-body start.
  • Task due follows the same local-datetime + timeZone convention.

Error handling

If any script exits non-zero, show its stderr to the user verbatim. Do not retry auth errors automatically (exit code 3) — surface them so the user can re-run setup.

Exit code reference:

  • 0 — success
  • 1 — bad argument, missing positional, or malformed JSON
  • 2 — credentials.json missing (→ user should run setup.sh)
  • 3 — API key rejected, HTTP 401/403 (→ user should re-run setup.sh)
  • 4 — Morgen returned 404 (resource not found)
  • 5 — Other API error (timeout, 5xx, unexpected body)
  • 6 — Rate-limited, HTTP 429 (respect Retry-After before retrying)
  • 64 — usage error
  • 127 — missing dependency (curl or jq)

Resources

  • references/api-reference.md: endpoint table with fields, methods, and notes.
  • references/examples.md: common workflows (scheduling a meeting, triaging tasks, bulk tag cleanup).
  • Upstream docs: https://docs.morgen.so/

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.