Skip to main content
skill CX Codex

todo-archive — Claude Code skill: what it does, how to install

todo-archive moves completed .ai/TODO.md tasks into dated daily archive files. Unchecked items stay untouched.

MIT 130 installs ★ 107 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PaulRBerg/agent-skills --skill todo-archive -a claude-code
Open on GitHub

What todo-archive does

The skill resolves the repository root and locates .ai/TODO.md. It extracts completed checklist items and moves them into .ai/todos/YYYY-MM/DD.md. Prose and unchecked tasks remain in the main file.

Execution is handled by scripts/archive_todo.py invoked through uv run python. Without Python and the uv package runner installed, the helper fails immediately.

The --hint option restricts task processing to headings matching specific text. Running --dry-run previews file paths and item counts before writing to disk.

What it helps with

  • move checked items from .ai/TODO.md to daily logs
  • keep unresolved checklist items intact in the main file
  • archive tasks under a single heading using --hint
  • preview task migrations safely using --dry-run

Example prompts for the agent

  • Archive completed tasks from .ai/TODO.md
  • Run task archiving for section --hint backend
  • Preview the archive changes with --dry-run

How to install todo-archive

1Skills CLI (Vercel)

npx skills add PaulRBerg/agent-skills --skill todo-archive -a claude-code

2Manually: put the files in place

~/.claude/skills/todo-archive/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/todo-archive/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about todo-archive

How to install todo-archive in Claude Code?

Run npx skills add PaulRBerg/agent-skills --skill todo-archive -a claude-code.

What does todo-archive do?

It scans .ai/TODO.md, extracts checked items, and appends them to .ai/todos/YYYY-MM/DD.md. Unfinished tasks stay in the original file.

What dependencies does todo-archive require?

The skill runs scripts/archive_todo.py via uv run python, so both Python and the uv tool must be installed.

Source text

SKILL.md · MIT
---
argument-hint: "[path] [--hint TEXT] [--date YYYY-MM-DD|YYYY_MM_DD] [--dry-run]"
disable-model-invocation: true
effort: low
model: sonnet
name: todo-archive
description: Archive checked `.ai/TODO.md` tasks into `.ai/todos/YYYY-MM/DD.md`, leaving unchecked tasks.
---

# TODO Archive

If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that
case, do not invoke this skill again through a skill tool.

## Arguments

- `path` (optional): Repository root or any path inside the repository. Default to the current directory.
- `--hint TEXT` (optional): Archive only the section whose heading contains `TEXT` (case-insensitive substring),
  including its subsections. Without it, archive checked tasks from the whole file. Checked tasks outside the matched
  section stay in `.ai/TODO.md`.
- `--date YYYY-MM-DD|YYYY_MM_DD` (optional): Archive date. Default to today's local date.
- `--dry-run` (optional): Preview target paths and rendered content without writing.

## Workflow

1. Resolve the supplied `path`, or the current directory when omitted. For an existing file, use its containing
   directory. For a directory, use that directory. Store the absolute directory as `start_dir`, then resolve its Git
   root:

   ```sh
   git -C "$start_dir" rev-parse --show-toplevel
   ```

   Store the result as `repo_root`. When `start_dir` is outside a Git repository, use it as `repo_root`. Stop on a
   missing input path or another resolution error.

2. Verify `.ai/TODO.md` exists under the root. If it is missing, stop and report the path checked.

3. Resolve the skill directory and run its helper:

   ```sh
   uv run python "<skill-dir>/scripts/archive_todo.py" --root "$repo_root"
   ```

   Pass through `--hint`, `--date`, or `--dry-run` when the user requested them.

4. Report the rewritten `.ai/TODO.md`, the created or merged archive path, the matched section (when `--hint` was
   given), and the archived/remaining task counts. If an archive for the date already exists, the helper appends the new
   batch to it, retaining one matching top-level heading. If the helper reports no checked tasks, treat it as a no-op.
   If `--hint` matches no heading, the helper exits non-zero and lists the available sections. In that case, relay them.

5. If useful, inspect only `<repo_root>/.ai/TODO.md` and the exact archive path returned by the helper. Verify their
   contents directly. When Git ignores them, compare filesystem snapshots rather than relying on `git diff`.

## Helper Behavior

`scripts/archive_todo.py` reads `<root>/.ai/TODO.md` and any existing archive for the date, writes archived tasks to
`<root>/.ai/todos/YYYY-MM/DD.md`, and rewrites `<root>/.ai/TODO.md` with the remaining tasks. It preserves task-free
sections and prose verbatim (a minimal stub with the source's first heading, or `# TODO`, only if everything was
archived). With `--hint`, it restricts archiving to the matched heading's subtree and exits non-zero listing available
headings when nothing matches. A same-day re-run appends its batch to that day's file, removing the new leading H1 only
when it exactly matches the existing archive's leading H1.

## Completion

Completion evidence is the helper's archive path plus archived and remaining task counts. A no-checked-task result is a
successful no-op. Dry-run completion requires rendered paths/content with no filesystem changes, but the final message
still follows the one-line formats below. Report the result as a single line (append a `(scope: "<hint>")` segment only
when `--hint` was given), with the archive path relative to the repository root:

- Success: `📦 Archived <n> → <archive path> (created|merged) · <remaining> remaining`
- No-op: `✅ Nothing to archive · <remaining> remaining`
- Dry run: `🔎 Would archive <n> → <archive path> (would create|would merge) · <remaining> would remain`

Do not repeat full dry-run document content in the final message or add decoration to TODO/archive files, paths,
commands, or helper diagnostics.

© PaulRBerg · MIT · PaulRBerg/agent-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set16

The whole set →
cli-cast cli-cast — a Foundry Cast skill for preparing, simulating, signing, and broadcasting transactions. It also handles ABI data and message signatures. CX Codex +1 309installs spreadsheets spreadsheets — a skill for CSV, TSV and .xlsx files: it inspects structure, edits only the rows you ask for and recalculates formulas. Use it when the table is the main input or output. CX Codex +1 267installs vitest Testing instructions for coding agents writing, running, and debugging Vitest suites in TypeScript projects. CX Codex +1 186installs evm-atlas evm-atlas is a Claude Code skill that researches EVM chains, wallets, transactions, bridges, and historical DEX activity, providing read-only evidence without broadcasting transactions. CX Codex +1 153installs agents-introspection The agents-introspection skill reviews local Codex and Claude Code transcripts to spot recurring agent behavior and suggest a focused durable fix. CX Codex +1 123installs frontend-design frontend-design — a skill for Claude Code, Codex and Cursor that builds web interfaces with custom art direction and verifies them in the rendered UI. CX Codex +1 111installs node-deps-bumper node-deps-bumper — a skill for Claude Code and Codex that structures package upgrades via Taze and guards against regressions. Runs whenever npm, pnpm, yarn, or bun dependencies need updates or dry-run checks. CX Codex +1 106installs release-bumper release-bumper — a skill for Claude Code that automates package releases. It calculates semver bumps, compiles changelog entries, commits changes, and creates annotated tags. CX Codex +1 105installs

Project sponsors

Companies that keep this analytics open