---
title: task-format skill — design
type: concept
updated: 2026-06-11
---

# task-format skill — design

## Why it exists

The autonomous poller (agents-task-runner) reads each project's `.tasks/STATUS.md` and decides what to claim, how to route it, and whom to notify. Those decisions hang on a handful of fields — most critically `**Weight:**` and `**Notify:**`. The formatting rules for those fields lived only in internal sources: the parser (`projects-meta-mcp/src/lib/status-md.ts`), the writer (`status-md-writer.ts`), and the ops runbook (`.common/.wiki/concepts/agents-task-runner-ops.md`).

The wiki is internal; **skills ship with `factory` to external users**. An external operator pointing the poller at their own board has no access to the wiki or the MCP source — so the on-disk task-block format had no public, copy-pasteable reference. `task-format` is that reference.

## Scope — and why it's a separate skill

Three adjacent skills, deliberately not merged:

- **`delegate-task`** — workflow for creating a task for *another* project/agent via `mcp__projects-meta__tasks_create`. The tool emits the field format for you; the skill is the pre-flight gate + body template.
- **`using-tasks`** — policy for *working* an existing board (claim / switch / close / per-task files).
- **`task-format`** (this skill) — the **byte-level field format** the poller parses, for *hand-edited* STATUS.md blocks and for understanding what `tasks_create` produces.

A hand-edit scenario triggers none of the other two: `delegate-task` is about the MCP tool, `using-tasks` is about board mechanics, neither documents the exact header regex / Weight vocabulary / Notify line. Hence a focused reference skill.

## Ground truth (sources of record)

- Header regex `TASK_HEADER = /^##\s+(\S+)\s+\[([^\]]+)\]\s+—\s+(.+)$/u` and all `**Field:**` regexes — `status-md.ts`.
- Canonical field order and the writer — `status-md-writer.ts` (`formatTaskBlock`).
- Claim gate: only `weight === 'needs-human'` is excluded at claim; capability/runtime gates — `claim.ts` `selectClaimableTask`.
- **Missing-Weight behavior:** the claim gate does *not* reject a weightless task, but the fleet router (`fleet-router.js` `resolveBackend`) finds no backend for an `undefined` tier, so the poller parks it to 🔵 blocked (`no backend for weight_tier: unknown`) and inboxes Notify. Net effect — confirmed by source, not folklore — a task without Weight does not run. The skill states this as the operative rule.
- Notify resolution + inbox write — `crossProjectAgentPoller.js` `makeInboxWriter`.

## TDD record (per `superpowers:writing-skills`)

**RED** — 3 baseline subagents, no skill, asked to author a poller-claimable STATUS.md block (ordinary work ×2, critical-infra ×1). Failures: 2/3 used `### `/bullet-list headers the parser cannot recognize as a task at all; 2/3 omitted `**Weight:**` entirely (invented `risk: low`, `tier: L`, `claimable-by`); 2/3 put the notification in prose instead of a `**Notify:**` field; 1/3 used 🟢 (done) for a ready task. The one partial success only got Weight/Notify right because it *read the board* and found the spec — a crib an external user lacks.

**GREEN** — 2 fresh subagents with the skill loaded, same scenarios. Both produced parser-valid blocks: correct `## ⚪ [slug] —` header, `**Field:**` lines, `**Weight:**` + `**Notify:**`. The critical-infra agent correctly chose `**Weight:** needs-human` in canonical vocabulary (baseline had invented `tier: L` / `auto: ❌`).

**REFACTOR** — no new format loopholes surfaced; the skill maps every documented RED failure to a Common-mistakes row.

## Decisions

- **Version 0.1.0** — new skill; project-discipline Rule 3 first-version clause (matches `delegate-task` starting at 0.x).
- **Reference skill, ~900 words** — exceeds the <500 word target for frequently-loaded skills, justified: it loads only when authoring/editing a task block, and a field reference needs the full table to be useful.
- The `needs-human` critical-infra list mirrors `delegate-task` pre-flight Q0 and the ops runbook's "Critical-infra защита" — kept consistent on purpose.