todo

Manages a persistent nested task queue in a single TODO.json file via a prebuilt binary.

Updated Aug 4, 2026
One-click install
npx skills add https://github.com/tschallacka/ai-skills --skill todo-tschallacka
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: todo
Source: https://github.com/tschallacka/ai-skills/tree/main/todo
Command: npx skills add https://github.com/tschallacka/ai-skills --skill todo-tschallacka

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Work items tracked only in chat disappear when a conversation ends, a context window compacts, or a session is handed off. This Skill keeps a durable, structured task queue in one TODO.json file that survives restarts and handoffs, with every closed task carrying the evidence of how it was closed. ## Core Features & Use Cases - Nested task register: Tasks and sub-tasks live in one JSON file with stable ids, priorities, statuses, timestamps, and refs, managed through the todo command rather than hand-editing. - Enforced closure evidence: Closing a task as done, dropped, or obsolete without a note is refused, so every closed item records what happened. - Queue hygiene and safety: todo prune archives closed tasks to dated files while holding back anything an open task still depends on, todo check validates the register, and todo resolve handles merge conflicts over task ids. - Use Case: An agent juggling a multi-session refactor files each work item with todo add, checks todo report at the start of every session to see what is still open, and closes items with commit references as they land. ## Quick Start Ask the agent to register the current work items in the todo queue and show what is still open.

Frequently Asked Questions about todo

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep a task list that survives between AI chat sessions?▼

Store tasks in a TODO.json file managed by the todo command instead of chat checklists. The file persists across restarts and handoffs, and todo report prints what is still open at the start of any new session.

How do I add a sub-task to an existing task in the todo queue?▼

Run todo add with --parent followed by the parent task id, along with the required --title and --detail flags. Sub-tasks carry their own priority and can be closed independently while sibling tasks remain open.

When should I use a JSON task register instead of an in-chat checklist?▼

Use the register when work must outlive the conversation, span a restart or handoff, or when juggling three or more separate work items. Short checklists finished within one conversation and defects belong elsewhere, such as the bug-report skill.

Why does closing a task fail without a note?▼

The todo command refuses to set done, dropped, or obsolete without a --note explaining what happened. This guarantees every closed task carries evidence such as a commit, decision, or reason, so closures remain auditable later.

Can the todo tool handle a git merge conflict in TODO.json?▼

Yes, todo resolve reads both sides from the git index mid-conflict, reports colliding ids, and applies rename decisions you pass in one run. Nothing is written until you return the confirmation token it prints.

What happens to closed tasks when the queue gets too long?▼

todo prune moves closed tasks into a dated TODO.<date>.archive.json file, which remains a readable queue itself. Tasks still referenced by open work through parent or blocked_on links are kept back automatically.