Skip to content
Skills Library
AI & agents · Planning

agent-fleet-design

/agent-fleet-design

Use when adding, backing up, or driving the agent fleet.

Licence
MIT
Last repository change
31.10.2026

Assessment and security

96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 31.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when adding, backing up, or driving the agent fleet.

Original author description

Use when adding, backing up, or driving the agent fleet.

How it works

  1. Always-on rules
  2. Fleet backup repo
  3. Driving a fleet agent from the coordinator
  4. Fleet runtime ops (gateways, updates)
  5. Reference chart (dev fleet)
  6. Fleet inventory one-liner
  7. Designer contract (reusable for any visual role)
  8. Role seat SOULs (~2.5 KB each)
Original SKILL.md headings · 310 lines, 3,104 words
SKILL.md preview
---
name: agent-fleet-design
description: "Use when adding, backing up, or driving the agent fleet."
version: 2.0.0
author: coordinator role of hermes-fleet-apps
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [fleet, multi-agent, roles, orchestration, hermes, profile, organisation]
    related_skills: [hermes-agent-factory, agent-identity-setup, fleet-project-pipeline]
---

# Agent fleet design

The fleet exists so one person can ship software alone: the owner throws ideas
and approves plans; specialised agents own the details. The owner is the
bottleneck (attention, time, maybe no dev training), so every design choice must
reduce their decisions to a few gates. Creating a single profile is
`hermes-agent-factory`; this skill decides WHICH profiles exist and how they hand
off.

## Always-on rules

- **Split by conflict, not by human job title.** A new agent is justified only
  by one of three conflicts: a different SOUL (builder vs judge), different
  tools (video renderer vs compiler), or different risk (may push to git vs
  writes prose). No conflict = the same agent carries several human roles
  (coder = frontend + backend + devops). 5-7 agents cover a small software org.
- **Project state lives in the repo, not in agent memory.** Agents coordinate
  through project files (`SPEC.md`, `.design/`, git log), never by reading each
  other's profile dirs — a profile is who an agent is, not where the work stands.
- **One shared `FLEET.md` next to the profiles** lists who does what,
  inputs/outputs, and the owner's approval gates. Each agent's memory carries ONE
  line pointing at it. Never copy the fleet map into every memory — N copies
  drift the first time an agent is added.
