Skills: the capabilities your agents reach for

A skill is a capability your agents reach for - a folder of instructions telling an agent how to do one kind of job, held on your Gateway rather than copied onto each machine. A session starts with a short index of the library - a line per skill, its name and what it does - so it knows what the fleet can do without carrying any of it. An agent reads a skill's actual instructions only when it decides that skill is relevant to what you asked.

It exists because the alternative is a file copied onto every machine by an installer, where fixing one word means a release - and where a withdrawn instruction keeps working from a leftover copy nobody remembered.

What a skill actually is

A directory with a SKILL.md file at its root, plus whatever else it needs: reference notes, scripts, images, data files, whole subdirectories. That shape is not ours - it is the Agent Skills open standard, and every agent DevThrottle has a first-class driver for reads that same directory, byte for byte.

The consequence is the single most useful fact about skills: there is no per-agent format. One skill works across all eight of the first-class agents without being converted, adapted or kept in duplicate. The only thing that differs between them is which folder the directory has to appear in, and DevThrottle handles that.

A skill can carry real programs, not only prose. Files may be binary, and a file can be marked executable so a script inside a skill actually runs.

The catalog

Open Skills in the Cockpit, beside Workflows. Each row is one skill: its id and name, the one line agents see in the briefing, whether it is on, which version is live, whether it is a built-in or one of yours, its first few triggers, and how many supporting files it carries. Read shows you exactly what the skill tells an agent.

The page also holds the two controls that matter. The switch turns a skill off - left out of every briefing and its fetch refused, with nothing deleted and the flip instant both ways. And Clone copies a skill into one of your own, which is the way to customize a built-in.

Drafts are private; publishing is the deployment

Anyone - and any agent - can author a skill. It is written as a draft, which no agent sees and no briefing names. Publishing makes it the live version at once: there is nothing to deploy, nothing to install, and nothing to restart on any machine. A typo fixed here reaches every connected machine at its next refresh, about a minute later.

The one delay is at the edge. Each connected Director re-reads the catalog on a poll about every minute, so a session started in the first moments after a publish can still be briefed with the previous catalog. Reading the library directly with the commands below is never behind - those ask the Gateway live.

Two people editing the same skill do not overwrite each other: an edit carries the hash of the version it was made against, and the Gateway refuses a write that is no longer current rather than losing the other author's work.

How a skill reaches an agent

Two separate things happen, and they are kept apart deliberately so that nothing to do with the network can delay a session starting.

• The session is told what exists. The briefing carries one line per skill - the id and its one-line summary - and the instruction to fetch a skill in full only when about to use it. That block is all a session pays for, and because it is discoverability rather than the library itself, it is bounded: at most forty skills are listed, and beyond that the block says how many more there are and which command lists them all. A long summary is cut to keep every entry to one line.
• The skills themselves are put where the agent looks. While DevThrottle runs it downloads every skill you have switched on and stores it on the machine; when a session starts, the stored skills are written into the folder that session's agent already reads. That second step never touches the network, so it cannot delay a launch - and if the Gateway is unreachable the session still starts, with whatever the last download brought down.

On a machine where DevThrottle is running and reaching the Gateway, the practical result is that a session opens with skills at most about a minute old, and finds them the same way it finds any other skill.

What happens when it is not reaching the Gateway is worth knowing, because it is not one behaviour but two. The skills on disk and the briefing index are refreshed separately and each keeps its own last successful download, so a machine that loses the Gateway goes on starting sessions with what it already has rather than with nothing. The index, though, is not kept indefinitely: once the copy on a machine is more than twenty-four hours old, no index is injected at all and sessions started there are told nothing about the library until a refresh succeeds. That is deliberate - the briefing is authored text reaching every session, and a skill you switched off a week ago must not keep being announced by a machine that has not heard since. Losing the index costs only discoverability: the commands below ask the Gateway live, so an agent that can reach it can always ask what the library holds.

Where they land on your machine

