rave-altfred/claude-backlog-skill

A Claude Code skill that keeps a project's task list in one file, docs/backlog.md, and lets you drive it with a slash command:
The backlog stays a readable Markdown file that lives in your repo next to the code. You can edit it by hand, diff it, and review it in pull requests. The skill makes sure Claude edits it the same careful way every time.
Why a script and not just a prompt
Asking a model to "move B-042 to Done" usually means it re-types the whole line, and long lines come back slightly changed. Here every edit goes through backlog.py, a small standard-library Python script that:
- moves and re-marks lines without retyping them,
- hands out IDs from the footer and never reuses an ID already in the file,
- keeps the **Now** section in step (start adds a pointer, done and drop remove it),
- refuses to guess: an ambiguous ID, text, or section name stops with a list of matches.
Claude only decides *what* to do; the script does the editing. The skill runs on your session's model, so judgement calls such as the next suggestion get the same model as the rest of your work. To make it faster and cheaper, add model: haiku to the frontmatter of SKILL.md.
Install
Clone the repo into your personal skills folder:
Start a new Claude Code session and type /backlog. To update later:
The folder must be named backlog and sit at ~/.claude/skills/backlog, because SKILL.md calls the script by that path.
Requirements
- Python 3.9 or newer (python3 on your PATH). No packages to install.
- macOS or Linux. The script uses fcntl file locking, so it does not run on native Windows (WSL works).
- git is optional. The script uses it to find the repo root; without git it uses the current folder.
Getting started
In a project, run:
This creates docs/backlog.md with IDs starting at W-001 (the default prefix is B). It never overwrites an existing file.
Commands
| Command | What it does |
|---|---|
| /backlog or /backlog status | What is in Now, what is in progress, open counts per section, next free ID |
| /backlog next | Now, in-progress tasks, and the top 3 open tasks per section, plus a suggestion for what to pick |
| /backlog add | One task per item (split on new lines, ;, or a list). Goes to Inbox, or add --bug … for Bugs, or add to : … |
| /backlog start | Mark [~] and add a pointer in Now |
| /backlog done [note] | Mark [x] with today's date and the note, move it to the top of Done |
| /backlog drop | Mark [-] with the reason and leave it where it is |
| /backlog move | Move to another section. Moving an idea out of the Inbox gives it an ID if it has none |
| /backlog split | Replace a task with smaller tasks right under it |
| /backlog show | Matching lines, their section, and which other tasks mention the ID |
Section names match loosely: bugs, phase 2, and inbox all work.
You can also just ask in plain words ("what's next on the backlog?", "mark W-006 done") and Claude will use the skill.