# Managing Todos

> Use when needing to capture, list, update, or archive todo items noticed during a session. Also use when you notice something worth fixing later but unrelated to the current task — in that case, ask user before creating.

- Skill: `cauethenorio/managing-todos` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cauethenorio/managing-todos`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cauethenorio/managing-todos/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: cauethenorio (https://skillmd.com/u/cauethenorio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cauethenorio/managing-todos

---


# Managing Todos

Lightweight todo tracking using markdown files. Todos capture things noticed during a session to tackle later.

## Directory & Customization

Default directory: `docs/todos/`, archived todos go to `docs/todos/done/`.

**Projects can override defaults in their CLAUDE.md:**

```markdown
## Todos
- directory: .todos/
- statuses: open, in-progress, blocked, done, wont-fix
```

The `todo.sh` script in this skill directory reads `## Todos` from CLAUDE.md automatically.

## The Script

**Always use `~/.claude/skills/managing-todos/todo.sh` for all operations.** It validates statuses, priorities, sets the correct created date, and respects CLAUDE.md overrides.

```bash
# Create
todo.sh create -t "Fix hardcoded URL" -p high --tags "refactor,config" -d "Move API URL to env var"

# Multiline description
todo.sh create -t "Fix auth flow" -p high -d $'First line.\nSecond line.\nThird line.'

# List / Filter
todo.sh list                          # all active todos
todo.sh list -s open -p high          # open + high priority
todo.sh list --tag frontend           # by tag

# Update
todo.sh update "hardcoded-url" -s in-progress
todo.sh update "hardcoded-url" -p low --tags "config,cleanup"

# Archive (sets status=done + moves to done/ subfolder)
todo.sh archive "hardcoded-url"
```

Run `todo.sh` with no args for full usage.

File matching is partial — `"hardcoded-url"` matches `2026-03-25-fix-hardcoded-url.md`.

## File Format

**Filename:** `YYYY-MM-DD-short-description.md` (auto-generated by script)

**Frontmatter:**
- `status` — `open`, `in-progress`, `done` (or project-custom)
- `priority` — `low`, `medium`, `high`
- `created` — ISO date (auto-set by script)
- `tags` — YAML list

## List Output Format

```
## Open Todos (2)

**[high] Add error boundaries** (2026-03-15) — frontend, error-handling
  No error boundaries in place. A crash takes down the whole page.

**[medium] Update deprecated deps** (2026-03-18) — dependencies
  Replace node-sass, request, moment with modern alternatives.
```

## Auto-Detection

When you notice something during a session that is unrelated to the current task and worth capturing:

**You MUST ask the user before creating a todo.** Example:

> I noticed [issue]. Want me to create a todo for this?

**Never silently create todos.** The user may already be aware, may disagree on priority, or may not want it tracked.

Only skip confirmation when the user explicitly says something like "todo: fix X later" or "add a todo for Y" — that's direct instruction, not auto-detection.

## Common Mistakes

- Creating todos without the script (bypasses validation)
- Creating todos without asking when auto-detecting
- Archiving by deleting instead of using `todo.sh archive`