eugenepyvovarov/things3-agent-skill

Overview

This skill connects to the Things 3 macOS app through a local CLI to list, search, open, and modify tasks, projects, areas, headings, and tags. It uses the Things URL scheme and a local virtual environment to run commands securely under the project data directory. Use it to inspect Things state, create or update items, and open items inside the Things app from automation or conversational flows.

How this skill works

The skill runs a bundled CLI that bootstraps a local virtual environment and uses Things URLs to perform write operations. Read-only commands query Things and format results for discovery (Inbox, Today, Upcoming, etc.). For writes, the skill resolves names to UUIDs, summarizes proposed changes, and requires user confirmation before invoking the Things URL scheme to add or update items. All runtime state, configs, and logs are kept under .skills-data/things3-manager/ to avoid touching other parts of the filesystem.

When to use it

• Browse current tasks, projects, areas, tags, headings, or logbook entries.
• Search for specific todos or projects by keyword or advanced filters.
• Add new todos, projects, or checklists in Things via automation.
• Update an existing todo or project after confirming exact changes with the user.
• Open a specific item or search result directly in the Things app for manual inspection.

Best practices

• Prefer read-only listing/search commands first to discover UUIDs and current state before any write.
• When the user refers to projects/areas/headings by name, list and resolve them to UUIDs prior to making changes.
• Always summarize intended changes and ask for explicit confirmation before running add/update commands.
• Keep all skill files and virtualenv under .skills-data/things3-manager/ to respect local project boundaries.
• Ensure Things → Settings → General → Enable Things URLs is turned on before using write/open features.

Example use cases

• Perform a weekly review: run today, upcoming, and projects to inspect outstanding work.
• Create a new todo with checklist items and a tag: add-todo --title "Book flights" --when today --tag travel --checklist ...
• Search for all items tagged "weekly" and open chosen results in Things for editing.
• Update a project deadline or move a todo into a project after confirming the exact change with the user.
• List areas and projects to resolve a project name to its UUID before creating a new heading under it.