Capabilities

The word “capability” shows up in several places in CodeHerder — on agents, on launch configs, on workflow stages, and on tasks and schedules — and it means something slightly different, with different rules, in each one. This page is the single place to check which rule applies where.

What a capability is

A capability is a short, free-form label string. You choose the labels to match your own conventions — common examples are go, frontend, or op.review. One convention is built in: model:<tier>, where the tier is haiku, sonnet, or opus, in increasing order of capability and cost. Use model:<tier> labels to describe which AI model an agent should run, and plain skill labels for anything else you want to track. For the rest of the model story — naming an exact model, restricting a config to an Allowed models list, and cost-aware routing — see Which model your agents run.

The two questions capabilities answer

Every place capabilities appear is answering one of two questions:

• What can this agent do? — a capability declared on an agent or a launch config, describing a skill it carries.
• What does this work need? — a capability declared on a task, a schedule, or a workflow stage, describing a requirement.

The rule that matters is this: skills only ever rank, and only launch-config and stage requirements can block. The sections below walk through each place in turn; the table at the end summarizes all of them.

Agent skill labels — soft

Set with ch agent create --cap <label> (repeat the flag for more than one), or edit afterward. These are the skill labels shown on the agent’s template.

ch agent create --display-name "Go coder" --cap model:sonnet --cap go

When the engine auto-staffs an unassigned task, it ranks available agents by how much their skill labels overlap with the task’s required capabilities — more overlap means higher priority. A partial or even zero overlap never blocks placement: the task still runs on the best available agent, even a plain skill miss. Skill labels are a ranking signal only.

Launch-config capabilities — hard

Set with ch agent config set <agent-id> --cap <label> (or ch agent config add for an additional config). This is a different set of labels, stored on the agent’s launch config, not the template. config set replaces the config’s capability list rather than adding to it, so include every capability you want the config to keep on each call:

ch agent config set <agent-id> --harness claude --cap model:opus --cap model:sonnet

The engine runs a workflow stage only on a launch config whose capabilities fully cover what that stage requires. If no launch config in your workspace carries a capability a stage requires, that stage is unstaffable — any task reaching it queues indefinitely, with no agent ever picking it up. This is a hard gate, not a preference.

Covering a whole workflow. Different stages of a workflow can require different capabilities — the built-in feature, story, and bug types need both the model:opus and model:sonnet tiers across their stages. A single launch config needs every tier the workflow uses to carry a task through it end to end; split across configs (one per tier) works too, since the engine picks whichever enabled config covers a given stage. See Agents and the CLI for the setup walkthrough.

For the full walkthrough of launch configs — including multiple configs per agent and how the engine picks between them — see Agents and the CLI.

Stage required capabilities — hard

Set from Settings → Task types, on each stage’s settings panel. A stage’s required capabilities are the list a launch config must fully cover before the engine will run that stage on it — the other side of the launch-config gate above. See Customising task types and workflows for how to view and edit a stage’s required capabilities.

Task and schedule required capabilities — soft

Set with ch task create --cap <label> or ch schedule create --cap <label> (repeat for more than one). These describe what the task or the tasks a schedule creates would ideally need.

ch task create --title "Write Go migration" --type story --cap go --cap model:opus

Like agent skill labels, this is a ranking signal, not a gate: the engine ranks candidate agents by how many of these capabilities their skill labels cover, and prioritizes higher overlap — it never refuses to place the task for lack of a match. See Writing tasks an agent can build for the rest of task creation.

Soft vs. hard, at a glance

Where it’s set	Command	Effect
Agent template	ch agent create --cap <label>	Soft — ranks agents during auto-staffing; never blocks
Launch config	ch agent config set <agent-id> --cap <label>	Hard — a stage only runs on a config whose caps cover its requirements
Workflow stage	Settings → Task types, per-stage settings	Hard — the requirement side of the launch-config gate above
Task / schedule	ch task create --cap <label> / ch schedule create --cap <label>	Soft — ranks candidate agents; never blocks

Setting a required capability on a task, or on a launch config, needs the Starter plan — skill labels are free on every plan. See Plans and limits.

When capabilities stall a task

A task that queues without an agent ever picking it up is usually a stage’s required capabilities going uncovered by any launch config. The web app’s Capability gap callout on the Set up → Agents page gives an early warning, but it checks agent templates’ skill labels, not launch configs — since the two are set independently, a template can carry a label its launch config doesn’t, or vice versa, so the callout can occasionally miss a real gap or flag one that’s already closed. Always confirm against the launch config, not just the callout.

For the full diagnostic walkthrough, see Why isn’t my task moving?; for reading the Capability gap callout itself, see Monitoring your agents.

Related guides

• Agents and the CLI — creating agents, launch configs, and how the engine selects between them
• Which model your agents run — naming an exact model, Allowed models, and cost-aware routing
• Customising task types and workflows — setting a stage’s required capabilities
• Writing tasks an agent can build — setting a task’s required capabilities
• Monitoring your agents — reading the Capability gap callout
• Why isn’t my task moving? — diagnosing a task stuck on a capability mismatch
• Core concepts — the full object model