Things Cloud

SKILL.md

---
name: things-cloud
description: Manage Things 3 tasks through Things Cloud using the maintained things-cloud-sdk CLI and MCP server, with dry-run safety for agent writes.
version: 0.1.2
metadata:
  openclaw:
    requires:
      bins:
        - things-cloud-cli
        - things-mcp
    primaryEnv: THINGS_TOKEN
    envVars:
      - name: THINGS_USERNAME
        required: true
        description: Things Cloud account email.
      - name: THINGS_TOKEN
        required: false
        description: Things Cloud password or automation token alias. Use this instead of THINGS_PASSWORD when possible.
      - name: THINGS_PASSWORD
        required: false
        description: Things Cloud password. Required only when THINGS_TOKEN is not set.
      - name: THINGS_CONFIG
        required: false
        description: Optional path to a JSON config file with credentials and cache settings.
      - name: THINGS_CLI_CACHE
        required: false
        description: Optional path to the CLI read-state cache.
    install:
      - kind: go
        package: github.com/pdurlej/things-cloud-sdk/cmd/things-cloud-cli@v0.2.4
        bins:
          - things-cloud-cli
      - kind: go
        package: github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.4
        bins:
          - things-mcp
    homepage: https://github.com/pdurlej/things-cloud-sdk
---

# Things Cloud

Use this skill when the user wants an agent to inspect or safely update Things 3
tasks through Things Cloud.

Works with OpenClaw, Codex, and Claude Code through MCP when available, with a
CLI fallback for hosts that prefer shell commands.

Prefer the MCP server when the host supports MCP. Use the CLI as the fallback or
when the user asks for explicit shell commands.

## Setup

Install the maintained CLI and MCP server:

```bash
go install github.com/pdurlej/things-cloud-sdk/cmd/things-cloud-cli@v0.2.4
go install github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.4
```

Set credentials:

```bash
export THINGS_USERNAME="you@example.com"
export THINGS_TOKEN="your-things-cloud-password-or-token-alias"
```

`THINGS_PASSWORD` also works when `THINGS_TOKEN` is not set. Do not store
credentials in the repository or in skill files.

## MCP Configuration

Use this stdio MCP server config for OpenClaw, Claude Code, Codex hosts, or any
MCP-compatible agent runtime:

```json
{
  "mcpServers": {
    "things": {
      "command": "things-mcp",
      "env": {
        "THINGS_USERNAME": "you@example.com",
        "THINGS_TOKEN": "your-things-cloud-password-or-token-alias"
      }
    }
  }
}
```

## Agent Policy

- Read before writing.
- Prefer MCP tools for task operations.
- Use CLI `--simple` output for compact task lists.
- Use `--dry-run` before any user-visible write generated by an agent.
- Summarize the planned change and get confirmation before non-dry-run writes.
- Never write to the local Things SQLite database.
- Do not infer completion from absence in active views; use
  `completed`/`logbook`.
- Use task UUIDs returned by Things Cloud output. Do not invent UUIDs.

## Common Reads

With MCP:

- `list_tasks` with `view` set to `today`, `inbox`, `anytime`, `someday`, or
  `upcoming`
- `search_tasks` for title/note search
- `list_projects`, `list_areas`, and `list_tags` for metadata

With CLI:

```bash
things-cloud-cli today --simple
things-cloud-cli inbox --simple
things-cloud-cli anytime --simple
things-cloud-cli someday --simple
things-cloud-cli upcoming --simple
things-cloud-cli search "invoice" --simple
```

## Completion Evidence

Use completed/logbook commands when the user asks whether something was done:

```bash
things-cloud-cli completed --since 2026-05-20T00:00:00Z --format full
things-cloud-cli logbook --since 2026-05-20 --limit 50 --format full
```

## Safe Writes

Preview first:

```bash
things-cloud-cli create "Follow up with Marta" --when today --dry-run
things-cloud-cli edit <task-uuid> --title "New title" --dry-run
things-cloud-cli complete <task-uuid> --dry-run
```

After user confirmation, run the same command without `--dry-run`.

Recurring tasks:

```bash
things-cloud-cli create "Check car listings" --repeat every-day --dry-run
things-cloud-cli create "Weekly review" --repeat weekly:mon --dry-run
things-cloud-cli create "Follow up after reply" --repeat after-completion:every-day --dry-run
```

Clear recurrence:

```bash
things-cloud-cli edit <task-uuid> --repeat none --dry-run
```

## Output Rules

- Keep raw command output as JSON.
- Summaries should mention the task title, UUID, view/status, and whether the
  write was dry-run or executed.
- If a task reference is ambiguous, search first and ask the user to choose.
- If credentials are missing, ask the user to set `THINGS_USERNAME` and either
  `THINGS_TOKEN` or `THINGS_PASSWORD`.