TickTick Skill

intent

manage ticktick tasks and projects directly from your cli or chat interface. use this skill to list, create, edit, complete, and organize tasks across projects. handles filtering by status, priority, due date, and project. best for daily task triage, batch operations, and keeping your task list in sync without leaving your workspace.

inputs

External connection: TickTick API

• OAuth2 credentials required. run setup once: bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
• Credentials stored securely in ~/.clawdbot/credentials/ticktick-cli/
• Check status anytime: bun run scripts/ticktick.ts auth --status
• API rate limit: ~100 requests/minute. the cli respects backoff; hitting limits requires ~60 second wait before retry.

Configuration file

• Location: ~/.config/ticktick-skill/config.json
• Optional keys: default.project, default.due, display.colors, display.timezone
• Not required to run; all defaults provided.

Task identifiers

• Task IDs: 24-character hex strings (e.g., 65a54fce2026ccc8b729349b). required for edit, complete, abandon, details, batch-abandon commands. obtain from /tasks --json or /tasks --format json output.
• Project names: case-insensitive, partial match works. "Hill" matches "Hillcrest".

Due date formats

• Natural language: "today", "tomorrow", "in 3 days", "next monday"
• ISO format: YYYY-MM-DD (e.g., 2026-03-25)

procedure

1. list projects

Command: /tasks projects or /ticktick projects

Input: None (uses OAuth credentials from setup).

Output: table or json listing all projects with their IDs and names.

Edge case: if no projects exist, returns empty list.

---

2. list tasks with filters

Command: /tasks [options] or /ticktick tasks [options]

Input options:

• --project <name> , filter by project name or ID (case-insensitive partial match)
• --status <pending|completed> , filter by completion state
• --due <today|overdue|none|unspecified> , filter by due date category
• --priority <high|medium|low|none> , filter by priority level
• --sort <due|priority|title|created> , sort results
• --limit <N> , cap results to N tasks (default: all)
• --offset <N> , skip first N tasks for pagination
• --group , group output by project
• --format <plain|rich|json|yaml> , output format
• --verbose , log API requests for debugging

Output: formatted list of tasks matching filters, or json/yaml for machine parsing.

Edge cases: empty result set (no tasks match filters), rate limit hit (wait 60s, retry), network timeout (retry with backoff).

---

3. create task

Command: /tasks add "<title>" [options]

Input:

• <title> (required): task name as quoted string
• --list <project> (required if no default.project configured): project name or ID
• --due <when> (optional): due date in natural language or ISO format
• --priority <low|medium|high> (optional): priority level
• --content "<notes>" (optional): task description
• --tags <tag1 tag2 ...> (optional): space-separated tags

Output: created task object with ID, or confirmation message.

Edge case: project not found (returns error; verify with /tasks projects), invalid due date format (retried with iso parsing), no default project and --list omitted (returns error requiring project).

---

4. edit task

Command: /tasks edit <task-id> [options]

Input:

• <task-id> (required): 24-character hex task ID
• --title "<new title>" (optional): replace title
• --content "<new notes>" (optional): replace content
• --due <date> (optional): change due date
• --priority <level> (optional): change priority (none, low, medium, high)
• --tags <tags...> (optional): replace tags (space-separated)
• --json (optional): output updated task as json
• --verbose (optional): log diagnostic info

Output: updated task object or confirmation message.

Edge case: task not found (returns error; verify ID with /tasks --json), invalid task ID format (returns parse error), network timeout during update (retry, check task state with /tasks details <id>).

---

5. complete task

Command: /tasks complete <task-id> or /tasks done <task-id> or /ticktick complete <task-id> (aliases)

Input:

• <task-id> (required): 24-character hex task ID
• --json (optional): output as json

Output: confirmation message or json representation of completed task.

Edge case: task not found (returns error), task already completed (api may accept idempotently or error; check with /tasks details).

---

6. abandon task

Command: /tasks abandon <task-id> or /ticktick abandon <task-id>

Input:

• <task-id> (required): 24-character hex task ID
• --json (optional): output as json

Output: confirmation or json of abandoned task.

Edge case: task not found (returns error), task already abandoned (check state with details).

---

