From work-session-tools
This skill should be used when the user asks to "track tasks", "create a todo list", "manage background tasks", "use TaskCreate", "orchestrate agents", "run tasks in parallel", "break this into tasks", "track progress", "create a checklist", "plan steps", "divide work into subtasks", or when working on multi-step tasks. Also activates when the user mentions TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, or TaskStop.
How this skill is triggered — by the user, by Claude, or both
Slash command
/work-session-tools:task-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use native task tools to track work, manage dependencies, and orchestrate background agents.
Use native task tools to track work, manage dependencies, and orchestrate background agents.
Create a task list when:
Skip task tools when:
| Tool | Purpose | Key Fields |
|---|---|---|
| TaskCreate | Create a task | subject (imperative), description, activeForm (spinner text) |
| TaskGet | Fetch full task details | taskId — returns description, metadata, dependencies |
| TaskList | List all tasks (summary only) | Returns id, subject, status, owner, blockedBy |
| TaskUpdate | Update status or dependencies | taskId, status, addBlockedBy, addBlocks, owner, metadata |
| TaskOutput | Read output from background task | task_id, block (true/false), timeout |
| TaskStop | Stop a running background task | task_id |
Note: TaskCreate/Get/List/Update use
taskId(camelCase). TaskOutput and TaskStop usetask_id(snake_case).
Status flows in one direction:
pending → in_progress → completed
in_progress before starting work on a taskcompleted only after work is fully done and validateddeleted to permanently remove a task that is no longer neededfailed status — if blocked, keep as in_progress and create a new task describing the blockerWrite in imperative form — a brief, actionable title:
Present continuous form displayed in the spinner while in_progress:
Keep descriptions concise (50-100 words). Include:
For large plans, reference external files instead of inline descriptions:
See docs/plan-auth.md for full implementation details
Chain tasks using addBlockedBy and addBlocks:
TaskCreate: "Write unit tests" → task #1
TaskCreate: "Run test suite" → task #2
TaskUpdate: taskId #2, addBlockedBy: ["1"]
Task #2 cannot start until task #1 is completed. After completing task #1, check TaskList to find newly unblocked tasks.
Launch agents in the background using the Agent tool with run_in_background: true:
Agent(
description: "Run linting checks",
prompt: "Run ruff check on the src/ directory and report results",
run_in_background: true
)
After launching, continue other work. To check manually before the completion notification:
TaskOutput(task_id: "<agent-id>", block: false, timeout: 5000)
To stop a background agent that is no longer needed:
TaskStop(task_id: "<agent-id>")
Launch multiple independent agents simultaneously:
# In a single message, launch all independent agents:
Agent(description: "Run tests", prompt: "...", run_in_background: true)
Agent(description: "Lint codebase", prompt: "...", run_in_background: true)
Agent(description: "Check types", prompt: "...", run_in_background: true)
Each agent runs in its own context window, consuming no parent context budget.
| Need | Agent Type |
|---|---|
| Read-only codebase search | Explore |
| Implementation strategy | Plan |
| Multi-step coding or research | general-purpose |
| Specific domain task | Named subagent (e.g., test-runner) |
Match model to complexity:
haiku — simple searches, repetitive taskssonnet — code generation, complex tasks (default)opus — critical decisions, complex reasoningTaskList returns summary fields only: id, subject, status, owner, blockedBy.
To access description, metadata, or activeForm, make an explicit TaskGet(taskId) call. This is by design to prevent context bloat — 20 tasks in TaskList costs 1 call, but full details would cost 21 calls.
Mitigation: Embed critical info in the subject field (always visible in TaskList) and keep descriptions concise.
Attach structured metadata to tasks for richer tracking:
TaskUpdate(taskId: "1", metadata: {
"priority": "high",
"files": ["src/auth.ts", "tests/auth.test.ts"],
"estimated_duration": "30m"
})
Set a metadata key to null to remove it.
| Anti-Pattern | Fix |
|---|---|
| Marking complete without validation | Run tests/checks first, then set completed |
| Assuming description visible in TaskList | Use TaskGet per task when details needed |
| Deeply nested task hierarchies | Flatten — use blockedBy for sequencing |
| Huge inline descriptions | Reference external plan files |
| Blocking main session for slow agents | Use run_in_background: true |
| Polling background tasks in a loop | Wait for notification, or use TaskOutput with block: true |
For detailed orchestration patterns, see references/orchestration-patterns.md.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub alex-kopylov/zweihander --plugin work-session-tools