claude-code-tasks

What this skill does

# Claude Code Tasks Reference

This skill is a shared reference for Claude Code's 6 Task Management tools. Load it when your skill or agent needs to create, manage, or coordinate tasks.

The tools serve two distinct purposes:

- **Structured tracking** — TaskCreate, TaskGet, TaskList, TaskUpdate — for organizing work items, tracking progress, managing dependencies, and coordinating agents
- **Background execution** — TaskOutput, TaskStop — for monitoring and controlling background processes (shells, agents, remote sessions)

Both share the task ID namespace but serve different operational needs.

This reference covers:
- Complete tool parameter tables for all six Task tools
- Status lifecycle, transition rules, and completion rules
- Naming conventions (subject vs. activeForm)
- Dependency management with DAG design principles
- Metadata conventions for categorization and tracking

For deeper content, load the reference files listed at the end of this document.

---

## TaskCreate

Creates a new task. Returns the created task object with a system-assigned `id`.

Use TaskCreate for complex multi-step tasks (3+ distinct steps), plan mode tracking, or when the user provides multiple tasks or requests a todo list. Skip it for single straightforward tasks or trivial work completable in under 3 steps.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subject` | string | Yes | Short imperative title for the task (e.g., "Create user schema"). Displayed in the task list UI. |
| `description` | string | Yes | Detailed description including context and acceptance criteria. Supports markdown. |
| `activeForm` | string | No | Present-continuous description shown while the task is in progress (e.g., "Creating user schema"). Displayed in the task list UI during execution. Falls back to `subject` if omitted. |
| `metadata` | object | No | Key-value pairs for categorization and tracking. Keys and values are strings. Common keys documented in the Metadata Conventions section below. |

### Behavior

- All tasks are created with status `pending`
- No owner is assigned at creation — use TaskUpdate to assign
- Use TaskUpdate after creation to set up dependencies (`blocks`/`blockedBy`)

### Return Value

Returns the full task object including:
- `id` — System-assigned unique identifier
- `subject` — The subject provided
- `description` — The description provided
- `activeForm` — The activeForm provided (if any)
- `status` — Always `pending` for newly created tasks
- `metadata` — The metadata provided (if any)
- `blockedBy` — Empty array (no dependencies yet)
- `blocks` — Empty array (no dependents yet)

### Example

```
TaskCreate:
  subject: "Create user authentication module"
  description: "Implement JWT-based auth with login, logout, and token refresh endpoints."
  activeForm: "Creating user authentication module"
  metadata:
    priority: "high"
    complexity: "medium"
    task_group: "user-auth"
```

---

## TaskGet

Retrieves a single task by its ID. Use this to get full task details including description, metadata, and dependency information.

Use TaskGet before starting work on a task to get the full description with acceptance criteria. Also use it to verify the `blockedBy` list is empty before beginning work, and to read the latest state before calling TaskUpdate (staleness check). Use TaskList first for an overview, then TaskGet for full details on a specific task.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `taskId` | string | Yes | The ID of the task to retrieve. |

### Return Value

Returns the full task object:
- `id` — Task identifier
- `subject` — Task title
- `description` — Full description (may be long)
- `activeForm` — Present-continuous form (if set)
- `status` — Current status (`pending`, `in_progress`, `completed`, `deleted`)
- `metadata` — Key-value pairs
- `blockedBy` — Array of task IDs this task depends on
- `blocks` — Array of task IDs that depend on this task
- `owner` — The agent or session that owns this task (if set)

---

## TaskUpdate

Updates an existing task. Only the fields you provide are changed; omitted fields remain unchanged.

Always read the latest state via TaskGet before updating to avoid acting on stale data.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `taskId` | string | Yes | The ID of the task to update. |
| `status` | string | No | New status. Valid values: `pending`, `in_progress`, `completed`, `deleted`. See Status Lifecycle below. |
| `subject` | string | No | Updated subject line. |
| `description` | string | No | Updated description. |
| `activeForm` | string | No | Updated present-continuous description. |
| `owner` | string | No | Set or change the task owner (agent name or session identifier). |
| `metadata` | object | No | Metadata keys to merge with existing metadata. Set a key to `null` to delete it. |
| `addBlocks` | string[] | No | Add task IDs to this task's `blocks` list (tasks that depend on this one). |
| `addBlockedBy` | string[] | No | Add task IDs to this task's `blockedBy` list (tasks this one depends on). |

### Return Value

Returns the updated task object with all current fields.

### Example

```
TaskUpdate:
  taskId: "5"
  status: "in_progress"
  activeForm: "Implementing user authentication module"
```

---

## TaskList

Lists all tasks in the current task list. Takes no parameters.

Use TaskList to see available work (pending, unblocked tasks), check overall progress, or find the next task after completing one. For teammate workflows: call TaskList, find tasks with `pending` status and empty `blockedBy`, prefer the highest-priority unblocked task, then claim it via TaskUpdate.

### Parameters

None.

### Return Value

Returns an array of task summary objects. Each summary includes:
- `id` — Task identifier
- `subject` — Task title
- `status` — Current status
- `owner` — Agent ID if assigned, empty if available
- `blockedBy` — Array of blocking task IDs
- `blocks` — Array of dependent task IDs
- `metadata` — Key-value pairs

Note: TaskList returns summary objects. Use TaskGet to retrieve the full `description` for a specific task.

---

## TaskOutput

Retrieves output from a running or completed background task. Works with background shells, async agents, and remote sessions.

Use TaskOutput to check on background task progress, retrieve results from completed background work, or monitor long-running operations.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `task_id` | string | Yes | — | The task ID to get output from. |
| `block` | boolean | Yes | `true` | Whether to wait for task completion before returning. |
| `timeout` | number | Yes | `30000` | Maximum wait time in milliseconds. Range: 0–600000 (0–10 minutes). |

### Behavior

- **`block: true`** — Waits for the task to finish (up to `timeout` ms), then returns the output. Use this when you need the result before proceeding.
- **`block: false`** — Returns immediately with current status and any available output. Use this for progress checks without blocking.

---

## TaskStop

Terminates a running background task.

Use TaskStop to cancel a long-running task that is no longer needed or to force-terminate a background process (e.g., a timed-out executor agent).

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | No | The ID of the background task to stop. |
| `shell_id` | string | No | **Deprecated** — use `task_id` instead. |

### Return Value

Returns success or failure status of the stop operation.

---

## Status Lifecycle

Tasks follow a three-state lifecycle with an additional terminal state.

```
┌──────────┐    TaskUpdate     ┌─────────────┐    TaskUpdate     ┌───────────┐
│