Manage Todos
Productivitymanage-todosManage Todos is an Agent Skill for productivity published in the nikolovlazar/dotfiles repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create, list, and update repository TODOs in Markdown. Use when the user asks to add/write TODOs, list current TODOs, track progress or feature work, mark TODOs done, blocked, or cancelled, or prompt for blocked/cancelled reasons before changing status.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/nikolovlazar/dotfiles/blob/HEAD/.agents/skills/manage-todos/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/manage-todos, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Manage TODOs
Overview
Use the repository's existing TODO conventions first. If no convention exists, prefer a root TODO.md with stable IDs and simple Markdown sections.
Canonical Format
Use this default format unless the repository already defines another one:
- [ ] TODO-0001: Short imperative title
- Status: todo
- Area: docs
- Goal: One sentence describing the outcome.
- Done when: Concrete acceptance criteria.
Allowed statuses:
todo: Not started or not currently active.in-progress: Started but incomplete.blocked: Cannot proceed until something changes.done: Completed and verified.cancelled: Intentionally abandoned.
When marking a TODO done, set the checkbox to [x]. For every other status, keep [ ].
Write TODOs
- Inspect existing TODO files before adding anything. Prefer root
TODO.md; also checkdocs/todos/if it exists. - Reuse the next numeric ID in the existing sequence. If no sequence exists, start at
TODO-0001. - Write the title as a short action, not a vague theme.
- Include
Area,Goal, andDone whenunless the existing file uses a leaner format. - Keep TODOs small enough to complete in one focused change. Split large features into a parent TODO plus concrete child TODOs only when useful.
- Avoid hiding important follow-up work only in chat; add it to the TODO file when the user wants persistent tracking.
List TODOs
When listing TODOs:
- Read the TODO source directly.
- Group by status or by the file's sections, whichever is clearer.
- Include each TODO ID, title, status, and any blocker/cancel reason.
- Keep the response concise. Do not paste the full file unless the user asks.
Change Status
When changing a TODO status:
- Identify the TODO by ID. If the user gives only a title, match conservatively and ask if ambiguous.
- Update the checkbox and
Statusfield together. - Move the TODO between sections only if the file already uses status sections.
- For
done, addCompleted: YYYY-MM-DDif the file already tracks dates. - For
blocked, add or updateBlocked reason: .... - For
cancelled, add or updateCancelled reason: ....
If the user asks to mark a TODO blocked or cancelled without a reason, ask for the reason before editing unless they explicitly say to skip it. A short prompt is enough:
What should I record as the blocked reason for TODO-0003?
Do not invent blocker or cancellation reasons. If the reason is obvious from the user's message, use it and do not ask.
Handoff
After editing TODOs, summarize:
- TODOs added or changed.
- Any status reasons recorded.
- Any verification performed, such as Markdown link checks or file review.