From eda9fb5522a02d9c4108d1ad0c5071b7f918c5b6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 1 Jan 2026 21:12:37 +0100
Subject: [PATCH] feat(skills): add things-mac

---
 CHANGELOG.md               |  1 +
 skills/things-mac/SKILL.md | 61 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 skills/things-mac/SKILL.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0789376c5..6dc2b32f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@
 - CLI: add Signal CLI auto-install from GitHub releases in the wizard and persist wizard run metadata in config.
 - CLI: add remote gateway client config (gateway.remote.*) with Bonjour-assisted discovery.
 - Skills: allow `bun` as a node manager for skill installs.
+- Skills: add `things-mac` (Things 3 CLI) for read/search plus add/update via URL scheme.
 - Tests: add a Docker-based onboarding E2E harness.
 - Tests: harden wizard E2E flows for reset, providers, skills, and remote non-interactive runs.
 
diff --git a/skills/things-mac/SKILL.md b/skills/things-mac/SKILL.md
new file mode 100644
index 000000000..3b956688e
--- /dev/null
+++ b/skills/things-mac/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: things-mac
+description: Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database). Use when a user asks Clawdis to add a task to Things, list inbox/today/upcoming, search tasks, or inspect projects/areas/tags.
+homepage: https://github.com/ossianhempel/things3-cli
+metadata: {"clawdis":{"emoji":"✅","requires":{"bins":["things"]},"install":[{"id":"go","kind":"go","module":"github.com/ossianhempel/things3-cli/cmd/things@latest","bins":["things"],"label":"Install things3-cli (go)"}]}}
+---
+
+# Things 3 CLI
+
+Use `things` to read your local Things database (inbox/today/search/projects/areas/tags) and to add/update todos via the Things URL scheme.
+
+Setup
+- Install (recommended, Apple Silicon): `GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`
+- If DB reads fail: grant **Full Disk Access** to the calling app (Terminal for manual runs; `Clawdis.app` for gateway runs).
+- Optional: set `THINGSDB` (or pass `--db`) to point at your `ThingsData-*` folder.
+- Optional: set `THINGS_AUTH_TOKEN` to avoid passing `--auth-token` for update ops.
+
+Read-only (DB)
+- `things inbox --limit 50`
+- `things today`
+- `things upcoming`
+- `things search "query"`
+- `things projects` / `things areas` / `things tags`
+
+Write (URL scheme)
+- Prefer safe preview: `things --dry-run add "Title"`
+- Add: `things add "Title" --notes "..." --when today --deadline 2026-01-02`
+- Bring Things to front: `things --foreground add "Title"`
+
+Examples: add a todo
+- Basic: `things add "Buy milk"`
+- With notes: `things add "Buy milk" --notes "2% + bananas"`
+- Into a project/area: `things add "Book flights" --list "Travel"`
+- Into a project heading: `things add "Pack charger" --list "Travel" --heading "Before"`
+- With tags: `things add "Call dentist" --tags "health,phone"`
+- Checklist: `things add "Trip prep" --checklist-item "Passport" --checklist-item "Tickets"`
+- From STDIN (multi-line => title + notes):
+  - `cat <<'EOF' | things add -`
+  - `Title line`
+  - `Notes line 1`
+  - `Notes line 2`
+  - `EOF`
+
+Examples: modify a todo (needs auth token)
+- First: get the ID (UUID column): `things search "milk" --limit 5`
+- Auth: set `THINGS_AUTH_TOKEN` or pass `--auth-token <TOKEN>`
+- Title: `things update --id <UUID> --auth-token <TOKEN> "New title"`
+- Notes replace: `things update --id <UUID> --auth-token <TOKEN> --notes "New notes"`
+- Notes append/prepend: `things update --id <UUID> --auth-token <TOKEN> --append-notes "..."` / `--prepend-notes "..."`
+- Move lists: `things update --id <UUID> --auth-token <TOKEN> --list "Travel" --heading "Before"`
+- Tags replace/add: `things update --id <UUID> --auth-token <TOKEN> --tags "a,b"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags "a,b"`
+- Complete/cancel (soft-delete-ish): `things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`
+- Safe preview: `things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`
+
+Delete a todo?
+- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).
+- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.
+
+Notes
+- macOS-only.
+- `--dry-run` prints the URL and does not open Things.