Add Things Cloud agent skill wrapper

AGENTS.md

@@ -9,6 +9,8 @@ writes and local read-only inspection.
 - Use `things-cloud-cli` in new docs, examples, and agent integrations.
 - Keep `things-cli` only as a backward-compatible alias.
 - Prefer `things-mcp` for MCP-based agents.
+- Use `skills/things-cloud/SKILL.md` as the public OpenClaw/ClawHub/Codex/
+  Claude Code wrapper for agent-facing Things Cloud workflows.
 - Prefer `sync.Open(...).Sync()` or `QuickSync()` for long-running services that
   need persisted state and semantic change events.
 - Use `local.OpenDefault()` only for read-only macOS SQLite inspection.
@@ -63,6 +65,10 @@ If the non-ASCII scan prints intentional content, document why in the PR.
 - `llms.txt` - short LLM crawler/agent index.
 - `docs/agent-cookbook.md` - task-oriented agent recipes.
 - `docs/contracts.md` - JSON contracts for CLI and MCP outputs.
+- `skills/things-cloud/SKILL.md` - publishable agent skill wrapper for
+  OpenClaw, ClawHub, Codex, and Claude Code.
+- `docs/integrations/openclaw-publishing.md` - ClawHub listing and OpenClaw
+  integration/showcase submission material.
 - `cmd/things-cloud-cli/` - preferred CLI entrypoint.
 - `cmd/things-mcp/` - MCP stdio server.
 - `internal/thingscli/` - shared CLI implementation and tests.

CLAUDE.md

@@ -6,6 +6,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Go SDK for the Things 3 cloud API (Cultured Code). This is a reverse-engineered, unofficial SDK — there is no official API documentation. The client mimics `ThingsMac/32209501` and sends a base64-encoded `things-client-info` device metadata header.
 
+## Agent Integration Surface
+
+Use `skills/things-cloud/SKILL.md` as the canonical Things Cloud agent skill
+wrapper for Claude Code, Codex, OpenClaw, and ClawHub. It describes safe task
+reads/writes through `things-cloud-cli` and `things-mcp`.
+
+Default agent behavior:
+
+- Prefer `things-mcp` when MCP is available.
+- Use `things-cloud-cli --simple` for compact task-list JSON.
+- Use `--dry-run` before generated writes, then ask for confirmation.
+- Use `completed`/`logbook` for completion evidence.
+- Never write to the local Things SQLite database.
+
+ClawHub/OpenClaw publishing material lives in
+`docs/integrations/openclaw-publishing.md`.
+
 ## Build & Test Commands
 
 ```bash
@@ -66,8 +83,10 @@ The `syncutil` package provides shared utilities for sync-based CLI tools:
 ### CLI Tools (`cmd/`)
 
 See `cmd/README.md` for detailed documentation. Key tools:
-- **`things-cli`** — Full CRUD operations (create, edit, complete, trash tasks)
-  - Supports `batch` command for multiple operations in one HTTP request
+- **`things-cloud-cli`** — Preferred CLI for reads, safe dry-run writes, CRUD,
+  recurring tasks, completed/logbook evidence, and batch operations
+- **`things-cli`** — Backward-compatible alias for older integrations
+- **`things-mcp`** — Stdio MCP server for agent hosts
 - **`thingsync`** — JSON-based sync with workflow views (today, inbox, review, patterns)
 - **`synctest`** — Human-readable sync output for testing
 
@@ -97,4 +116,5 @@ See `docs/client-side-bugs.md` for the full investigation.
 
 The example app and real usage require:
 - `THINGS_USERNAME` — Things account email
-- `THINGS_PASSWORD` — Things account password
+- `THINGS_TOKEN` — Preferred automation password/token alias
+- `THINGS_PASSWORD` — Things account password, used when `THINGS_TOKEN` is not set

README.md

@@ -75,6 +75,10 @@ LLM-assisted automation:
 - `docs/agent-cookbook.md` - copy-paste recipes for common agent workflows.
 - `docs/contracts.md` - stable JSON contracts for CLI and MCP integrations.
 - `examples/agent/` - MCP config, OpenClaw notes, smoke test, and sample JSON.
+- `skills/things-cloud/SKILL.md` - publishable OpenClaw/ClawHub skill wrapper,
+  also useful for Codex and Claude Code operating instructions.
+- `docs/integrations/openclaw-publishing.md` - ClawHub listing and OpenClaw
+  integration/showcase submission material.
 
 ## Install
 
@@ -334,6 +338,27 @@ Tools exposed by `things-mcp`:
 For destructive or user-visible changes, hosts should confirm the action before
 calling a non-dry-run write tool.
 
+## OpenClaw, Codex, and Claude Code
+
+This repo includes a publishable agent skill wrapper:
+
+```text
+skills/things-cloud/SKILL.md
+```
+
+Use it when wiring Things Cloud into OpenClaw, ClawHub, Codex, Claude Code, or
+another agent runtime that understands `SKILL.md` style instructions. The skill
+wraps `things-cloud-cli` and `things-mcp`; it does not duplicate runtime code.
+
+Local OpenClaw test install from this checkout:
+
+```bash
+openclaw skills install ./skills/things-cloud --as things-cloud
+```
+
+See `docs/integrations/openclaw-publishing.md` for ClawHub publishing commands
+and OpenClaw integration request copy.
+
 ## Go SDK Quick Start
 
 Use the SDK directly when you need Cloud API access from a Go service.
@@ -581,8 +606,10 @@ state/memory/           In-memory state aggregation
 local/                  Read-only local Things SQLite reader
 example/                Lower-level SDK examples
 examples/agent/         Agent configs, smoke tests, and sample JSON
+skills/things-cloud/    Publishable OpenClaw/ClawHub/Codex/Claude Code skill
 docs/agent-cookbook.md  Agent workflow recipes
 docs/contracts.md       CLI and MCP JSON contracts
+docs/integrations/      ClawHub and OpenClaw publishing material
 docs/client-side-bugs.md Wire-format and crash analysis
 docs/                   Investigation notes and protocol details
 ```

