Skills

A skill is a packaged bundle of instructions — a SKILL.md plus any supporting files — that an agent can follow while it works. The catalog holds two kinds of entry: skills that ship with CodeHerder itself, and skills your own workspace has written. Either way, you decide which ones apply to your work.

This is a different thing from an agent’s capability tags, which describe what an agent can do for fleet placement. A skill is a set of instructions; a capability tag is a label used to match agents to tasks.

Finding the catalog

From the web app: open Set up → Skills. Every member of the workspace can see this page — reading the catalog doesn’t require any special role.

From the CLI: ch skill list.

Before you turn a skill on, it’s worth reading it — a skill is instructions an agent will actually follow, so it’s worth knowing what you’re switching on. Click a skill’s row to open its own page: its metadata alongside its files, with the file list on the left and the selected file’s contents on the right. That view is read-only unless it’s a skill your own workspace defined and you’re an owner or admin, in which case the same page is the editor. For a built-in skill you can also read it from the CLI with ch skill show <slug> — that command only reaches the shipped catalog, though, so it won’t find a skill your workspace or a parent group wrote. Open one of those in the web app instead.

Source and Selection — two questions, two columns

The catalog list shows two columns, and they answer two different questions:

• Source — who may edit this skill’s definition. One of Built-in (ships with CodeHerder), This workspace, or Inherited from <group>.
• Selection — where your workspace’s on/off choice for it came from. One of Set here, Inherited from <group>, or Default (on) / Default (off) when nobody in the chain has made a choice.

These disagree all the time, and that’s normal — a built-in skill you’ve switched on for your own workspace is Source Built-in, Selection Set here. A group’s Selection choice applies to every workspace beneath it; a workspace’s own choice always wins over its group’s, including turning a skill off that the group turned on. See Managing workspaces for how groups and their descendants fit together.

One CLI gotcha worth knowing: ch skill list’s SOURCE column is the Selection axis above, not the web app’s Source column, and the CLI doesn’t show ownership at all.

Turning a skill on or off

From the web app: click Enable or Disable on the skill’s row. Once your workspace has made its own choice, a Reset selection button appears — it clears your workspace’s choice and returns the skill to whatever it inherits (a parent group’s choice, or the catalog default if there’s no group choice either).

From the CLI:

ch skill enable <slug>
ch skill disable <slug>
ch skill reset <slug>

These commands act on the workspace set by your CH_WORKSPACE_ID environment variable — see Agents and the CLI for getting ch set up. Use reset, not “unset,” “revert,” or “clear” — it’s the one word CodeHerder uses everywhere for this action.

Writing your own skill

Click New skill on the Skills page to open the workbench: a file list on the left, with an Add file action, a running count of how many files you’ve added out of the 64-file limit, and a meter for the skill’s total size; an editor pane on the right shows whichever file is selected.

SKILL.md is always the first file, and it can’t be removed or renamed — it’s the one file every skill needs. Its frontmatter is the only place a skill’s name, description, and version live: the Slug, Description, and Version fields above the file list read and write that frontmatter directly, so typing a slug keeps SKILL.md’s name: field in step. Description is required.

A checkbox, Enable in this workspace now, turns the skill on for your workspace as part of creating it — it takes effect at the next session the same as any other enable.

A skill has to stay within these limits:

• Slug: 2–64 characters, lowercase letters, numbers, and hyphens, starting with a letter or a number.
• Up to 64 files, including SKILL.md.
• 256 KB per file, 512 KB total per skill.
• File extensions: .md, .txt, .json, .yaml, .yml, .csv.
• Paths are relative and slash-separated, with no .. segments.

A new slug has to be unique across your whole workspace tree — it can’t already belong to a built-in skill, one defined on a parent group, one already in your workspace, or one in a descendant workspace. So a workspace can never shadow a skill it inherits.

Writing, editing, and deleting a skill only happens in the web app. ch skill reads the catalog and switches skills on and off — list, show, enable, disable, and reset — and has no command that creates, edits, or deletes one.

Editing, renaming, and deleting

Only a skill your workspace defined is editable from that workspace’s page — an inherited one opens read-only, with a note on which workspace to go edit it in.

The slug is a skill’s identity and can’t be changed once it’s created; to rename one, delete it and create it again under the new slug. If you navigate away from the editor with unsaved changes, CodeHerder asks you to confirm first.

Delete removes the skill’s definition and files, along with every workspace’s enable/disable choice for it, behind a typed confirmation. A session spawned after the delete simply doesn’t get it; a session that’s already running is unaffected. Only a skill your workspace owns can be deleted.

Starting from a skill that already exists

A built-in or inherited skill’s page has a Duplicate to this workspace button (visible to an owner or admin). It opens the create form pre-filled with that skill’s files, under a slug like <slug>-copy that you’re free to change before saving.

Skills owned by a group

A skill can also be owned by a group rather than a single workspace — the same way devices, repositories, and agents can be. When it is, every workspace nested beneath that group can see it in the catalog and enable it for itself, and only the group can edit or delete it. See Managing workspaces for how groups and the workspaces beneath them relate.

Who can change what

Creating, editing, deleting, enabling, disabling, and resetting all need a workspace owner or admin, and a human token — an agent’s own token can’t change workspace settings, so an agent can’t do any of this for itself. Everyone else sees the same pages read-only, and reading the catalog only needs regular membership.

What happens after you turn one on

It takes effect on the next session, not the one running now. A session that’s already in flight keeps whatever it started with — turning a skill on or off doesn’t reach back into work that’s already underway. This is the same whether the skill is one you wrote or one that ships with CodeHerder; delivery doesn’t care where a skill came from.

When a new session starts, CodeHerder puts the skill’s files into that session’s working copy and points the agent at them, in whichever way its CLI expects — usually by linking them into the folder that CLI reads its skills from, so the agent can use the skill the same way it would use one already checked into the repo. Every coding CLI CodeHerder can launch for a task gets this treatment; see the harness table on Agents and the CLI for the full list.

Your own copy always wins: if your repo already has a folder with the same name as the skill, CodeHerder leaves it exactly as it is and doesn’t deliver the catalog copy on top of it. Nothing in your repo is ever overwritten.

Nothing about this is committed. The delivered files are excluded from git in that clone, so they never show up in git status and never end up in a commit or a merge request.

Turning a skill off works the same way in reverse: on the next session, CodeHerder removes what it had delivered — again, not retroactively into a session that’s already running.

Two limits worth knowing:

• Only task sessions get skills. An interactive dev session doesn’t go through this delivery step, so it never gets a Skills section either.
• A device needs a current release to deliver anything. An older release doesn’t inject skills at all, and a session run on it shows no Skills section on its page. Devices update themselves automatically by default, so this only shows up on a device that’s stuck.

Checking that a skill reached a session

Open a task session’s page and look for the Skills section, below the session summary. It lists every skill that was enabled for the workspace at spawn time, each with an outcome:

• linked — linked into the agent’s skills folder for this session.
• already there — it was already linked there; nothing to do.
• copied — copied instead of linked, because that device’s filesystem doesn’t support linking.
• skipped — your repo already has its own folder with that name, so CodeHerder left it alone. This is the same “your own copy always wins” rule above, not a bug.
• removed — the skill is no longer enabled, so CodeHerder removed the copy it had previously delivered.

Alongside the per-skill list, a counter row totals how many skills were enabled, linked, already linked, copied, skipped, and removed for that session.

If the section says no skills are enabled for the workspace, follow its link to turn some on. If it says CodeHerder doesn’t know a skills folder for the agent’s CLI, that session was launched with a raw command CodeHerder doesn’t recognize as one of the supported CLIs, so it can’t tell where that CLI keeps its skills — nothing was injected. A pi session shows only the counter row with no per-skill list, since pi is handed its skills bundle directly rather than through a folder to link into.

Related guides

• Managing workspaces — groups, nesting, and how a group’s settings reach the workspaces beneath it.
• Agents and the CLI — set up ch, including CH_WORKSPACE_ID.
• Shaping how an agent works — personas and system prompts — the other way to shape agent behavior, per-agent rather than per-workspace.
• Workspace memory — the other shared, inherited store your workspace keeps.