Skip to content
Skills Library
AI & agents · Planning

showcase-progress

/showcase-progress

A progress bar for long agent tasks that can't be faked. Split the work into subtasks with time estimates; a script computes progress = finished estimated time / total estimated time, reports time left and an ETA, and corrects the ETA from real durations. Use it whenever a task will take more than ~15 minutes or has 3+ deliverable steps (features, refactors, migrations, bulk fixes, long reports, multi-part analyses), when the user asks "how long will this take", "where are we", "what's left", "ETA", or wants a progress bar, and when resuming interrupted multi-step work. Also triggers on 进度条, 还

Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: install.ps1, install.sh

What it does and when to use it

A progress bar for long agent tasks that can't be faked. Split the work into subtasks with time estimates; a script computes progress = finished estimated time / total estimated time, reports time left and an ETA, and corrects the ETA from real durations. Use it whenever a task will take more than ~15 minutes or has 3+ deliverable steps (features, refactors, migrations, bulk fixes, long reports, multi-part analyses), when the user asks "how long will this take", "where are we", "what's left", "ETA", or wants a progress bar, and when resuming interrupted multi-step work. Also triggers on 进度条, 还

Triggers from the description

how long will this takewhere are wewhatETA
Original author description

A progress bar for long agent tasks that can't be faked. Split the work into subtasks with time estimates; a script computes progress = finished estimated time / total estimated time, reports time left and an ETA, and corrects the ETA from real durations. Use it whenever a task will take more than ~15 minutes or has 3+ deliverable steps (features, refactors, migrations, bulk fixes, long reports, multi-part analyses), when the user asks "how long will this take", "where are we", "what's left", "ETA", or wants a progress bar, and when resuming interrupted multi-step work. Also triggers on 进度条, 还

How it works

  1. When to use it
  2. Step 1 — estimate before you start
  3. Step 2 — create the ledger
  4. Step 3 — move it forward at subtask boundaries
  5. Post it, or it didn't happen
  6. Changing the plan
  7. Finishing
  8. Anti-patterns
  9. Status line (Claude Code)
  10. References
Original SKILL.md headings · 177 lines, 1,330 words
SKILL.md preview
---
name: showcase-progress
description: >
  A progress bar for long agent tasks that can't be faked. Split the work into
  subtasks with time estimates; a script computes progress = finished estimated
  time / total estimated time, reports time left and an ETA, and corrects the
  ETA from real durations. Use it whenever a task will take more than ~15
  minutes or has 3+ deliverable steps (features, refactors, migrations, bulk
  fixes, long reports, multi-part analyses), when the user asks "how long will
  this take", "where are we", "what's left", "ETA", or wants a progress bar, and
  when resuming interrupted multi-step work. Also triggers on 进度条, 还要多久,
  到哪一步了, 什么时候能好, 剩多少. Skip it for one- or two-step tasks.
license: MIT
compatibility: Needs Python 3.8+ (standard library only) to run scripts/progress.py.
metadata:
  version: "1.1.0"
---

# showcase-progress

An agent's progress bar usually lies in two places: **how big the job is** and
**how much is left**. This skill puts both on the table and lets a script do the
arithmetic, so the number you post comes from a ledger, not from a feeling.

- Denominator = sum of every subtask's estimated time (visible, editable)
- Numerator = estimated time of the subtasks that are actually done
- Time left = open estimate × measured pace (only once there is real data)

Run the script as `python3 <this-skill-dir>/scripts/progress.py` (`python` on
Windows). The ledger lives in `.showcase-progress/state.json` in the project, so
the task survives restarts and can be resumed by another session or agent.

## When to use it

Use it when the task has 3+ subtasks and will take a while, when the user asks
how long / where are we, or when picking up interrupted work.

Don't use it for a two-minute fix or a pure discussion. Rule of thumb: if the
user would ask "how much longer?", use it; if they'd ask "you made a progress
bar for *this*?", don't.

## Step 1 — estimate before you start

Plan first, don't code yet. Produce 5–9 subtasks. Each one needs:

- an id and a title that names a **deliverable**, not an action
  ("token endpoint returns a JWT", not "write code")
