Which skills a stage gets

Skills covers the workspace-wide catalog: which skills exist, and which ones your workspace has switched on. That’s the default every session starts from. But a workflow stage can go further and pick a smaller set for itself — so a code stage that only ever needs your linting skill isn’t also handed a deploy runbook meant for verify.

What a selection does

A stage in a workflow’s pipeline can carry its own list of skill slugs. When it does, a session that runs at that stage gets only the skills on that list — never more than what your workspace has enabled, only ever less.

• It only narrows. If a stage names a skill your workspace has turned off, that skill is still not injected. A stage selection can never switch on a skill your workspace has switched off.
• No selection means everything enabled. A stage with no skills list — or an empty one — behaves exactly like today: the session gets your workspace’s whole enabled set. Most stages never need to set one.
• A typo or a rename never breaks the session. If a stage names a skill slug that doesn’t match anything in your catalog, that session still starts; the session just doesn’t get that one skill. See Reading the result below for where that shows up.

Where it lives

A skill selection lives on a stage instance — an entry in a workflow’s stage_instances list, alongside that instance’s other settings like class, to, and terminal. It’s the instance’s skills field:

{
  "name": "code",
  "stage": "code",
  "class": "doing",
  "to": ["review"],
  "skills": ["repo-lint-conventions", "release-checklist"]
}

A workflow gets stage instances once its pipeline is composed from the shared stage library — from the CLI, or from Settings → Workflows’s Convert to composition… button on a type that isn’t composed yet. See The stage library for how composing and converting work; this page only covers what one instance’s skills list does once you have one.

Today, changing a selection is a CLI-only edit, using the same show → edit → apply round-trip Customising workflows describes for any schema change:

ch workspace workflow show --json   # every type in the workspace, as JSON
# find the entry whose "typeKey" matches <type>, then copy that entry's
# "schema" object into a file — that's what you edit and pass to --from-file
ch workspace workflow edit <type> --from-file <path>

--type narrows the plain-text view, but show --json always returns every type — filter the output yourself to find the one whose typeKey matches, then edit the “skills” list on the entry you want to narrow, inside stage_instances.

edit replaces the whole schema, so keep everything the captured file already had — every field and every other stage instance — not just the entry you’re changing. The web app’s workflow editor keeps a selection you set this way, but doesn’t have its own control for editing one.

If a task is running under its own workflow override instead of its type’s default, that override’s own stage instances can carry their own selections too — the override is what a session at that stage resolves against.

Limits

A stage’s skills list follows the same slug format as the catalog itself (see Skills), with a few rules of its own:

• Up to 64 slugs per stage instance.
• No duplicate slug within one instance’s list — ch workspace workflow edit rejects a duplicate outright rather than silently collapsing it.
• A slug isn’t checked against your catalog when you save it — only when a session actually starts. That’s why a stale or misspelled slug surfaces later, on the session, rather than blocking the schema edit itself.

Reading the result

Open a task session’s page and look at the Skills section, same as for any session. Alongside the outcomes described in Skills, a stage selection can produce two more:

• Not found — the stage asked for a skill slug with no matching entry in your catalog. Check the slug for a typo or a rename.
• Turned off — the stage asked for a skill your workspace has switched off. This is the narrows-only rule working as intended, not a bug — a stage selection can’t re-enable it.

When the stage carries a skill selection, the counter row at the bottom of the section also shows N selected — how many skills the stage’s own list named, whether or not any of them were actually narrowed out. A session running under no selection (the common case) shows no such count.

Related guides

• Skills — the workspace-wide catalog: finding, enabling, and authoring skills, and every other outcome a session’s Skills panel can show
• Customising workflows — stages, gates, and the flattened schema format
• The stage library — building a pipeline from shared stage instances
• Customising a task’s workflow — giving one task its own pipeline, including its own skill selections