- **Adding an agent = FLEET.md edit + pointer edits** in the SOULs that
  previously held the responsibility (e.g. "brand belongs to coder" → "to
  designer"). Grep every SOUL for the responsibility word before declaring
  the hand-over done.
- **Skills migrate with responsibilities.** When carving a role out of a fat
  agent: `find <profile>/skills -name SKILL.md`, map each skill as stays /
  → new agent / → later agent / remove (off-role), show the owner the map, move
  only after they confirm, then re-run `prompt-size` on both profiles. `mv` by
  default; **copy** only when both sides genuinely run it from their own seat
  (commit-identity rules: coder signs, docs publishes; interview forms: product
  and coder both question the owner). Read the skill's `description` before
  deciding — a review skill written for the *author* ("request a review")
  stays with the builder, one written for the *judge* goes to qa.
- **Build the whole fleet before resuming product work.** A half fleet means the
  first real project hits a missing seat mid-flow.
- **Hermes kanban is the software factory, already built.** `claim`
  (atomic, per-profile), isolated workspace per task, review states,
  `decompose` (routes by profile `description`), `dispatch` daemon. Do not
  hand-write "claimed label / sandbox / one-merge-at-a-time" rules into
  FLEET.md — adopt one board per project once the fleet exists, test with 2-3
  real tasks, then make it the standard path (see `fleet-project-pipeline`).
- **Keep a plan file while restructuring.** Reorganisation spans sessions and
  overwhelms the owner; the coordinator owns a `FLEET-PLAN.md` (decided / open
  decisions / numbered steps) and surfaces ONE open decision at a time. The owner
  does not have to remember the file — the coordinator re-reads it.
- **A per-project knowledge base lives in the project, not per agent** — per-agent
  copies go out of sync.
- **Efficiency settings are baked into the seed**, not applied per agent (e.g.
  `hermes -p seed config set compression.threshold_tokens <n>`). There is no
  config option for "hand off after N compactions" — that is a behaviour rule for
  the seed SOUL (LIMITS) plus the `handoff` skill: endless compaction degrades
  context and silently drops earlier decisions.
- **Shop the hub before writing a role skill**: `hermes skills search <term>`
  then `hermes skills inspect <identifier>`. Prefer `official` trust; read
  frontmatter for `allowed-tools`/CLI needs and reject anything requiring a
  paid or cloud CLI — it silently routes work off-machine. Vet community skill
  repos per `references/community-skill-vetting.md`, give a TAKE / DROP / LATER
  verdict, assign every TAKE to exactly one profile, and record the verdict in
  the plan so it is never re-vetted. Install when that profile is built, not before.
- **One skill per theme per agent.** Two review skills or two spec skills on
  one profile compete for the trigger. When two repos overlap, pick one source
  for that theme and write the pick in the plan.
- **A persona repo ("think like the lazy senior dev") splits in two**: the
  standing rule (e.g. the Ponytail ladder: exists? → in repo? → stdlib? →
  installed dep? → one line? → minimum; never cut validation/security/error
  handling; one small test; end with "what I skipped") goes INTO the SOUL of the
  coding seats, in full, so it holds without the model choosing to load anything;
  the long procedure (`ponytail`, `ponytail-review`, `ponytail-audit`) is
  installed as plain SKILL.md files from the upstream repo, never through a
  third-party plugin wrapper. qa gets `ponytail-review` only (it finds code that
  should not exist, which `code-review` does not). A persona that conflicts with
  a seat's SOUL (non-dev agents) is not installed there at all.
- **Skills an agent cannot do its job without are named in its SOUL at the
  method step where each applies** ("Research `x`; Spec `y`"), names only.
  The skill index is a suggestion the model may skip, and the owner never names
  skills or talks to most agents; the SOUL is read every turn. 2-7 names per
  seat; everything else stays index-only or is named in the coordinator's brief.
- **An agent with no job in the queue is maintenance debt.** Park it as
  FUTURE in the plan with its trigger condition. Check the candidate repos' shape
  first: a repo that is an MCP server plus external tools (`npx ... setup`,
  decompilers, proxies) or has no `SKILL.md` at all is a *tool install*, not a
  hub skill — it needs the owner's explicit install approval, so it cannot be
  built on autopilot like a skill-only agent.
- **Retiring a project's knowledge** (the owner restarts a project from scratch):
  follow `agent-identity-setup` → "Retiring a project's knowledge", and grep
  `FLEET.md` too.
- **Naming**: one word, a trade or a function, no human title. Offer the owner
  five options with a one-clause meaning each; they pick.

## Fleet backup repo

The fleet is the asset; Hermes profiles are its runtime copy. Keep one local
git repo (no remote unless the owner asks) that holds, per agent, exactly the
five portable things: `SOUL.md`, `profile.yaml`, `config.yaml`, `memories/`,
`skills/` plus the marker `.no-bundled-skills`, and at the root the shared
`FLEET.md`, `FLEET-PLAN.md`, a small snapshot/restore script, and project
folders for fleet-level work.

- **Never in the repo**: `.env`, `sessions/`, `cache/`, `state.db*`,
  `skills/.hub/` (hub cache, several MB per profile), `skills/.usage.json`,
  `skills/.curator_*`, `skills/.archive/`, `*.lock`. `.gitignore` them and
  check `git ls-files | grep -cE 'usage.json|curator|\.hub|\.env$'` → 0
  before the first commit — a hub cache alone doubles the repo size.
- **Loop after every agent change**: real test + `prompt-size` → snapshot →
  `git commit -m "<agent>: <reason>"`. One commit per SOUL change; the message
  is the changelog.
- **The snapshot copies only the agents its list names.** A live profile missing
  from that list is not backed up. Add the name first, snapshot, then commit only
  that profile plus the script. Leave other profiles' already-dirty files
  unstaged — a snapshot refreshes every listed profile, and committing them mixes
  unrelated history into this change.
- Do not add `.gitattributes` with `eol=lf` and leave `core.autocrlf`
  unset on Windows: every snapshot then prints thousands of CRLF warnings that
  drown the commit output. Set `git config core.autocrlf false` in the repo.
- Set the repo's commit identity locally (per repo). If the owner later wants a
  remote, say so, so they pick the forge identity.
- Restore = restore one agent's files + rewrite `MEMORY.md` for the host + the
  owner types `.env`. Memory is machine truth, never restored verbatim.

## Driving a fleet agent from the coordinator

- One-shot: `hermes -p <agent> chat -q "<brief>"`. Continue the same
  session with `hermes chat --resume <id> -p <agent> -q "..."` — `hermes
  --resume ...` without `chat` is parsed as a command name and fails.
- A design/render job runs 3-40 min. Launch with `terminal(background=true,
  notify=true)`; never block a foreground call on it and never re-run it
  when the foreground cap promotes it. Tell the owner one line, end the turn.
- The brief names the exact files to read (`SPEC.md`, `../FLEET.md`,
  `.design/ui-plan.md`, `tokens.json`), the output path, and "reply under
  N lines" — the agent's reply is what the coordinator relays to the owner.
- **Route a field's questions to the agent that owns the field, even quick
  ones.** "Give me a list of visual styles" goes to the designer and the
  coordinator relays the comparison. The coordinator's own job is the brief,
  the gate, and the relay.
- **When product is the seat**: any *what* decision, not only a new idea — a
  new feature on an existing app (scope cut + tickets), "does this make
  sense?" (stress-test, competitors, trademarks), a project that lost its
  course (re-read SPEC, push to "later"). Rule of thumb: nothing reaches coder
  that is not in an approved SPEC. Internal demos/videos skip product — the
  coordinator writes those SPECs.
- **Videos made from code are media's job, including quick teasers.** The
  coordinator writes the brief and relays the result; it never renders itself.
  Before setting up any toolchain for a field, look in the owning agent's work
  folder first: a second copy is waste the owner has to find later.
- **Before saying a project "has no style"** (and routing it to the designer),
  search the repo for `tokens.json` anywhere (`find <repo> -name tokens.json -not
  -path '*/node_modules/*'`), plus `DESIGN.md` and logo files. Older projects may
  keep their house style outside `.design/`; a check limited to `.design/`
  misreports it and sends the owner through a needless design gate.
- **Check the GPU before dispatching any render**: another process can hold most
  of the VRAM. If one does, say so and
  let the owner choose (stop it / go anyway). If the owner says stop mid-render,
  kill the background loop first, then the renderer, or the loop starts the next
  item.
- **Video idea menus**: ground each idea in what media's skills already cover
  (chart, diagram, kinetic type, explainer) and say per idea whether the
  project's style exists; recommend the reusable one (a template refilled with
  new data) over a one-off.
