How to use the Things 3 To-Do Manager agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This skill is named things-todo and is described as Things 3 via things CLI: add, list, search, update, delete, verify.

Once installed, the agent can add new to-dos with notes, dates, tags and checklists, look up existing ones, update them, and delete them to the Things Trash. The skill tells the agent to read items back after each change to confirm the result, and to preview bulk changes with --dry-run first. It is written for Peter's Macs, and it says to prefer Things for to-dos and to use Apple Reminders only when a user explicitly asks for it.

Install the things CLI

The skill depends on the things command-line tool from github.com/ossianhempel/things3-cli. The skill's install line uses the Go toolchain, so Go must be installed first. The skill's install command is shown below. Set GOBIN to the directory where you want the binary placed; the skill uses /opt/homebrew/bin.

• Requirements: macOS, the Things 3 app installed on the Mac, and the Go toolchain.
• Grant Full Disk Access to the app that calls the tool, because reading the Things database needs it.

Install the skill (ZIP or Claude apps)

Download the ZIP for things-todo from this page and unzip it. For a personal setup, place the things-todo folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The skill package contains one file, SKILL.md.

• Personal install: ~/.claude/skills/things-todo/
• Project install: .claude/skills/things-todo/ inside your project

Set up the auth token for updates

Adding and searching do not need a token, but updating does. The skill expects THINGS_AUTH_TOKEN to be stored in ~/.profile or in 1Password. The skill sources ~/.profile and runs things auth to check access. The agent is instructed never to print the token. Running things update --dry-run shows the token redacted as auth-token=***.

• add does not need THINGS_AUTH_TOKEN; update does.
• Keep the token in ~/.profile or 1Password, not in a chat or a shared file.

Ask for to-dos in plain language

You do not need to type commands yourself. Describe what you want, and the agent chooses the right things operation. The skill's conventions shape how it handles your wording: vague requests become concrete next-action titles, wording stays as you gave it when you clearly want capture, and unrelated actions become separate to-dos.

The agent uses Today only when you imply it; otherwise it uses the Inbox or Anytime defaults. If you need the agent to know today's date for a relative request, the skill says it runs date rather than guessing.

• "Add a to-do to book a nonstop LHR to SFO flight for tomorrow, tagged travel."
• "Search my Things tasks for flight and show me what you find."
• "Change the flight to-do's notes to say I want business class."
• "Delete the old LHR-SFO to-do, and check that it is in the Trash."

Check what the agent did

The skill asks the agent to read items back after every write. For a new to-do, the agent searches for it again. For a delete, it confirms the item is gone from normal search and, when cleanup matters, that it appears in the trash. Ask the agent to show you these results so you can see the check happened.

For bulk changes, ask the agent to run a dry run first. The --dry-run flag shows the things:/// URL without changing anything.

• Read-back after add: search for the title with --format json.
• Delete check: normal search empty, trash search contains the item.
• Dry run: --dry-run on add, update or delete previews the change.

Safety notes: scripts and network

This skill runs scripts and uses the network. The things CLI is installed with go install from GitHub, and the update operations use the Things URL Scheme or AppleScript through things. The skill tells the agent not to write to the Things SQLite database directly.

Updates and deletes change real data. Delete moves items to the Things Trash rather than erasing them, but an agent with this skill can still change tasks you did not mean to touch, so review what it reports and use dry runs for bulk work.

• The skill runs scripts and makes network calls to install and operate the CLI.
• The agent is told never to print THINGS_AUTH_TOKEN.
• Deletes go to Things Trash; check the trash search if you need to be sure.