7. batch abandon multiple tasks

Command: /tasks batch-abandon <task-id-1> <task-id-2> ... or /ticktick batch-abandon <task-id-1> ...

Input: space-separated list of task IDs (24-character hex strings).

Output: summary of abandoned tasks or json array.

Edge case: one or more IDs invalid or not found (operation may fail atomically or skip bad IDs; check output), rate limit hit (waits ~60s, retries).

---

8. show task details

Command: /tasks details <task-id> or /ticktick details <task-id>

Input:

• <task-id> (required): 24-character hex task ID
• --json (optional): output as json
• --verbose (optional): show full task object

Output: formatted or json task object with all fields (title, content, due date, priority, tags, status, created, updated, etc.).

Edge case: task not found (returns error), auth expired (re-run auth setup).

---

9. manage configuration

Command: /tasks config get <key> or /tasks config set <key> <value> or /tasks config list

Input:

• get <key>: retrieve single config value
• set <key> <value>: store config key-value
• list: show all config keys and values

Supported keys:

• default.project , default project for add when --list omitted
• default.due , default due date for new tasks ("none", "today", "tomorrow")
• display.colors , enable/disable colored output (true/false)
• display.timezone , timezone for date display (e.g., "America/New_York")

Output: current value, confirmation, or full config dict.

Edge case: invalid key (returns error with supported keys listed), timezone invalid (falls back to UTC).

---

decision points

if oauth credentials not found or expired: re-run bun run scripts/ticktick.ts auth --client-id ... --client-secret ... and retry command.

if --list not provided in add command and no default.project configured: return error requiring --list flag or config set default.project <name>.

if --project filter is provided but no matching project exists: return empty result set (not an error; user may have misspelled name).

if task ID not found in any edit, complete, abandon, details, or batch-abandon command: return "task not found" error; user should verify ID with /tasks --json.

if rate limit (100 req/min) is hit: wait ~60 seconds before retrying. the cli logs backoff info; user can see with --verbose.

if network timeout occurs during api call: retry with exponential backoff (1s, 2s, 4s, then fail). return error after 3 failed attempts.

if due date parsing fails (invalid natural language or malformed iso): fall back to iso parsing, then error if both fail.

if --format json or --format yaml is requested: output raw machine-readable format for scripting; ignore --format rich or --format plain in same command.

if --group is set: group tasks by project name in output, ignoring sort order within groups.

---

output contract

Success looks like:

• projects command: json array of {id, name} or formatted table
• tasks command: json array of task objects or formatted list with columns (title, due, priority, project)
• add command: json object {id, title, project, due, priority, created} or string confirmation
• edit command: json object representing updated task or confirmation message
• complete/done/abandon command: json object or string confirmation (e.g., "task marked complete")
• details command: json object with all task fields or pretty-printed text
• batch-abandon command: json array of abandoned task objects or summary string
• config command: json object {key: value} or confirmation message

Storage: config file written to ~/.config/ticktick-skill/config.json (created if missing). credentials stored in ~/.clawdbot/credentials/ticktick-cli/ by auth setup.

Format defaults: human-readable (rich or plain) unless --json, --yaml, or --format <type> specified. all json output valid json parseable by standard parsers.

---

outcome signal

user knows the skill worked when:

• task appears in /tasks output after /tasks add ... with correct title, project, due date, priority
• task status flips to "completed" in /tasks --status completed after /tasks complete <id>
• task status shows "abandoned" after /tasks abandon <id> (visible in /tasks details <id>)
• project filtering works: /tasks --project Work shows only work tasks
• due date filtering works: /tasks --due today shows only today's tasks
• edited task reflects new title, content, or priority after /tasks edit <id> --title "new"
• config persists: /tasks config set default.project Personal then /tasks add "foo" uses Personal without --list
• grouped output clusters tasks by project name when --group used
• colored output renders priority/urgency in distinct colors when --format rich used and display.colors is true
• rate limit backoff happens silently: user sees no interruption but cli waits 60s before retry if 100 req/min hit
• json output is valid json: jq and other tools parse it without error

---

credits: original skill from clawhub. enriched to include explicit inputs, edge cases, decision points, and output contract per implexa standards.