docs/integrations/openclaw-publishing.md

@@ -0,0 +1,126 @@
+# OpenClaw and ClawHub Publishing
+
+This repository includes a publishable Things Cloud agent skill at:
+
+```text
+skills/things-cloud/SKILL.md
+```
+
+The skill is designed for OpenClaw, ClawHub, Codex, Claude Code, and other
+agent runtimes that can consume `SKILL.md` style instructions. It wraps the
+maintained `things-cloud-cli` and `things-mcp` tools instead of duplicating
+runtime code.
+
+## Install from This Repository
+
+After the skill is merged to `main`, OpenClaw users can install from the raw
+skill URL if their OpenClaw version supports URL installs:
+
+```bash
+openclaw skills install https://raw.githubusercontent.com/pdurlej/things-cloud-sdk/main/skills/things-cloud/SKILL.md --as things-cloud
+```
+
+For local testing from a checkout:
+
+```bash
+openclaw skills install ./skills/things-cloud --as things-cloud
+```
+
+## Publish to ClawHub
+
+Prerequisites:
+
+```bash
+npm i -g clawhub
+clawhub login
+```
+
+Recommended dry-run/sync check:
+
+```bash
+clawhub sync --all --dry-run
+```
+
+Publish the skill:
+
+```bash
+clawhub skill publish ./skills/things-cloud \
+  --slug things-cloud \
+  --name "Things Cloud" \
+  --version 0.1.0 \
+  --tags latest \
+  --changelog "Initial Things Cloud skill for safe OpenClaw, Codex, and Claude Code task automation." \
+  --clawscan-note "This skill installs and calls the maintained things-cloud-cli and things-mcp Go binaries. It requires Things Cloud credentials through THINGS_USERNAME plus THINGS_TOKEN or THINGS_PASSWORD. Agent writes should use dry-run before execution."
+```
+
+Expected listing copy:
+
+```text
+Things Cloud
+
+Manage Things 3 tasks through Things Cloud with a maintained Go CLI and MCP
+server. Supports safe dry-run writes, compact JSON task reads, completed/logbook
+evidence, recurring tasks, and agent-friendly credentials.
+```
+
+Suggested search terms:
+
+```text
+things, things3, things-cloud, task-management, productivity, mcp, cli, agents, openclaw
+```
+
+## OpenClaw Integration Request
+
+The OpenClaw integrations page links "Request Integration" to the
+`openclaw/openclaw` issue tracker. Submit an issue after the skill is merged and
+published or at least installable from `main`.
+
+Suggested title:
+
+```text
+Add Things Cloud / Things 3 as a Productivity integration
+```
+
+Suggested body:
+
+~~~markdown
+## Integration
+
+Things Cloud / Things 3 task management
+
+## What it does
+
+Adds an agent-friendly way to read and safely update Things 3 tasks through
+Things Cloud.
+
+## Links
+
+- SDK/CLI/MCP: https://github.com/pdurlej/things-cloud-sdk
+- Release: https://github.com/pdurlej/things-cloud-sdk/releases/tag/v0.2.3
+- Skill: https://github.com/pdurlej/things-cloud-sdk/tree/main/skills/things-cloud
+
+## Capabilities
+
+- list Today, Inbox, Anytime, Someday, Upcoming
+- search tasks
+- create/edit/complete/trash/move tasks
+- dry-run writes before user confirmation
+- completed/logbook evidence for feedback loops
+- recurring task creation via CLI
+- stdio MCP server for agent hosts
+
+## Setup
+
+```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
+export THINGS_USERNAME="you@example.com"
+export THINGS_TOKEN="your-things-cloud-password-or-token-alias"
+```
+
+## Safety
+
+The local Things SQLite adapter is read-only. Agent writes go through Things
+Cloud and should use dry-run before executing user-visible changes.
+```
+~~~

llms.txt

@@ -27,6 +27,10 @@ Best entry points for LLMs:
 - `docs/agent-cookbook.md` - copy-paste recipes for common agent workflows.
 - `docs/contracts.md` - JSON output contracts for CLI and MCP integrations.
 - `examples/agent/` - MCP config, OpenClaw notes, smoke test, sample outputs.
+- `skills/things-cloud/SKILL.md` - publishable OpenClaw/ClawHub skill wrapper
+  and reusable Codex/Claude Code operating policy.
+- `docs/integrations/openclaw-publishing.md` - ClawHub listing and OpenClaw
+  integration/showcase submission copy.
 - `docs/client-side-bugs.md` - Things wire-format and crash-safety notes.
 
 Recommended interface by task: