Skills
What a skill is, how to write, enable, and check one reached a session, and how to read its version history.
A skill is a packaged bundle of instructions — a SKILL.md plus any supporting files —
that an agent can follow while it works. Every skill in your catalog belongs to some
workspace: yours, or a group above it that shares skills down through the hierarchy.
Either way, you decide which ones apply to your work.
The catalog holds three kinds of item: skill, agent and command. An agent is one AGENT.md
file. A command is one COMMAND.md file. An admin can write all three. A
plugin source can also sync them in from a plugin marketplace. This page
says “skill” for all kinds unless it names the kind.
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.
The list has a Kind column and a Kind filter. A synced item shows a Synced badge and links to its plugin source.
From the CLI: ch skill list — it has a KIND column. Add --enabled or --disabled to narrow it
to one state, or --kind skill|agent|command to narrow it to one kind; see Listing enabled and disabled records.
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. The details (slug, definition, selection, version, description) sit at the top.
Below them, the file list is on the left and the selected file’s contents are on the right.
The page is read-only. If your workspace defined the skill and you’re an owner or admin, an
Edit button opens an editing panel on the same page.
You can also read any skill from the CLI with ch skill show <slug> — it resolves the same
way the web app does, so it finds a skill your own workspace wrote or one inherited from a
parent group.
Definition and Selection — two questions, two columns
The catalog list has the columns Skill, Description, Definition, Version, and Selection. Two of them answer different questions:
- Definition — where the skill is defined. It reads This workspace, or the chip Inherited when a group above you defines it. Hover the chip to see the group’s name.
- Selection — where your workspace’s on/off choice for it came from. One of Set here, Inherited choice, or Default (on) / Default (off) when nobody in the chain has made a choice.
These disagree all the time, and that’s normal. Take a skill defined by a group above you that you’ve switched on for your own workspace. Its Definition is Inherited and its Selection is Set here. A group’s 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.
The CLI shows both axes. ch skill show prints an owner row for the definition. In
ch skill list, the SOURCE column is the Selection axis: workspace,
inherited from <name>, or default.
Turning a skill on or off
From the web app: click Enable or Disable on the skill’s row, or in the header of its page. Once your workspace has made its own choice, a Reset button appears. It asks you to confirm, then 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 your current workspace. Pass --workspace <ref> to pick another one.
See Using the CLI for how ch chooses a workspace. Use reset, not
“unset,” “revert,” or “clear” — it’s the one word CodeHerder uses everywhere for this
action.
Enabling a skill can be refused if your workspace’s combined enabled skills would go over their size budget — see The workspace-wide size budget below for what counts and what to do about it.
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 and a file count (the panel notes the 64-file limit), plus a Total size meter that shows the space used out of 512 KB. 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.
- Text file extensions:
.md,.txt,.json,.yaml,.yml,.csv. - Script file extensions:
.sh,.bash,.py,.js,.mjs,.cjs,.ts. - Paths are relative and slash-separated, with no
..segments. - Your workspace’s enabled skills also share a combined 2 MB size budget — see The workspace-wide size budget below.
A new slug has to be unique across your whole workspace tree — it can’t already belong to 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.
From the CLI
You can also keep a skill in a folder in your repository and publish it from CI. Put
SKILL.md and the skill’s other files in one folder. Then run:
ch skill create --from-dir ./skills/samplewriter
The skill’s slug is the name: in SKILL.md. The folder holds every file of the skill.
ch uploads every file in it, including hidden files, and refuses a symbolic link. A new
skill starts disabled. Run ch skill enable <slug> to turn it on.
ch checks the folder with the same rules as the web app: the same file types, the same
size limits, and the same frontmatter rules. A problem names the file at fault, for
example ./skills/samplewriter/run.exe: file type not allowed. When there is a problem,
ch sends nothing.
Add --dry-run to see what would change. It saves nothing. It cannot see a slug that a
descendant workspace already uses. It does not run the malware scan. It does not check the
workspace-wide size budget.
ch skill also works on the .codeherder/skills/ folder of a repository you run local tasks
in. See Project folder.
Editing, renaming, and deleting
Only a skill your workspace defined is editable from your workspace. An inherited skill opens
read-only, with a note: “Defined in <workspace>. Edit it there. This workspace can only
enable or disable it.”
An item that a plugin source synced is read-only, even in the workspace that owns the source. The page shows a Synced badge and names the source. Change the plugin at its source and pin the new commit. Enable, disable and reset still work. Delete the item by removing the source.
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. The new slug starts its own version history from scratch — it doesn’t inherit anything from the one you deleted. The editor keeps a draft as you type. If you leave and come back, it shows “Draft restored from your last visit” with a Discard draft button. See Unsaved changes and drafts.
Delete is on the skill’s row and on its page. It removes the skill’s definition and files, along with every workspace’s enable/disable choice for it. You confirm in a dialog titled “Delete skill” and then press Delete skill. 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. Its retained versions stay readable after the delete — see Version history below.
From the CLI, ch skill edit <slug> --from-dir <folder> replaces all the skill’s files with
the folder’s files. A file that is not in the folder is removed. Add --dry-run to see each
file as added, removed, changed, or unchanged. ch skill delete <slug> deletes the skill. It
asks you to confirm. In CI, add --yes. You cannot undo a delete.
Version history
CodeHerder keeps a full retained history of a skill’s files. Every time a skill is created or edited, it retains the file set as a new version — unless the bytes are identical to a version it already has, in which case it just marks that version current again instead of adding a new one. Turning a skill on or off, resetting a selection, and copying one don’t touch history at all.
That last rule matters for Revert: reverting to an earlier version doesn’t add a new version on top. It makes that earlier version current again. So reverting twice in a row lands you back where you started, and the version count never grows just from going back and forth.
A version has no author — its identity is its content hash, not a person. Each one records its version number, content hash, when it was first retained, and its file count and size.
From the web app: open a skill’s page and its Version history panel lists every retained version, newest first. Compare shows a file-by-file diff between the version you pick and the current one. You can’t pick two older versions. The pair you’re comparing lives in the page’s own address, so you can share a link straight to that diff. Revert sits behind a confirmation and needs an owner or admin — and only works on a skill your own workspace owns. An inherited skill’s panel offers Compare but not Revert.
Speaking of inherited: a skill’s version history belongs to whichever workspace actually owns it, the same as the skill itself. If your workspace enabled a skill from a parent group, its history lives with that group. The panel may note this.
From the CLI: ch skill versions <slug> lists the history, with --limit and --cursor
to page it. Add --version N or --hash <sha256> to read one version in full, files and
all — the two are mutually exclusive. Reading history only needs regular membership;
there’s no revert command in the CLI, since revert is an app-only action.
The workspace-wide size budget
Beyond the per-skill limits above, your workspace’s enabled skills share a combined size budget: 2 MB (2,097,152 bytes) total, across every skill switched on for your workspace — your own and any inherited from a group above you. CodeHerder checks this the moment you make a change, not later: it’s a refusal, not something that quietly drops a skill once a session starts.
Not every change can hit this budget:
- Turning a skill on can be refused if it would push your workspace over the limit.
- Editing a skill that’s currently on can be refused too, if the edit grows it enough to go over.
- Creating a new skill is never refused — a new skill starts switched off, so it adds nothing to the total until you enable it. This holds for items you write. A synced item starts switched on, so a plugin source pin can hit the budget. The budget then refuses the whole pin.
- Editing a skill that’s switched off is never refused, for the same reason.
- Turning a skill off is never refused — it can only shrink the total.
If you create a skill with Enable in this workspace now checked while your workspace is near the limit, the skill is still created; only the enable step is refused. Free up some room, then turn it on separately.
If you hit this limit, disable a skill you’re not using, or shrink one. ch skill list
prints a BYTES column for every skill, so you can see where the weight is before deciding
what to trim.
Starting from a skill that already exists
A skill page has a Copy skill button for any skill your workspace doesn’t define (visible
to an owner or admin). It opens the New skill 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, and deleting a skill need a workspace owner or admin, and a
signed-in person. An agent’s session can’t do any of them. Enabling, disabling, and resetting
also need an owner or admin, and an agent’s session can’t do them either. The ch skill
commands follow the same rules. In CI, use a human owner’s or admin’s member key. 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 yourself or one you inherited from a group; 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. This works for all six supported CLIs. Four of them (Claude, Codex, Cursor, and OpenCode) get a link into their skills folder. Pi is handed its skills directly. mini-swe-agent has no skills folder, so CodeHerder lists each skill in its prompt and the agent reads the skill file. See Harnesses for the full list.
Agents and commands reach every harness. Claude Code gets an agent in .claude/agents and a command in
.claude/commands. The other five harnesses have no folder for them, so each one arrives as a skill
with the same name. The agent reads the original text from that skill. If a skill, a file in your repo,
or an earlier item already has the name, the earlier one wins and the later one shows Skipped.
Script files
A skill can carry helper scripts, for example scripts/setup.mjs. Scripts follow the same
limits as other files. They count toward the file count and the size budgets.
- The agent sees each script at the same relative path.
- A script that starts with a
#!line is installed as executable. - A script without a
#!line is installed as a plain file. The agent can still run it with its interpreter. - CodeHerder never runs a skill script. The agent runs a script when the skill tells it to.
- The skill page marks each script with a Script badge, plus Executable when the file
starts with
#!. This shows an admin what executable content a skill carries. - A device on an older version installs scripts as plain files, not executable.
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:
- A session that runs in your own checkout gets no linked skills. If you start a session
with
ch start(see Local sessions), CodeHerder never writes into your checkout. The agent doesn’t see your catalog skills there, except Pi, which is handed its skills directly. Task sessions and sessions you start on a device both get skills. - 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 session’s page and look for the Skills section, near the bottom. It says
“Injected into this session’s worktree at spawn.” It lists every skill the session was
eligible to receive, each with its kind and an outcome. Rows from a plugin source group under
the source, with plugin@marketplace and the short commit. The outcomes are:
- Loaded — the item is in the session. CodeHerder linked it into the agent’s folder. If the device’s filesystem doesn’t support linking, CodeHerder copied it instead. If the link was already there, nothing changed.
- Skipped — your repo already has its own folder or file with that name, so CodeHerder left it alone. This is the same “your own copy always wins” rule above, not a bug. An agent or command also shows Skipped on a harness without agent folders when a skill or an earlier item took its name.
- Removed — the skill is no longer enabled, so CodeHerder removed the copy it had previously delivered.
- Not found / Turned off — the session’s workflow stage narrowed its own skills to a specific list, and one of the names on that list didn’t resolve, or resolved to a skill your workspace has switched off. See Which skills a stage gets for what a stage’s own selection is and how to set one.
- Unsupported harness — the item is an agent or a command, and the session ran on a device with an older release. That release delivers agents and commands only to Claude Code. To fix it, update the device.
- Opted out — the device owner turned off synced content with
CH_SYNCED_CATALOG. See Changing a device’s settings. Items an admin wrote still load. - Refused — the plugin source’s last sync refused this item. The row names the reason.
Alongside the per-skill list, a counter row totals how many skills were enabled, linked, already linked, copied, skipped, and removed for that session — plus, when the session’s stage narrowed the set, how many it selected.
The section can also show other messages:
- “No skills are enabled for this workspace, so none were injected.” It links to Manage skills so you can turn some on.
- “CodeHerder doesn’t know a skills folder for the
<harness>harness, so no skills were injected for this session.” This happens when the session was launched with a raw command CodeHerder doesn’t recognize as a supported CLI. It also happens for a session in your own checkout (see above). - “The device reported a problem injecting skills” followed by the device’s message.
A session with no delivery report at all has no Skills section. A pi or mini session shows only the
counter row with no per-skill list, since these harnesses get their skills bundle directly rather
than through a folder to link into.
Enforced hooks
A skill frontmatter hooks key is refused on upload. A skill asks the agent to behave. A guardrail enforces a rule.
Related guides
- Plugin sources — sync a team’s plugin skills, agents and commands into the catalog at a pinned commit.
- Version history and going back — how a skill’s history compares to the other things CodeHerder keeps a history of.
- Which skills a stage gets — narrow a workflow stage’s sessions to a specific list instead of the workspace’s whole enabled set.
- Managing workspaces — groups, nesting, and how a group’s settings reach the workspaces beneath it.
- Agents and the CLI — set up
ch, includingCH_WORKSPACE_ID. - Agent personas and system prompts — the other way to shape agent behavior, per-agent rather than per-workspace.
- Workspace wiki — the other shared, inherited store your workspace keeps.
Last updated