Guide · Agent skill

How to use the TaskFlow Job Orchestration agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

TaskFlow is an agent skill for building background jobs that span several detached tasks, such as sub-agent or ACP runs, while still behaving like one job with a single owner session. This guide explains what the skill makes the agent do, how to install it, how to trigger it with natural requests, and what it needs to run. By the end you will know when TaskFlow fits your work and how its core lifecycle of create, run, wait, resume and finish fits together.

TaskFlow Job Orchestrationspinabot/brigade · MIT Download the skill

Quick start

1Download the skill. Download the ZIP for skills/taskflow from the spinabot/brigade listing on this page.
2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
3Confirm your runtime. Make sure your environment exposes api.runtime.tasks.flow and that you have trusted tool context with sessionKey or a binding layer that resolves the session.
4Create a managed flow. Bind to the session and call createManaged with a controllerId, goal, currentStep and initial stateJson.
5Link child tasks. Use runTask to attach detached ACP or subagent work to the flow, and check the created flag before continuing.
6Wait, resume and finish. Call setWaiting with an expectedRevision when waiting on a person or system, resume when work can continue, and finish or fail at the end, carrying the latest revision each time.

What the TaskFlow skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions that the agent reads when a task matches the skill's description. The taskflow skill is about durable job structure. It tracks a flow's identity, its owner session and requester origin, its current step, a small persisted state bag, waiting status, linked child tasks, and revision numbers so that updates are conflict-safe and the job can survive restarts.

TaskFlow deliberately does not contain branching or business logic. That stays in the calling code or in an authoring layer such as Lobster or acpx. Use it when a job needs to outlive one prompt or one detached run but should still report back to one place.

Multi-step background work with one owner
Work that waits on detached ACP or subagent tasks
Jobs that need small persisted state between steps
Plugin or tool work that must survive restarts and revision conflicts

Install the TaskFlow skill

Download the ZIP for skills/taskflow from the spinabot/brigade listing on this page. Unzip it into your personal skills folder at ~/.claude/skills/ so it is available in every project, or into a project's .claude/skills/ folder so it applies only to that project.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into the project's .claude/skills/
Claude apps: Settings → Capabilities → Skills, then upload

Know what you need before using it

TaskFlow is an API reference for code that runs against a specific plugin runtime. It is not a standalone automation tool. The skill expects a runtime that exposes api.runtime.tasks.flow, which is the Brigade plugin/runtime environment. You also need either trusted tool context that includes a sessionKey, or a binding layer that resolves session and delivery context.

The example workflows reference Lobster files and a separate taskflow-inbox-triage skill. Those are not included in the reviewed files, so you will need to obtain them separately if you want to follow those examples.

A runtime exposing api.runtime.tasks.flow
Trusted tool context with sessionKey, or a binding layer resolving session and delivery context
Optional: Lobster examples and taskflow-inbox-triage, which are not in the reviewed files

Create and run a managed flow

Use a managed flow when your code owns the orchestration. Bind to the session first, create the flow, then link child work with runTask so the child task is attached to the flow instead of being created on its own. The canonical entry point is api.runtime.tasks.flow; api.runtime.taskFlow still exists as an alias.

Every mutating call after creation is revision-checked. Carry the latest flow.revision forward after each successful mutation, and check the applied or created flag on each result before continuing.

Bind with fromToolContext(ctx) when you have trusted tool context with sessionKey
Bind with bindSession({ sessionKey, requesterOrigin }) when your binding layer already resolved the session
Lifecycle: createManaged, runTask, setWaiting, resume, finish or fail, and requestCancel or cancel

const taskFlow = api.runtime.tasks.flow.fromToolContext(ctx);

const created = taskFlow.createManaged({
  controllerId: "my-plugin/inbox-triage",
  goal: "triage inbox",
  currentStep: "classify",
  stateJson: {
    businessThreads: [],
    personalItems: [],
    eodSummary: [],
  },
});

const classify = taskFlow.runTask({
  flowId: created.flowId,
  runtime: "acp",
  childSessionKey: "agent:main:subagent:classifier",
  runId: "inbox-classify-1",
  task: "Classify inbox messages",
  status: "running",
  startedAt: Date.now(),
  lastEventAt: Date.now(),
});

if (!classify.created) {
  throw new Error(classify.reason);
}