- **Fleet demo content is generic**: the fleet is the subject, no owner named
  or shown, professional wording, no hype. Put that in the SPEC; agents
  otherwise write the owner into the story.
- A second visual variant of the same demo is a new project folder
  (`<demo>-<variant>/`) with its own `SPEC.md` and `.design/`, run through the
  same chain — never a branch of the first `.design/`, since media reads one
  tokens.json per folder.
- **Resuming product work after a fleet-building stretch**: no gateway restart
  unless the coordinator's own SOUL/config changed — memory and skills load fresh
  per chat. Open a new chat and paste a handoff prompt (fleet map path, repo
  path, project scope, the chain to run, first step); do not reopen the
  pre-fleet chat, its context predates the agents.
- The owner adds requirements while a job runs: append a dated `## Owner,
  addendum` block to the artifact the agent is still writing
  (`.design/ui-plan.md`) instead of waiting for it to finish — the agent re-reads
  its own file and folds it in; a second round costs 15-30 min.
- "How long?" is answered from evidence, not a guess: `ls -lt` the agent's
  output folder for the latest write, then say which step it is on.
- A round-2 brief says "read ui-plan.md and tokens.json fully again, they
  changed" and "keep the old render as `<name>-v1.mp4`" — a resumed session
  otherwise trusts its earlier reading and overwrites the only copy the owner
  has seen.
- Every render brief ends with "clean your build dir when done": a renderer
  cache outside the project folder can reach several GB per job, and a repo
  sweep never finds it.
