productivity-todoist - SKILL.md Agent Skill

name: productivity-todoist description: Fetch and manage Todoist tasks. Use when the user asks about "todoist tasks", "show my tasks", "what's due", "overdue tasks", "triage tasks", or when another skill needs Todoist task context.

Todoist

Overview

Read Todoist tasks from synced markdown files and manage them via the Python SDK. Provides task context to other skills (e.g., life-coach planning) and allows direct task management from the CLI.

Context

Tasks are synced to todoist-sync/tasks/ as markdown files with YAML frontmatter
Sync freshness is tracked in todoist-sync/sync-status.yml
Token stored at ~/.config/todoist-cli/config.json (set up via npx @doist/todoist-cli auth token)
Triage script uses uv run --script so dependencies are handled automatically
For project structure, labels, priorities, and collaboration model, see the "Todoist organization reference" appendix in todoist-sync/README.md

Process

Step 1: Sync (always do this first)

Run the sync script to refresh local markdown files from Todoist:

./todoist-sync/scripts/sync.py

Or via justfile:

just todoist-sync

Check todoist-sync/sync-status.yml for last sync time. If the sync is recent (within the last hour), you can skip this step.

Step 2: Read tasks from synced files

Tasks live at todoist-sync/tasks/{project-slug}/{section-slug}/{task-slug}.md.

Each file has YAML frontmatter:

---
title: "Review Q1 invoices"
id: "6VpWpv2qfH9pm7fG"
project: "Work"
section: "Business ops"
priority: "p2"
labels: ["30-min", "admin"]
due: "2026-02-15"
recurring: false
created: "2026-02-01T12:00:00+05:30"
updated: "2026-02-08T12:00:00+05:30"
url: "https://app.todoist.com/app/task/..."
parent_id: null
---

To answer common queries, read the frontmatter:

Today's tasks: find files where due is today or earlier
Tasks by project: read from the project's subdirectory
High priority: find files where priority is p1
Tasks with label: find files where labels contains the label
All tasks: read all .md files under todoist-sync/tasks/

Step 3: Triage (write operations)

For modifying tasks (close, reschedule, label), use scripts/todoist-triage.py:

echo '[{"action": "drop", "task_name": "old task"}, {"action": "reschedule", "task_name": "deferred", "due_date": "2026-04-01"}]' | \
  ./scripts/todoist-triage.py

Actions: drop (add "dropped" label + close), complete (close), reschedule (update date), someday (add "someday" label + remove date)

After triage, run sync again to update the local files.

Resources

todoist-sync/scripts/sync.py: One-way sync from Todoist to markdown (run first)
todoist-sync/tasks/: Synced task files (read these for current state)
todoist-sync/sync-status.yml: Sync metadata (last sync time, counts)
scripts/todoist-triage.py: Batch triage via Todoist API (drop/complete/reschedule/someday)

Guidelines

Always sync before reading tasks to ensure freshness
Priority mapping: p1 (urgent/important), p2 (important), p3 (urgent, not important), p4 (neither). Todoist API inverts these: API priority 4 = p1, API priority 1 = p4.
When reviewing tasks during planning: overdue tasks need a decision (reschedule, do today, or drop). Tasks with no due date need --all during weekly review.
After any triage action, re-run sync to update the local markdown files