Index of every page on this site: llms.txt
All skills
paulrberg avatar

/todo-archive

@c9e5a34
by Paul Bergpaulrberg/agent-skills106 stars
11
Run it yourself

Archive checked `.ai/TODO.md` tasks into `.ai/todos/YYYY-MM/DD.md`, leaving unchecked tasks.

Use this Skill: https://skilld.dev/gh/paulrberg/agent-skills/todo-archive

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈27 tokens for metadata: the name and description. ≈949 when used: this file. ≈11 more on demand in 1 file.

How this Skill uses context

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

This Skill turns off automatic use in Claude Code. Its description stays out of the automatic Skill list by default.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

    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:

    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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts21d3 checks · Risk SAFE
  • Gen Agent Trust Hub21d

    The skill archives completed tasks from a Markdown file. It performs local file operations and uses Git to locate the repository root. No network communication or unsafe code execution was found.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

Signed by skilld at c9e5a34. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last month
Modelsonnet
argument-hint
[path] [--hint TEXT] [--date YYYY-MM-DD|YYYY_MM_DD] [--dry-run]
disable-model-invocation
true
effort
low
Other metadata
model
sonnet

README badge

README badge for paulrberg/agent-skills/todo-archive