What It Does

The ToDone skill adds a /todo command to Claude Code. When you say /todo Fix the login redirect bug, it:

1. Enriches the todo by scanning your codebase for related files and context
2. Appends the task to a local docs/TODO.md file in your project
3. Creates the task in your ToDone workspace via the API
4. Syncs both sources bidirectionally — tasks added or completed on either side stay in sync

This means your todos live in two places: version-controlled markdown in your repo, and your ToDone dashboard.

Prerequisites

Setup

1. Create the skill directory

In your project root, create the skill folder:

mkdir -p .claude/skills/todo

2. Copy the skill file

Create .claude/skills/todo/SKILL.md with the contents from The Skill File below. The full file is ready to copy.

3. Configure your API key

In the skill file, replace <YOUR_API_KEY> with the API key you generated in ToDone:

| API key | `td_abc123...` |

4. Test it

Open Claude Code in your project and type:

/todo Add a test task

Claude will create the task in both docs/TODO.md and your ToDone workspace.

The Skill File

Copy this entire block into .claude/skills/todo/SKILL.md:

---
name: todo
description: "Add a todo to docs/TODO.md and the ToDone app, then bidirectionally sync both sources. Invoke via '/todo'."
user-invocable: true
disable-model-invocation: false
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# Todo — Add & Sync

## Config
| Key | Value |
|-----|-------|
| API base | `https://www.todone.fyi` |
| API key | `<YOUR_API_KEY>` |
| Auth header | `Authorization: Bearer <YOUR_API_KEY>` |
| TODO file | `docs/TODO.md` |
| Category name | `ToDone` |

All `curl` calls use `-s` and the auth header above.

## Phase 1 — Add New Item
1. **Parse** — Extract title + details from user message.
2. **Enrich** — Glob/Grep the codebase for related files. Add 1-3 sentences of context as the description. Check for related existing TODOs.
3. **Append to TODO file** — Read the file, pick the best `##` section (`Features`, `UI / Design`, `Views`, `API`, `Deployment / Infrastructure`, `Platform`, `Real-Time`, `Bugs` — default `Features`). Append:
   ```
   ### <Title>
   - **Status:** TODO
   - <description>
   ```
4. **Create in app** — `GET /api/categories` to find the category ID (create via `POST /api/categories` if missing). Then `POST /api/tasks` with `{ title, body, categoryId, force: true }`.

## Phase 2 — Bidirectional Sync
5. **Fetch live tasks** — `GET /api/tasks?categoryId=<id>` for all tasks in the category.
6. **Parse TODO file** — Extract every `### <Title>` and its `**Status:**`.
7. **Reconcile** — Match by normalized title (case-insensitive; use fuzzy judgement for near-matches).

| Live app | TODO file | Action |
|----------|-----------|--------|
| Active, not in file | — | Add to file in appropriate section |
| — | Status: TODO, not in app | `POST /api/tasks` with `force: true` |
| Completed (`completedAt` set) | Status: TODO | Update file status to `Done` |
| Active, has body | No/different description | Update file description |
| — | Has description, app task has no body | `PATCH /api/tasks/:id` with `{ body }` |
| Both agree (both done, or both match) | — | No change |

8. **Report** — Tell the user: what was added, sync summary (items added/updated/status-changed per side), total active count.

## API Quick Ref
| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/api/tasks` | Params: `categoryId`, `stageId`, `priority`, `sort`, `order` |
| `POST` | `/api/tasks` | Body: `{ title, body?, categoryId?, priority?, force? }`. Returns 409 on duplicate. |
| `PATCH` | `/api/tasks/:id` | Same fields as POST (minus `force`), plus `position`. |
| `DELETE` | `/api/tasks/:id` | Returns 204. |
| `GET` | `/api/categories` | |
| `POST` | `/api/categories` | Body: `{ name, color? }` |

Priority values: `LOWEST`, `LOW`, `MEDIUM`, `HIGH`, `URGENT`, or omit for none.
Field limits: title 500 chars, body 50k chars.
Errors: 400 bad request, 401 unauth, 403 forbidden, 404 not found, 409 duplicate/similar.

How It Works

Phase 1: Adding a todo

When you invoke /todo, Claude:

1. Parses your message to extract the task title and any details
2. Scans your codebase with Glob and Grep to find related files, then writes a short description with context
3. Appends the task to docs/TODO.md under the most relevant section heading
4. Creates the task in ToDone via the API, filed under a "ToDone" category (created automatically if it doesn't exist)

Phase 2: Bidirectional sync

After adding the new item, Claude syncs everything:

• Tasks in ToDone but not in the file get added to the file
• Tasks in the file but not in ToDone get created via the API
• Tasks completed in ToDone get their file status updated to "Done"
• Description differences are reconciled (longer/newer description wins)

The sync runs automatically every time you use /todo.

Usage Examples

/todo Fix the login redirect bug

Creates a task, enriches it with context from auth-related files, syncs.

/todo Add rate limiting to the API endpoints

Scans for API route files, notes which endpoints exist, creates a detailed task.

/todo Sync my todos

Skips creating a new task and just runs the bidirectional sync.