- name
SKILL.md
Tệp skill vẫn nằm trong kho mã của nhà phát hành.
Dán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add JetBrains/thinkrail --skill todos -a cursor -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add JetBrains/thinkrail --skill todos -a claude-code -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add JetBrains/thinkrail --skill todos -a codex -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add JetBrains/thinkrail --skill todos -a grok -yGửi tin nhắn đã sao chép trong cuộc trò chuyện Grok Bot. Bot sẽ lấy tệp SKILL.md này từ GitHub và thêm vào bộ skill mà mọi Bot của bạn dùng chung.
Install this skill: https://github.com/JetBrains/thinkrail/tree/HEAD/packages/pi-todos/skills/todosTừ nhà phát hành
pending → in_progress → done), and an optional note. The note is agent-facing working
detail — the human's default plan view shows titles + status and keeps notes behind a disclosure —
so it's where your own tracking, reminders, and the done-criterion live (e.g. "login e2e green"),
never a place the user must read to follow along. A task's own status is never stored — it derives from its steps.todo_add (no
group, no after). Loose is pre-work — raw kernels and half-formed asks, never a step you are
about to execute. todo_list renders them last, after every group, on purpose: an item added
mid-task queues after your current work. So finish (or resume) the task you're on before you pick
up a loose item — don't jump to a freshly-added item and abandon a step you had in progress.todo_promote <loose-id>. One
atomic call: the loose item disappears from the queue and a group inherits its id and title. No
duplicate window, no todo_remove dance, and if the session dies right after, the plan still
honestly shows the user's ask as its own group. Then todo_add group:"<same title>" the first
substantive step and flip it in_progress — even a one-liner like "Investigate the ask and sketch
the plan" is a real step, so the user sees her task is being worked on from the first beat. Only
pass title: to todo_promote when the user's wording is unusable as a group title; otherwise keep
it verbatim. Size doesn't matter: a pending loose item is already in the plan, so even a 1–2-step
one becomes a small group. Don't rewrite or drop a loose item for any other reason, and never
author a group via todo_add group: + todo_remove for a user-origin loose item — that's the old
two-step dance todo_promote replaces.todo_list) to stay in sync, don't trust your memory of it.Steps are verifiable and ≈ commit-sized: "easy to check off as you go", not "phase 1".
A step is a substantive, human-meaningful outcome — not your bookkeeping. The plan is the user's
status window, so every step must be something the user cares to see done. Process/meta chatter that
only keeps you oriented is not a step: "make a plan", "read the files", "think about the approach",
"review my changes" — don't mint items for these. Keep the plan to the real, checkable outcomes; put
any working memory you need in the step's note (agent-facing), not as its own item.
Each field answers one question, in one shape — don't let them blur: the title is what the step
does (imperative, about the change/outcome, not the process); the note is your private working
detail; the summary is what changed and why (it must NOT restate the title — add the decision
or constraint the title can't show); the verification is how it was proven, in the normalized
shape check → result (or the honest "not verified").
todo_write with one group per task. Clarifying questions may come first when their answers
change the plan. Publish the plan before execution, then refine it only when the work materially
changes.in_progress when you start it, done when you finish. Starting a new step
auto-returns any other in_progress step to pending — so finish (mark done) before moving on,
or the previous step visibly falls back to open.note, tell the user, and move on to the next group.todo_list before choosing each next item, after user input, and before completion.
New loose items are appended at the end — take them up (promoted) after the in-progress step. If
an item you planned is gone, the user dropped it: skip it and do not re-add it.done they name the task's next step; when nothing is
in_progress they remind you to flip the step you're on. Act on those nudges.todo_add with group:, one per step, or
several calls for several steps). An ordinary 1–2-step chat ask gets that group only when the user
explicitly requested a plan; otherwise finish the in-progress task, then handle it directly. When
that short ask is already a pending loose item, promote it into its own group instead. Never mix a new ask's steps into the current group. A step discovered
inside the current task slots in with todo_add after: <current step id>; an anchor on a loose
item is rejected. Do not rebuild the plan with todo_write for that.todo_list once more before the final handoff. If open
steps remain, either do them or clearly say what is left and why.The user reviews your work from the summary + the diff. The diff shows what; the summary must carry everything the diff cannot show — intent, decisions, and honesty about verification. Write it for the reviewer, not for yourself.
A step that changed code gets a summary AND a verification when you mark it done — pass both
on the same todo_update call that sets status: done. summary is Markdown, written structured
(a short lead sentence + a bullet list when it has parts), covering what changed and why —
especially decisions that are NOT visible in the diff (a rejected alternative, a constraint you worked
around) — not one run-on paragraph. Research/analysis/verification-only steps that produced no code
changes need neither.
Verification is its own field, named, never claimed. Pass verification as one or more checks in
the normalized shape check → result — the exact check you ran and its outcome ("bun test src/todos
→ 34 pass", "typecheck → green") — or the honest "not verified". It renders as Markdown on the
plan page, so when you ran several checks write them as a bullet list (one - check → result per
line), not one run-on line crammed with ; separators; a single check stays one line. The UI shows it
as a status badge on the review card, so a vague or missing line is visible at a glance. Never write "tests pass" for tests you didn't run. And never make a
check pass by weakening it — if you changed, skipped, or deleted a test as part of the step, the
summary must say so explicitly: a reviewer who finds it themselves stops trusting every other
summary.
A step that changed code also gets a commitSubject. The host commits that step's delta on the
user's branch and uses this line as the commit subject verbatim, so write it as a commit message,
not a plan step: one imperative line about the change, and in this repository's existing
style — run git log --oneline -20 and match what you see (Conventional Commits ⇒
type(scope): subject; a prose-subject repo ⇒ prose). It must be pushable as-is: no todo:
prefix, no item ids, no tool attribution. Omit it and the host falls back to the step title, which
reads as a plan step in git log — so don't rely on that.
Disclose scope drift. Anything you touched beyond the step's own ask — an adjacent refactor, a drive-by rename, a new dependency — goes in the summary ("also touched X because Y"). The signature failure of agent changes is solving the asked problem plus neighbors; undisclosed extras are what reviewers distrust most.
When one part of the change deserves the reviewer's closest look — a contract/API change, tricky concurrency, an area you're least sure of — name it in one clause ("closest look: the rollback path").
todo_update → done. Never delete a done item — it's the
user's history. todo_remove is only for when the user explicitly asks to drop something — a user
loose item you take into work is consumed by todo_promote, not removed by hand.todo_update / todo_add (they touch one item) for
a single change — cheaper than restating the whole plan. todo_write reconciles (it's not a
destructive replace): it matches your written steps to the existing ones by group + step title and
keeps their status/summary/id, so a re-plan is safe and lossless — reach for it when you're genuinely
restructuring, not to nudge one item. Status advances only via todo_update; a status you put in
todo_write on a step that already exists is ignored.todo_write never touches loose items and keeps done
items; but keep your steps' titles
stable across a re-plan — a reworded title reads as a new step, so the old one's progress won't carry.)todo_list — read the current plan (the source of truth; re-read to catch the user's edits).todo_add — add one step (into a group, after an existing step, or loose when both are omitted;
leaves the rest untouched).todo_update — progress one step (in_progress on start, done when finished — with a summary
when the step changed code; done stays).todo_promote — turn one loose item into a group of its own (same id, same title) in one atomic
call; this is how a user-origin loose ask enters execution.todo_remove — delete one item (only when the user asks — a promoted loose item is already gone,
todo_promote consumed it).todo_write — lay out or reconcile the plan (groups only — one per task; matches steps by title and
keeps their progress; prefer todo_add/todo_update for a single change).todo_plan_summary — after the last item is done: a short overall summary of what the plan
accomplished.Use when the user asks for a shared plan, a task needs at least three substantive execution steps, or a loose TODO is pending. Without an explicit plan request, not for one-shot answers or checks, or
---name: todosdescription: Use when the user asks for a shared plan, a task needs at least three substantive execution steps, or a loose…---# packages/pi-todos/skills/todos/SKILL.mdTổng quan
Use when the user asks for a shared plan, a task needs at least three substantive execution steps, or a loose TODO is pending. Without an explicit plan request, not for one-shot answers or checks, or one- to two-step work that is not already in the list.
Câu hỏi thường gặp
Tải packages/pi-todos/skills/todos/SKILL.md từ nhà phát hành, hoặc sao chép đường dẫn và mở kho mã. PlugMCP chỉ liệt kê skill và không lưu trữ tệp này.
Nhà phát hành duy trì nó tại https://github.com/JetBrains/thinkrail.
Claude, Cursor, Codex và Grok Build có thể đọc tệp SKILL.md mà bạn thêm từ kho mã của nhà phát hành. Grok Bot cài đặt skill khi bạn gửi liên kết thư mục GitHub của skill trong cuộc trò chuyện.
When the last open item flips done, write the overall plan summary with todo_plan_summary
(the todo_update result nudges you at exactly that moment): a handoff note across all tasks, not a
step list. It is cumulative — it covers EVERYTHING done across the whole plan, not the last step
alone. When the plan gained new work and finished again, a summary from the earlier completion is
still there (the done-flip nudge surfaces it): extend that text — carry every earlier point forward
and add the new work — never rewrite it down to only the most recent step.
Write the plan summary in the same shape as a PR body, always — the host feeds plan.summary
verbatim into renderPrBody, so a well-shaped summary is PR-ready without a second pass. Three H2
sections, in this order:
## Summary — what and why, in prose. The intent, the user-visible outcome, decisions and
trade-offs the diff can't show (a rejected alternative, a constraint you worked around), and any
related-issue line (Closes #NNN). This is the one section the auto-rendered ## Plan can't
speak for.## Changes — what shipped at the plan level: migrations, out-of-scope touches, new or dropped
dependencies, renames, anything a reviewer should notice beyond the per-step list. Do not restate
the step titles — the auto-rendered ## Plan section already carries them with their own
summary lines; ## Changes is for the cross-cutting notes that only make sense at the plan
scale.## Testing — end-to-end verification done beyond per-step checks (e.g. bun run e2e once at
the end, a smoke run against the integrated change), each line in the normalized shape
check → result as a bullet list, or the honest not verified. Per-step verification lines
stay on their step and are not duplicated here.Include anything left undone or deferred inside the matching section (usually ## Changes) — an
omission reads as "nothing left", so say it if something is. Use **bold**, lists, and code
where they aid scanning. The per-item summary renders as Markdown too — a tight sentence or two,
bulleted only when it genuinely has parts. Keep every surface scannable, never a wall of text.
Fix requests re-open the SAME item. When the user asks for a fix on a reviewed step (you'll
receive the original step, its summary, its change set, and their feedback), flip that exact item
(by id) back to in_progress, make the fix, and mark it done with a fresh summary and a
fresh commitSubject describing the fix — the fix, not the original work (the user re-reviews
only the new delta, and the revision lands as its own commit). Re-opening clears the previous
values, so supply both again. Never open a new item for a fix — the revision must attach to the step
it revises.