Each skill is written exactly once, into ~/.agents/skills - the shared folder the agent ecosystem standardised on. Six of the eight first-class agents scan that path natively and need no configuration whatsoever. Claude Code does not read it, and Cursor documents only its own folder, so each of those two gets one shortcut per skill inside its own directory pointing at that same single copy. On Windows the shortcut is a directory junction and elsewhere an ordinary symbolic link; neither needs administrator rights.

One real copy is the point: there is nothing that can quietly drift out of step with itself. Skills are written under your home folder and never into the repository you are working in, so they never show up as untracked files in your working trees - which also means a downloaded skill is visible to every session on that machine, including sessions DevThrottle did not start.

Your own skills are never touched

The library is an additional source of skills, not a replacement. A skill of your own on a machine, or in a repository, keeps working exactly as it did - and if one of yours has the same name as one from the library, yours wins. DevThrottle leaves it alone and records that it did. Everything DevThrottle writes is marked as its own, and it only ever changes or removes its own entries.

Reading and authoring from the command line

The Cockpit is one window onto the library; the command line is the other, and it is the one your sessions use.

cc-devthrottle skill list          # every skill the fleet holds, one line each
cc-devthrottle skill show <id>     # one skill's details, without its body
cc-devthrottle skill get <id>      # its full instructions - read this to USE it
cc-devthrottle skill versions <id> # version history, newest first

get is the one an agent actually calls, at the moment it is about to use the skill. It prints the instructions to follow, writes any supporting files onto the machine and prints their paths, and fails loudly if the Gateway cannot be reached rather than letting an agent proceed from memory.

cc-devthrottle skill pull <id> --dir <dir>   # skill.json + SKILL.md + its files
cc-devthrottle skill push <id> --dir <dir>   # upload as a DRAFT; no agent sees it yet
cc-devthrottle skill publish <id>            # the draft becomes live, fleet-wide
cc-devthrottle skill clone <id> <new-id>     # copy one into a skill of your own

--dir is required on both pull and push. push takes --note for a line on what changed. There are two more verbs for the owner's switch, disable and enable, and delete, which archives a skill of your own - its versions stay readable by explicit version, and a built-in can never be deleted at all.

Built-ins are read-only

The skills DevThrottle ships are marked built-in and cannot be edited, so they never diverge from what we shipped and they update with the Gateway itself. The Cockpit does not even offer you a Files button on one, because the write would be refused and a control that cannot work reads as broken. To make a built-in yours, clone it - the copy is published immediately, fully editable, and independent of the original.

Adding one

In the Cockpit, Add skill asks for two things: a name, and one line saying what it does. That line matters more than its length suggests - it is the only part of the skill a session pays for, and the only thing an agent has to go on when deciding whether to fetch the rest.

Adding it creates a draft and hands you the exact prompt to give an agent, which is the intended way to write one: your agents do the authoring, pulling the draft into a working directory, writing its SKILL.md and its triggers, adding any supporting files, then pushing and publishing.

If a skill does not appear

• Is DevThrottle running and connected to the Gateway? The download happens in DevThrottle, so a machine where it is not running gets nothing new.
• Is the skill switched on? Only enabled skills are downloaded.
• Did the session start before the skill was published? Skills are placed at session start, out of what that machine has already downloaded. Give that machine its next refresh - about a minute - then start a new session.
• Has the machine been cut off from the Gateway for a day? Past twenty-four hours it stops injecting an index at all, so sessions there are briefed with no skills until it reconnects and a refresh succeeds. cc-devthrottle skill list reads the Gateway directly and is never the thing that is behind.
• Are there more than forty skills switched on? The briefing lists forty and counts the rest. A skill past that line is in the library and fetchable by id - it simply is not named in the block.
• Is it a custom-agent session? A user-supplied command line has no skills folder, so nothing is placed for it. Use the commands below.
• Do you already have a skill of that name? Yours wins, deliberately. Rename one of them if you want both.

Where to go next

For the ways of working a whole job follows, see Workflows. For which agents DevThrottle runs, see supported coding agents. For the rest of the command line, see the command reference.