Utopia Fleet Wiki
Resume
Resume
Structure

The skills layer

A skill is reusable agent behaviour stored as a directory with one markdown file. It reaches exactly one machine. The fleet has three delivery layers, and each one reaches a different set of machines.

Updated

in-flux

Prompt 1

Learn the three delivery layers and why a skill reaches one machine

Reads this page, explains the three delivery layers, their reaches and the conventions that decide whether a skill fires, then quizzes you. Writes only its checklist.

Prompt 2

Audit my skills for rot and dead routing, then fix one properly

Audits every skill, rule and instruction file on this machine for stated facts already false and descriptions that will never fire, then rewrites or creates one skill. Writes only after you confirm.

This page comes from the fleet's own component document for skills-layer. It is marked in-flux for three reasons. Three of the component's own in-repository pointers resolve to files that nothing calls. Only two of the fleet's seven agent repositories have a skills directory at all. And those two have diverged, and nothing measures the gap.

A skill is a directory that holds one markdown file. The model reads the description in that file's frontmatter to decide whether the skill applies. So the description is not documentation. It is the routing key, and a skill with a vague description exists but never fires.

The fleet's process entry points live here. These are the skills that start a plan, continue one, or run a feedback pass. If you deleted this layer, every agent would keep executing work, but there would be no way left to start anything.

This page is about delivery: which machines get a skill, and how far it actually travels.

The defining property is negative

A skill reaches exactly one machine.

The fleet ships a plugin to every box. The plugin carries hooks and scripts, is pinned to a commit, and is gated on a version. One push really does reach every box, because every box pulls it. That is true of the plugin and of nothing else. People who had read the plugin's documentation have more than once applied the sentence "one push, every machine gets it" to skills.

The plugin does not carry skills, and it never has.

Three delivery layers, three reaches

PLUGIN        one repository  →  EVERY box
              pinned to a commit, gated on a version
              carries: hooks, scripts

DOCTRINE      each box's own clone  →  EVERY box, live
              read through a symlink, so a rule change
              lands with no version bump
              🔴 but the SYMLINK is tracked in that box's own repo

SKILL         one box's own repository  →  exactly ONE box
              arrives at that box's next pull

People keep confusing two of these layers with each other. The middle one causes the most trouble, because doctrine looks like it is delivered the way skills are.

Each machine reads doctrine through a symlink into its own clone, so a rule change reaches every box without a release. But the symlink itself is a tracked file in that machine's own repository. On five machines, someone repointed the links by hand and committed the change on none of them. After that, every checkout restored nine symlinks into a directory that the rebuilt tree no longer had. The automatic pull then skipped, because it refuses to run over uncommitted deletions. The result was five machines pinned to a stale tree, with no warning.

A repoint is not delivered until someone commits it. A change made by hand on a live machine lasts until the next checkout and no longer.

What belongs in a skill, and what does not

A skill belongs to the agent that owns the folder. A machine's agent directory belongs to that agent, and a project's own skills, commands and rules never go there. That boundary stops one agent's behaviour from leaking into another agent's because their files sit near each other.

The fleet holds its own skills to four conventions. Each one came from a past failure, not from a preference.

  • A skill that touches more than one file loads its context and shows a status table before it writes anything. The reader sees what is about to happen while it is still cheap to stop.
  • A skill never asks an interactive question as its first step. A skill that opens with a question has not read anything yet, so it cannot ask an informed one.
  • A skill with side effects opts out of automatic invocation. Matching on the description automatically is right for a skill that reads and wrong for one that writes.
  • The set of verbs a skill name starts with is fixed. audit is read-only, self-enhance runs on its own, and update and fix are limited in scope. A skill whose name does not start with one of them claims a shape the fleet has no rules for.

A door is thin; the process is a frame

The skills that start things work out which process you mean and then hand off to a frame document. The process itself lives in the frame document, never in the entry-point skill.

This matters more than it sounds. If an entry point contains its process, a second entry point cannot share it. As soon as two entry points need the same steps, someone copies the steps, and the two copies diverge the way any two copies do.

A fact a skill would assert becomes a command that reads it

In a skill file, an exclamation mark directly followed by a backticked command runs in a shell before the content goes to the model, and the command's output replaces the placeholder. We verified this here both with no tool allowlist and with automatic invocation turned off.

So a sentence that states a count, a path or a version goes out of date, and a command that reads the value does not. The pages on this wiki follow the same discipline, state the probe, not the answer, and this applies it one layer down, inside the instruction itself.

The executing agents have no skills at all

That is the current design, not a gap. An agent that executes a filed piece of work reads its specification and its checklist. Anything it needs from a process is written into the issue body when the issue is filed.

This is the opposite of the obvious approach. The machines that do the work carry the least process. Process lives where work is planned, and it reaches the place where work is done as data in the issue, not as installed behaviour. That means a process can change without deploying anything anywhere.

Grade the population, never one machine

"The fleet has skill X" can only be true of each machine separately, and no single account can read most of them. A verification here once read one machine and declared the whole layer sound.

Every fact about this layer lives outside the repository, so this page gives the commands that read each fact instead of the answers:

QuestionCommand
What does this machine havels ~/.claude/skills/
What does a given machine's repository carrygh api repos/<org>/<repo>/contents/skills --jq '.[]|select(.type=="dir").name'
What one skill actually doesgh api repos/<org>/<repo>/contents/skills/<name>/SKILL.md --jq .content | base64 -d
Does the plugin carry skills (it does not)gh api repos/<org>/<repo>/contents/plugins/<plugin> --jq '.[].name'
Is a machine on the current plugin payloadbash _infra/scripts/plugin-deploy-check.sh

That table has one trap, and it costs an hour the first time. gh api writes its 404 body to standard output, so a bare fallback prints the error JSON and the fallback text on one line. Filter for the shape of output you expect, not for whether the output is empty.

Where this layer is currently weakest

  • Only two of seven agent repositories have a skills directory. The rest return 404. So the layer really reaches two machines, and nobody else can reach the larger set, which holds most of the skills that exist here. Any plan that says "ship a skill to the fleet" describes a mechanism that does not exist.
  • The two sets have diverged, and nothing measures the gap. One has twenty-four named skills and the other has fifty-one. There is no shared manifest, no linter and no index. No command answers "which skills exist in the fleet". The table above needs one read per machine because that single command has never existed.
  • A backup file sits inside the skills directory, the same directory the loader walks. It is not a skill and nothing removes it, which breaks this fleet's own standing rule that git history is the archive.
  • Three of this component's own in-repository pointers point at files that nothing calls. The assertion checker reports them as present on disk and called by nobody. That is what an entry point looks like when someone replaced it but did not delete it.

The always-on agent

The fleet forbids resident processes and then permits exactly one. This page covers what earned that exception, what the process has to declare about itself, and the three properties that stop a permanent loop from dying without anyone noticing.

Surfaces

Every hostname the fleet owns or references, each with an explicit class of LIVE, RETIRED-BY-DECISION or BROKEN. A status code by itself does not tell you the state.

On this page

The defining property is negativeThree delivery layers, three reachesWhat belongs in a skill, and what does notA door is thin; the process is a frameA fact a skill would assert becomes a command that reads itThe executing agents have no skills at allGrade the population, never one machineWhere this layer is currently weakest