# Which skills a stage gets

How a workflow stage narrows the skills its own sessions get.

Source: https://codeherder.com/docs/stage-skills/

How a workflow stage narrows the skills its own sessions get.

[Skills](https://codeherder.com/docs/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](https://codeherder.com/docs/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](https://codeherder.com/docs/task-types/#manage-workflows-from-the-cli) 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](https://codeherder.com/docs/workflow-overrides/) 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](https://codeherder.com/docs/skills/#writing-your-own-skill)), 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](https://codeherder.com/docs/skills/#checking-that-a-skill-reached-a-session), 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](https://codeherder.com/docs/skills/) — the workspace-wide catalog: finding, enabling, and authoring skills, and every other outcome a session’s Skills panel can show
- [Customising workflows](https://codeherder.com/docs/task-types/) — stages, gates, and the flattened schema format
- [The stage library](https://codeherder.com/docs/stage-library/) — building a pipeline from shared stage instances
- [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/) — giving one task its own pipeline, including its own skill selections