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.0
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.3
        bins:
          - things-cloud-cli
      - kind: go
        package: github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.3
        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.

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.3
go install github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.3
```

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`.