Module: Skills
Reusable instructions the agent can pull in when a task calls for them, written in Anthropic's SKILL.md format β the same files Claude Code reads, so a skill written here works there and back again.
Status: implemented β storage and discovery, agent consumption through the existing
progressive-disclosure path, a creator with a live preview of exactly what the model
receives, per-turn cost accounting, and export/import against .claude/skills/.
Backend backend/modules/skills/; frontend packages/core/src/modules/skills/.
Contributions to the layout shellβ
- Panels β
skills.library("Skills", π,role: 'document'β a browsable catalogue, the same shape as the marketplace; singleton). Two sections:library(l, default) andeditor(e). - Commands β
skills.open,skills.new(opens the pane and switches it to the editor),skills.status(prints the list and the per-turn cost inline, no model turn). - Chat β
/skillslists them with their per-turn cost,/skills openrunsskills.open. - Agent tools β
use_skill, in the core set, but only when a skill is enabled. - Keybindings / settings β none. Enablement is machine-local state, not a setting; see Enablement.
The editor is a section, not a swap of the pane body from local state. It used to be the latter, which left it with no address at all: the shell did not know it was open, a reload dropped you back in the list, and the only way out was the component's own Cancel button. One honest limit remains β the section is addressable, but which skill is loaded into it is still component state, so a reload returns to an empty editor rather than to the skill you were writing.
/skills returned the literal string No skills available yet. for as long as this
module has shipped β a placeholder from before it landed that nothing came back to, so
asking the agent about its own skills got a confident denial they existed. It reads the
module's own client now, the way /mcp does, and the two cannot disagree.
The format is not oursβ
A skill is a directory containing SKILL.md: YAML frontmatter (name, description,
optional allowed-tools) followed by a markdown body.
---
name: tidy-a-file
description: Tidy a source file the way this project likes it. Use before committing.
allowed-tools:
- files.read
- editor.proposeEdit
---
# Tidy a file
1. Read the file.
2. β¦
Adopting the format rather than inventing one is the whole point: it is what makes a skill portable in both directions without a converter, and a converter is exactly the thing that would rot.
Two sources are discovered:
| Scope | Location | Writable here |
|---|---|---|
user | $HORRIBLE_DATA_DIR/skills/<name>/SKILL.md | yes |
project | <repo>/.claude/skills/<name>/SKILL.md | no β copy it first |
Project skills are the repository's own git-tracked files. The pane reads them and
offers "copy to mine"; a pane that silently rewrote one would be a surprise in
someone's next git diff.
Two tiers, and the whole economicsβ
This is the design, and everything else follows from it:
- The description rides every turn. All enabled skills are listed β one line each,
name: descriptionβ in a system message assembled next to the tool guides. That is how the model learns the skill exists. - The body is delivered only when asked for. The model calls
use_skill(name)and gets the instructions back as a tool result.
The same progressive disclosure the tool groups use, for the same reason: a good skill's body is thousands of tokens, and paying for all of them every round would make skills a net loss. What the split buys is that a skill costs a sentence until the moment it's worth its full price.
The catalog is not free, and the pane says soβ
Ten skills with 40-word descriptions is a permanent ~500-token tax competing with the same budget the 38-tool ceiling constrains β a fine trade if the skills fire, pure loss if they don't. So:
GET /api/skills/costcounts the assembled catalog and each skill's share of it, and the pane leads with "N tokens on every turn" before the list.- The catalog is its own block kind in the interpretability
pane (
skills, "Skill catalog"), deliberately not folded intoguides: a guide is paid only when its group is active, while every line of this rides every round. Merging them would hide the one block whose growth most needs watching. - Disabling is the lever. A disabled skill costs exactly nothing.
Zero skills costs exactly zeroβ
No catalog message, and use_skill is not in the core tool set β the tool appears
only when at least one skill is enabled. An unconditional core tool would be ~60 tokens
on every turn of every install, which is precisely the regression that took the core
tool list from 34 down to 11.
The check runs on every model round, so the discovered-skill list sits behind a 2-second TTL cache; the routes invalidate it after a write, never before β dropping it first leaves a window in which a concurrent turn refills it from the pre-write state.
allowed-tools activates tool groupsβ
A skill saying "use editor.proposeEdit" is useless if that tool isn't loaded, and
asking the model to notice the gap and call load_tools itself is a round-trip it
routinely skips. So use_skill resolves the declared entries to their groups and
activates them in the same step, returning loadedGroups (and those groups' guides,
for the same reason load_tools returns one).
An entry may be a tool name (files.read) or a group name (files) β both are written
in the wild, and a group name never contains a dot, so they're unambiguous. Resolving
here keeps the file portable: Claude Code's allowed-tools lists tools.
The picker, and the seam it exposesβ
That field used to be free text with a placeholder. Two things were wrong, and the second matters more.
You could not tell whether what you typed was real. A name matching no group is not an error anywhere β the skill saves, loads, and activates nothing, surfacing much later as an agent that appears to have ignored its own skill.
And it hid the relationship with MCP completely. A group is a tool name's
prefix, and a connected MCP server is a group (mcp-<id>), so a skill can pull a
whole third-party server's tools into a turn just by naming it here. Nothing in either
pane said so. The picker reads the live catalog from GET /api/agent/tool-groups β the
same _group_catalog the model gets from list_tool_groups, so the two cannot drift β
and MCP servers appear in it beside the built-ins, which is the only place that
relationship is visible.
Free text is still accepted alongside the picker: the format allows individual tool names, Claude Code writes them that way, and refusing to round-trip a portable file would defeat the point of adopting the format. Entries the picker does not recognise are kept and shown, never dropped β a skill authored against another machine's servers is still a valid file, and silently discarding its entries on save would corrupt it.
Note the route reports connected. With no browser socket attached it can only see
backend groups, so the frontend-contributed ones (editor, files, layoutβ¦) are absent; the
picker says so rather than presenting a short list as the whole catalog.
A skill cannot widen a specialized agent's scope. use_skill running under a spec
with tool_groups drops anything outside it and reports refusedGroups β otherwise a
skill would be a way around the roster's boundaries.
Failure is visible, never silentβ
A skill that quietly fails to load is the worst outcome in this module: the agent simply doesn't know something, and nothing anywhere says why. So every malformed file is listed with its error rather than skipped:
| Problem | Reported as |
|---|---|
| No frontmatter, or an unclosed fence | "the file must start with ---" / "never closed" |
| Invalid YAML, or frontmatter that isn't a mapping | the YAML error / "must be a mapping" |
No description | "the model has nothing to decide by" |
name: disagrees with the directory | "the directory wins; fix the file" |
| Empty body | "there is nothing for the model to read" |
The directory is the identity, not the frontmatter's name. Everything that
addresses a skill β save, delete, export, use_skill β needs one answer, and the
directory is the one that exists even when the file won't parse. Taking the name from
the frontmatter instead makes a mismatched file retrievable under neither identity, so
the pane cannot show you the error it just recorded.
A BOM before the fence is stripped, because an editor writing UTF-8 with a BOM would otherwise make every skill it touches "have no frontmatter".
Shadowingβ
A user skill and a project skill can share a name. use_skill takes a name, so the
collision has to resolve one way: the user copy wins, and the project one is flagged
shadowed in the list. Hiding it would leave "I edited the skill and nothing changed"
with no explanation.
Enablement is not a settingβ
GET /api/settings hands the whole bag to the browser, and this is machine-local state
about local files β so it lives in $HORRIBLE_DATA_DIR/skills-state.json. Nor is it
frontmatter: toggling a project skill would rewrite a git-tracked file to record a local
preference.
Portabilityβ
POST /api/skills/{name}/export copies a user skill into .claude/skills/, where Claude
Code reads it unchanged. A copy, not a symlink β Windows needs elevation (or
developer mode) for one, so a symlink implementation works on the author's machine and
fails on half the users', with an opaque OSError at export time. The cost is that the
two diverge after an edit.
The other direction is already automatic: anything in .claude/skills/ is discovered as
a project skill, and "copy to mine" brings the whole directory β resources included,
since the format lets a body reference files beside it.
Backend surfaceβ
Mounted at /api/skills:
| Method | Path | Purpose |
|---|---|---|
GET | `` | Every discovered skill, both scopes, including broken ones |
POST | `` | Create or update a user skill (409 on a project skill) |
DELETE | /{name} | Delete a user skill (409 on a project skill) |
POST | /{name}/enabled | Switch its catalog line on or off |
GET | /cost | Per-turn catalog cost, and each skill's share |
GET | /{name}/preview | The literal catalog text + the literal use_skill result |
GET | /{name}/files/{path} | One file from the skill's directory, as text (read-only) |
POST | /{name}/copy | Copy a project skill into the user's own |
POST | /{name}/export | Copy a user skill into .claude/skills/ |
The library is an index and a detail, not one wide listβ
Every skill used to be one full-bleed row carrying its name, its description, a token figure and six controls. Nothing capped the width, so in a maximised pane the Delete button sat two thousand pixels from the name it belonged to β and the name, at 11px uppercase, was smaller than the description underneath it.
So the row's job was split from the record's, across a SplitPane (persisted width,
and narrowBelow measures the pane rather than the viewport, because a skills pane
docked in a three-column workspace is narrow at any screen size):
- The index holds identities and nothing else β name,
tok, and aproject/offchip β which is what lets it be 280px wide. Its titles are set throughDataList'ssize="lead"variant, so the name is read at 15px instead of being the smallest text in its own row. - The detail holds everything that is about a skill: description, tools, files, path, and every action, inside a 72ch reading measure.
The index rows carry no buttons, and that is a rule rather than a preference.
DataRow renders a real <button> once it is clickable, and a <button> may not
contain interactive descendants β an enable checkbox and five buttons inside a
selectable row is invalid content that browsers and screen readers each recover from
differently. Moving them to the detail is also what collapses the width.
A skill is a directory, so its files are part of itβ
GET /api/skills now carries a files list per skill (paths relative to the skill's
own directory, SKILL.md first, dotfiles and __pycache__ skipped), and
GET /api/skills/{name}/files/{path} returns one of them as text. copy_to_user had
always taken a skill's sibling resources along β the format lets a body reference files
beside it β but nothing ever served them, so a skill's own references were invisible
in the app that hosts it.
Two things are load-bearing:
- The containment check lives in
store.read_file, not the route. A route that passed a caller-supplied path through toread_textis an arbitrary-file-read route. The path is resolved and required to beis_relative_tothe skill directory, which is what fails../../../.envand an absolute path alike β the same reasoning as the database module's write gate living in the driver. - A binary file is refused, not decoded. Rendering a PNG through
errors="replace"produces a page of replacement characters, which reads as a broken viewer rather than the honest answer that the file is not text.
The viewer is read-only. The editor writes SKILL.md and nothing else, exactly as
store.save does, and a viewer that could write would first need an answer for what
happens to a project skill's git-tracked resources.
The creator shows the string, not the intentβ
A skill is a prompt, and the usual way prompts go wrong is that the author is looking at
their intent while the model is looking at a string. So the editor's preview shows the
two things the model literally receives β the catalog line and the use_skill result β
as raw text rather than rendered markdown. Stray frontmatter and leading whitespace are
exactly what a prettified preview would hide.
Roadmapβ
- A test run against a spawned agent. The pieces exist (
agent.delegateruns a full sub-turn on the same connection), but a "try this skill" button needs a live socket, so it belongs to the chat surface rather than a REST route. - Resources beyond the body. The format allows files beside
SKILL.md; they are copied and exported, but nothing yet offers them to the model β a skill that says "seereference.md" is describing a file the agent can only reach through thefilestools. - Skill-scoped permissions.
allowed-toolscurrently grants (it loads groups); it does not restrict a turn to those tools. Making it a ceiling as well as a floor is a permission-model change, not a skills change.