- Check the agent's artifact against its own plan before handing on:
  tokens.json names image files → those exact filenames must exist in
  `.design/images/`, and `grep -ril tbd .design` must be empty. Fix trivial
  mismatches yourself and commit; do not bounce the agent for a filename.
- Fleet-level creative work goes through the same chain as a product:
  SPEC.md (the coordinator writes it) → designer Research + Direction (2-3
  options, comparison table) → owner picks → designer Plan (brand, tokens,
  storyboard to the millisecond, images) → media renders → qa checks against the
  storyboard. Do not send media a style brief directly; it takes style only from
  the project's `tokens.json`.
- **Video deliverables**: every text block stays on screen long enough to read
  twice aloud; deliver the full-res file by path and a small preview for chat.
  Gitignore renders with `**/assets/*.mp4` — a root-anchored `assets/*.mp4`
  misses every variant folder.
- **Per-agent artwork or any image set**: ask for ONE style proof before the full
  set, so a wrong style costs one image, not eight. Every generated image gets a
  close-up defect check before it reaches the owner.
- **Third-party imagery**: register every image in `.design/imagery-briefs.md`
  with source URL and licence. Artwork with no open licence is "private demo only;
  replace before any public release", so docs blocks a public ship. "Everyone
  does it" is not a licence — say so once. For Hermes-branded art, check the
  licence file of the upstream `NousResearch/hermes-agent` repo before using its
  `assets/`.

## Fleet runtime ops (gateways, updates)

- SOUL and skill index load at session start. After a SOUL/skills change:
  headless seats need nothing (each job is a new session); running gateways
  need a restart; open CLI sessions need `/new`.
- Find what runs: `for p in */; do hermes -p ${p%/} gateway status; done`
  from the profiles folder, or `hermes update --plan` (lists every live service
  with its restart command, read-only).