- an estimate: `30m`, `1h30m`, `2h`, `45分钟` all work
- optionally `done_when`: one sentence that would prove it's finished

Estimate **your own** time as the agent doing the work, not how long a human
developer would take — writing a small module may take you two minutes, while
waiting on builds, installs or the user can take far longer. Estimate how long
it will really take, not how long it takes if nothing goes wrong. Uneven numbers (15m / 40m / 1h20m) mean you thought about each step; a
column of `1h, 1h, 1h` means you guessed. Spend a few minutes looking at the
code or material first — investigating is often its own first subtask.
See `references/estimating.md` for sizing rules and worked examples.

## Step 2 — create the ledger

```bash
python3 scripts/progress.py init --plan plan.json
```

```json
{
  "title": "Add password reset",
  "subtasks": [
    {"id": "Q1", "title": "Map the current auth flow", "est": "25m"},
    {"id": "Q2", "title": "Reset-token endpoint works", "est": "1h10m",
     "done_when": "POST /reset returns 202 and a token row exists"},
    {"id": "Q3", "title": "Reset page and form", "est": "1h20m"}
  ]
}
```

You can also pass `--subtasks '<json array>'` and `--title` inline. Output is
ready to paste:

```
Progress  0.0% [□□□□□□□□□□□□□□□□□□□□] plan 2h55m · 2h55m left · ETA 11:55
Next: Q1 "Map the current auth flow" est 25m
```

Output language follows the task title (a Chinese title gives Chinese output);
override with `--lang en|zh` or `SP_LANG`.

## Step 3 — move it forward at subtask boundaries

```bash
python3 scripts/progress.py update "Q1=doing"                     # starts the clock for Q1
python3 scripts/progress.py update "Q1=done" --brief              # stops it
python3 scripts/progress.py update "Q2=done" --evidence "curl returned 202, row id 17" --brief
python3 scripts/progress.py update "Q3=doing" --count 2/6 --brief
python3 scripts/progress.py update "Q4=blocked(waiting for staging access)"
python3 scripts/progress.py update "Q5=dropped(out of scope)"
```

**`doing` earns nothing.** Half-finished work isn't progress — the file exists
but doesn't run, the migration is stuck at table 200. Only `done` earns its
full estimate. The bar will jump in steps; that's what real progress looks
like.

**The one exception is a count.** If the subtask has countable units — 3 of 6
handlers migrated, 12 of 20 tests passing — `--count k/n` earns that share.
Only use it when you can point at the k things; a count is evidence, a guessed
"60%" is not, so there is no flag for that.

**Let the script time it — don't report times from memory.** When a subtask
goes `done`, the script records how long it took: from when you marked it
`doing`, or else since the previous update. Agents asked "how long did that
take?" answer in human time; this skill's own author-agent once reported 2h35m
for ten minutes of wall clock. So update **one subtask at a time, as it
happens**: mark `doing` when you start, `done` when you finish. Batching
updates at the end of a turn ruins the timing (a batch `done` isn't timed at
all). Pass `--took 40m` only when you have a real number from elsewhere — the
user told you, or a command printed its runtime.

Measured times turn the plan into a forecast: once two finished subtasks with
real durations cover 20%+ of the plan and the pace is off by more than 15%,
time left is rescaled and labelled "at current pace".

**Give `--evidence` for subtasks with `done_when`.** What did you run or see
that proves it? `check` warns about done subtasks that have a condition but no
evidence. Planning, doing and verifying are different steps — writing a plan
is not finishing the work.

## Post it, or it didn't happen

The user can't see tool output. Running `update` without pasting the result
into your reply means the skill did nothing.

1. **Each time a subtask finishes, paste the one line** that `--brief` prints,
   next to a sentence about what was done. Don't batch three updates into the
   end of the turn.
2. **When resuming or asked "where are we", post the status first**
   (`render`), then continue.
3. **At the end, post the export** — the estimate-vs-actual table is the most
   useful thing this skill produces.
4. **Never repost an unchanged number.** If nothing moved, say "still on Q3".

Use the full block (`render`) only at start, on request, and at the end; use
one line for live updates. If the user says "stop reporting, just do it",
do that.

## Changing the plan

Plans change. Use `replan`, never `init` (which starts over):