const waiting = taskFlow.setWaiting({
  flowId: created.flowId,
  expectedRevision: created.revision,
  currentStep: "await_business_reply",
  stateJson: {
    businessThreads: ["slack:thread-1"],
    personalItems: [],
    eodSummary: [],
  },
  waitJson: {
    kind: "reply",
    channel: "slack",
    threadKey: "slack:thread-1",
  },
});

if (!waiting.applied) {
  throw new Error(waiting.code);
}

const resumed = taskFlow.resume({
  flowId: waiting.flow.flowId,
  expectedRevision: waiting.flow.revision,
  status: "running",
  currentStep: "finalize",
  stateJson: waiting.flow.stateJson,
});

if (!resumed.applied) {
  throw new Error(resumed.code);
}

taskFlow.finish({
  flowId: resumed.flow.flowId,
  expectedRevision: resumed.flow.revision,
  stateJson: resumed.flow.stateJson,
});

Trigger the skill with natural requests

The skill loads when a request matches its description. Ask for work that spans several steps, waits on something, or has to report back to one owner. Phrase requests around the job rather than the API, for example asking the agent to triage an inbox in stages and send one summary at the end, or to hold a job until a Slack reply comes in and then finish it.

Keep conditional decisions in your own code or authoring layer. The skill's pattern routes items to buckets such as business, personal and later, and TaskFlow only stores the state for those buckets.

"Triage my inbox in the background and give me one summary when it is done"
"Start a job that waits for a Slack reply on this thread, then finalises the summary"
"Run these classification sub-agents and report back to me once they all finish"

Safety notes: scripts and network

The skill's metadata states that it runs no scripts and uses no network access. It consists of a single SKILL.md file. Its behaviour is determined by the plugin runtime you connect it to, so review the code you write against that runtime, including any Slack or other channel integrations your flow calls.

Keep the state you persist small. The skill recommends storing only the minimum needed to resume, and putting human-readable wait reasons in blockedSummary or structured wait metadata in waitJson.

Scripts: none included
Network: none used by the skill itself
Persist only the minimum state needed to resume
Review the integrations your own code calls through the runtime

Tips for reliable flows

Always use the revision from the most recent successful result. A stale expectedRevision is what makes a mutation fail safely, so refetch or carry forward the returned flow rather than reusing an old value.

Use getTaskSummary(flowId) when the orchestrator needs a compact health view of child work. Use requestCancel when you want the flow to stop scheduling immediately, and cancel when you also want active linked child tasks cancelled.

Carry forward flow.revision after every successful mutation
Use getTaskSummary(flowId) for a compact view of child work
requestCancel stops scheduling; cancel also cancels active linked child tasks
Use runTask rather than creating detached tasks yourself when you want parent orchestration

What people use it for

Triaging an inbox in the background, with classification done by sub-agents and one summary sent to the owner
Holding a job at a waiting state until a Slack reply arrives, then resuming to finalise
Coordinating several detached ACP or subagent runs that must all report to one owner session
Building a plugin that runs a multi-step workflow and survives restarts without losing its place

Frequently asked questions

How do I install the TaskFlow agent skill?

Download the ZIP for skills/taskflow from the spinabot/brigade listing, then unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

Is TaskFlow free to use?

The skill is released under the MIT licence, as stated on its listing. The source does not mention pricing, so check the listing and your own runtime for any costs beyond the skill itself.

What do I need to run TaskFlow?

You need a runtime that exposes api.runtime.tasks.flow, plus either trusted tool context with a sessionKey or a binding layer that resolves session and delivery context. The example Lobster files and the taskflow-inbox-triage skill are not included in the reviewed files.

Does TaskFlow run scripts or use the network?

According to its listing, the skill runs no scripts and uses no network. It is a single SKILL.md file, so any network activity comes from the code and runtime you build around it.

How does TaskFlow compare to Lobster or acpx?

TaskFlow stores flow identity, state, waiting status and child-task links, but it does not hold branching or business logic. Lobster and acpx are authoring layers that sit above it, and your own calling code can also be the authoring layer.

When should I not use TaskFlow?

Skip it for simple one-shot prompts or single tasks that do not need persisted state or resumption, since the overhead is not useful there. It is also not a ready-made end-user automation, because it is an API reference for code running against a specific plugin runtime.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

TaskFlow is a good fit for plugin and tool developers who need multi-step background jobs with durable state, waiting and resumption, and detached sub-agent or ACP runs reporting to one owner. It is not suited to one-off prompts or to people who want a ready-made automation without writing code. If you are not building against the Brigade plugin runtime, it will not be useful on its own.

Download the skill