- On Windows, restart other gateways through their own launcher, not
  `hermes -p X gateway restart` from the coordinator's shell: a restart spawned
  there stays in its Job Object and dies with the session ("could not break
  away" warning). Run `hermes -p X gateway stop`, then the profile's startup
  launcher, then `gateway status`.
- The coordinator cannot restart or update itself: Hermes blocks `gateway
  stop/restart` and `hermes update` from inside the gateway. Hand the owner the
  one-line command for their own terminal and ask them to ping the chat
  afterwards.
- `hermes update --set-channel stable` only records the channel and exits;
  the actual update is a second `hermes update --backup -y`. Verify first with
  `git merge-base --is-ancestor HEAD <tag>` in the Hermes checkout that the
  stable tag contains the current commit, so state written by newer code is not
  at risk. A fleet usually wants `stable`, not `main`.

## Reference chart (dev fleet)

```
owner ──idea──> coordinator (routes work, talks to the owner)
   product   what & why   -> SPEC.md (scope, users, done-criteria)          <- gate: owner
   designer  how it looks -> .design/ (brand.md, ui-plan.md, tokens.json, logo/)  <- gate: owner
   coder     builds       -> code + tests; front, back, devops, CI
   qa        verifies     -> bug list, security, review. Never edits code
   media     motion/video -> assets from .design/tokens.json
   docs      release      -> README, changelog, store listing, posts        <- not a gate: owner says go per push/tag/post
```

Out until there is work: legal/finance/sales/support/data.

Two stress-tests, not one: product stress-tests the **idea** (users, purpose,
scope cut); coder stress-tests the **spec** (feasibility, risk, gaps). Do not
strip coder's interrogate step when product appears — re-aim it at the spec.

## Fleet inventory one-liner

Run from the profiles folder:

```bash
for p in <names>; do echo "== $p: $(python -c "import yaml;print(yaml.safe_load(open('$p/config.yaml')).get('platform_toolsets',{}).get('cli'))")"; \
  echo "skills: $(find $p/skills -name SKILL.md | wc -l)"; hermes -p $p prompt-size | grep -E 'total|Tool schemas'; done
```

A narrow agent showing 58-68 skills inherited the bundled sync, not chose
them — trim in a dedicated pass, not while creating another agent.

## Designer contract (reusable for any visual role)

- Deliverables in `<repo>/.design/`: `brand.md`, `ui-plan.md` (per screen:
  purpose, layout, components, empty/loading/error states), `tokens.json`
  (single source of truth; media reads it), `logo/` (SVG + PNG exports +
  font licences), `images/`, `imagery-briefs.md` (register: source URL +
  licence per image, prompts for anything the owner must render), `research.md`.
- Rule: no "TBD" anywhere. If coder would have to ask, the plan is not done.
- Flow: Brief → Research (platform guidelines, 3-5 reference apps) → Direction
  (2-3 options via `sketch` mockups) → owner picks → Plan → owner approves →
  coder builds → designer reviews screenshots, returns a punch-list, never code.
- **A creative seat should be able to produce, not only brief**: give it the
  tools for mockups, SVG and image edits it can do locally, and say per job what
  still needs the owner.
- **Design gates can run through Lavish** (`skills-sh/kunchenguid/lavish-axi/lavish`,
  MIT): the designer writes a reviewable HTML page, opens it with
  `npx -y lavish-axi <file>`, the owner annotates in the browser, feedback returns
  via `lavish-axi poll`. Rules that came with it:
  - Never `lavish-axi share` (it publishes to a third-party host). When a
    CLI-backed skill has a publish/share subcommand, ban it in the SOUL at
    install time.
  - **A live gate needs a listener**: the server self-stops when no poll is
    attached, and the owner's notes then sit stranded in the tab. A real review
    brief tells the designer to open the page and then run
    `npx -y lavish-axi poll <file>` in the foreground and wait, launched by the
    coordinator with `terminal(background=true, notify=true)`. If the page died
    anyway: `lavish-axi <file> --reopen` + poll.
  - Headless test only: brief "open it, do NOT poll" — a poll blocks
    `hermes chat -q` until a human answers. After the test: `npx -y lavish-axi
    stop`, delete the scratch dir and the test session.
  - If the owner reviews from a phone chat while the page opens on the PC, tell
    them the tab will appear and that answering in chat is fine.
- Hub skills that fit: `official/creative/impeccable` (UI/UX method),
  `official/creative/sketch` (variant mockups). Read scanner verdicts before
  installing a community logo/design skill: some are blocked for real reasons
  (sub-agents with permissions bypassed, global npm installs).

## Role seat SOULs (~2.5 KB each)

qa: the builder never grades its own work; Scope → Run → Review → Report; never
edits a project file, not even a typo; PASS only on what it ran. product:
Interrogate → Research → Cut → Spec → Tickets; v1 = smallest thing that proves
the idea, the rest to "later"; questions as a small form with options. docs:
Verify (no qa PASS = no release) → Draft → Check (every claim maps to a built
feature) → Ship only on the owner's go; never a trademark as ours.
Files in this package (2)
  • SKILL.md 20 KB
  • references/community-skill-vetting.md 2 KB

Versions

The database has no other skills named agent-fleet-design.

Database snapshot: 13.11.2026 · package version e516e19d5ad7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 96fleet-agent-inspection
    Use when checking, briefing, or retiring another fleet agent.
  • 100dev-fleet
    Drive the development agent fleet (code-builder, fact-verifier, coherence-checker, code-reviewer) through build, verify, cohere, review and commit with explicit hand-offs. Use for a non-trivial change where correctness and fact accuracy matter and the steps must actually run in…
  • 100ops-fleet
    OPS on-demand: This skill should be used when the user asks to \"fleet dashboard\", \"CLIProxy sessions\"…
  • 100agent-orchestration
    Orchestrate agents at runtime — task routing, scheduling, parallel execution, result aggregation, and supervision dashboards. Use when running agents as a managed fleet rather than one-off calls.
  • 100fleet
    Orchestrate a fleet of coding-agent lanes in Herdr panes — open lanes in worktrees, brief and watch them, run critic rounds, reset or hand off lanes, pick remuda accounts, and clean up. Use whenever you drive other agents through Herdr (HERDR_ENV=1), or the user mentions lanes,…
  • 95agent-bom-monitor
    Monitor agent fleet, track trust scores, and manage lifecycle states. Use when: "fleet", "watch agents", "runtime status", "trust scores", "fleet sync", "agent lifecycle", "serve dashboard".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.