```bash
python3 scripts/progress.py replan --plan plan-v2.json --reason "split Q4: staging access pending"
python3 scripts/progress.py update "Q3=doing" --est 2h30m      # one estimate was wrong
```

Done subtasks keep their state, actual time and evidence. Adding work lowers
the percentage — that's correct, and the reason is recorded in history. Never
quietly shrink the denominator to make the bar look better.

## Finishing

```bash
python3 scripts/progress.py check      # exit 1 only when numbers can't be trusted
python3 scripts/progress.py export     # .showcase-progress/progress.json + PROGRESS.md
python3 scripts/progress.py history    # replay every step
```

## Anti-patterns

| Don't | Why | Instead |
|---|---|---|
| Run `update` but not paste the line | The user sees nothing | Paste after every done |
| Type a percentage yourself | Drifts from the ledger | Only post script output |
| Give `doing` partial credit by feel | Inflates the bar; the last 10% takes forever | `--count k/n` or nothing |
| 15 subtasks of exactly 1h each | Obviously invented, no information | 5–9 uneven, honest estimates |
| Split work finer to "make progress" | Weights are time, so it can't inflate — it only adds noise | Split by deliverable |
| Quietly edit estimates down | Destroys trust in "time left" | `--est` or `replan --reason` |
| Guess `--took` from memory | Agents report human-scale times; the ETA goes wrong | Mark `doing`/`done` as it happens; the script times it |
| Batch several `done`s at the end | No timing, and the user saw nothing live | One update per finished subtask |

## Status line (Claude Code)

If the user wants the bar always visible, `scripts/statusline.py` prints it in
Claude Code's status line from the nearest `.showcase-progress/state.json`. Set
it up only when asked, since it edits the user's settings: point `statusLine`
at `python <skill-dir>/scripts/statusline.py`, and if they already have a
status line, keep it with `--chain "<their existing command>"`.

## References

- `references/estimating.md` — sizing, splitting, worked examples
- `references/states.md` — states, counts, evidence, replanning, check rules
- `references/rendering.md` — output modes, narrow screens, GBK consoles
- `PROMPT.md` — a no-script version for chat-only models
Files in this package (11)
  • .gitattributes 1 KB
  • .gitignore 1 KB
  • CHANGELOG.md 1 KB
  • LICENSE 1 KB
  • PROMPT.md 2 KB
  • PROMPT.zh-CN.md 2 KB
  • README.md 10 KB
  • README.zh-CN.md 10 KB
  • SKILL.md 9 KB
  • install.ps1 1 KB
  • install.sh 1 KB

Versions

The database has no other skills named showcase-progress.

Database snapshot: 13.11.2026 · package version 3b9dfbaae24d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90build-tracker
    Live HTML progress page for multi-step work - current task with elapsed time, done tasks with durations, to-do tasks with estimates, overall ETA, updating in real time. Use when the user says "set up the build tracker", "track progress of this work", "show me task progress", or…
  • 84eta
    Assess the current task's progress and give a grounded ETA, backed by a global learning knowledge base at ~/.claude/.eta/ that gets better as real durations are recorded. Produces a progress overview, a completion table (mirrors the ticket's structure when a ticket is in scope,…
  • 100eta
    Estimate how long a piece of Claude Code work will really take — agent time vs the user's time, a range, the biggest risk, and speed-ups. Use when the user asks "how long will this take", wants an ETA or time estimate for a feature or build, or passes a plan file to estimate.
  • 100realtime-est
    Calibrated time estimates for work done by an AI agent (you), based on the user's real Claude Code history instead of human-scale intuition. Use BEFORE stating any duration, ETA, effort or timeline for a task you or other agents will do — "how long will this take", "ile to…
  • 100agent-task-checklist
    Use this skill when the user says 'track progress', 'task.md', 'keep a checklist', 'break this into steps', 'show me what is done', or when an agent executes a long multi-step task that should remain transparent and resumable. It maintains a granular, frequently updated…
  • 90file-based-planning
    Keep a long task's progress, findings and dead ends in files so a reset or crash resumes from disk. USE WHEN work is long-running. NOT FOR ordering steps, handoff notes or doc drift.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.