Keep Agent Tasks on Track with a Shared TODO Plan

Where this fits

Imagine asking an agent to "update the pricing page and add a test for the checkout flow." You step away, come back, and have no idea what it did, what is left, or whether it silently dropped one of your requirements. The todos skill solves exactly that: it turns every multi-step request into a live, shared TODO plan scoped to the chat session. You can see the plan, edit it, and reorder work while the agent follows it strictly — no more black-box execution.

Why agents benefit

• Proposes before acting — the agent writes the plan first (todo_write) before asking clarifying questions or starting work, ensuring alignment upfront.
• Strictly ordered execution — tasks are processed in order with exactly one step in in_progress, preventing scope creep and partial work.
• Live status synchronization — every status change (pending → in_progress → done) is reflected immediately, so both user and agent always see the same truth.
• Detects user edits — re-reading the list catches when the user adds, removes, or reorders items; the agent adapts and respects removals without deleting completed history.
• Outcome-focused grouping — each group names a result (e.g., "Fix login redirect") not a process, and each step carries a done-criterion in its note.

Practical scenarios

Multi-file feature implementation

User asks for a new contact form with validation, backend endpoint, and tests. The agent writes a group with steps for each layer, marks the first step in_progress, and works through them sequentially while the user watches progress in the Todo panel.

Research and report generation

For a comparative analysis request, the agent plans steps like "gather sources", "evaluate pricing models", "draft comparison table" — and after the user edits the plan to remove a non‑essential step, the agent re‑reads the list and skips it without complaint.

Debugging with a known fix sequence

A user reports a flaky test. The agent creates a group with steps: "reproduce locally", "identify race condition", "apply fix", "run e2e suite". If the user marks the reproduction step as done manually, the agent notices the status change and moves on, respecting the user's faster analysis.

Add it to your agent workflow

Install the skill in your agent environment:

npx skills add JetBrains/thinkrail --skill todos

After installation, the agent automatically reads the skill's README when a request involves multiple steps. A typical interaction starts with the agent writing a plan via todo_write:

{
  "tool": "todo_write",
  "args": {
    "groups": [
      {
        "title": "Add contact form",
        "items": [
          {"title": "Create form component", "status": "in_progress"},
          {"title": "Add validation logic", "status": "pending"},
          {"title": "Write API endpoint test", "status": "pending"}
        ]
      }
    ]
  }
}

The chat UI shows this as a live checklist; both sides can edit it, and the agent keeps it current as it works.

Compare before adopting

Before adding any agent skill, evaluate:

• Quality signals — check the skill's README for clear behavior contracts and edge-case handling (like "never delete done items").
• Maintenance freshness — look at recent commits and issue activity; a stale skill may miss tool API changes.
• Alternatives — consider built‑in plan tools in your agent framework vs. this chat‑scoped model; todos shines when the user actively edits the plan.
• Workflow fit — does your agent already keep state? This skill works best for conversational sessions where shared visibility is key.

Why it is worth tracking

The todos skill comes from JetBrains' thinkrail repository (65 stars, actively maintained), signaling a pragmatic, developer‑first design. It directly addresses a common pain point — agent autonomy vs. user control — by making the plan a first‑class chat artifact. Keep an eye on it if you build agents that handle multi‑step tasks in interactive environments; its simple model of shared state is a solid pattern to borrow even if you don't adopt the skill directly. For more agent skills and patterns, see OpenAgentSkill.