An agent answering "what is a commander, how do I start one" had nothing to answer from. skills/load.ts
already compiles an index of name + when-to-reach-for-it + path into every session, with the body read on
demand — so this needed skills written, not a mechanism built. There was one skill before these; now three.
skills/platform/SKILL.md is GENERATED by the platform repository's `bun run skills:platform`, and its
`docs:check` fails if it drifts. Do not edit it here — an edit is lost on the next run, and the generator
carries the prose for exactly that reason.
skills/commander/SKILL.md is written by hand, because none of it is derivable. What is in it is what three
days of running one taught, including the parts that surprised us:
- A commander is an ordinary chat session in a particular directory. Not a special agent — a conversation
plus a loop somebody started from inside it.
- Three pieces, and people get the third wrong: the conversation, the shell loop that waits, and the HEADLESS
AGENT the loop spawns when it fires. They expect the commander itself to wake up. It does not.
- Its cost line understates, structurally: only turns crossing the platform's chat socket are recorded, and a
spawned agent's never do. A commander that spent dollars through children can display cents.
- A spawned agent cannot be linked to its parent after the fact. The entry types that look like they mark one
are the harness's own and appear in both. If the link matters, the loop must record the id itself.
- Poll a local address, never a public hostname behind a reverse proxy — rate limiting there reads as an
access-rights error and is not one.
- The platform may not know a watcher exists: its bookkeeping engages only for the hand-back-and-re-arm fire
behaviour, so a working loop can sit beside a row that says unarmed.
The largest section is about helping somebody SHAPE one, since that is the part that is a conversation rather
than a form. Four questions, and the third is the one nobody volunteers: what must never happen twice. A
trigger that stays true after a failed action fires again, and again.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ChatLink applies target="_blank" to every anchor without exception, so linking an Officer route does not
navigate the app — it loads a second copy of the whole SPA in a new tab and the person loses their place
in the first.
That is the intended behaviour, so this declares it rather than treating it as a defect. What changes for
an agent is small and constant: name an internal route in backticks instead of linking it, since the
reader is already in the app, and save links for things that genuinely belong in a tab of their own.
Asked for by the owner after it was raised and set aside yesterday.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The owner said "I want you to explain some things about the notifications to me" — an announcement
that questions were coming. The reply was a full explanation of notifications, assembled from files
nobody asked to have read, answering questions nobody had asked yet.
Announcing a topic is not requesting anything. It usually means the person is still typing.
Passes the boundary tests in docs/affordances.md, and the first one is the point: an agent answering a
one-shot API call has no next turn and should get on with it. Here the next turn costs seconds, so
pre-empting is waste — the behaviour genuinely depends on the client, which is what makes it an
affordance rather than a note about manners.
Scoped narrowly on purpose: when there IS a request, carry it out in full. This covers only the case
where there is not one yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer shows a live panel per background job carrying that job's output, and the user watches it. A
command that writes nothing until it finishes leaves that panel reading "Nothing written yet." for the
whole run, which is exactly what a hung job looks like.
Written after doing it twice in one session: plugin installs driven from a script printed nothing for
two minutes, and the owner asked whether I was stuck. Both times the work was fine.
So: verbose flags on, echo around each step when the tool has none, per-item output in a loop, and the
result on the last line — that is the line still on screen when the panel stops. Plus the buffering
trap, because a program that prints steadily still shows nothing through a pipe.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
reported after it happened repeatedly: commands rendered as inline backticks,
which the user then has to select by hand — on a phone especially.
it passes the tests in docs/affordances.md rather than being a defect worn as
one. a terminal client would not care; this one has a copy button on fenced
blocks and none on inline code, so it is a fact about the surface. and the
partial code fix available — click-to-copy on inline code — would not make it
right anyway: a command still wants its own line and unambiguous boundaries.
the deciding argument is that this already existed as a private memory, in one
project, for one agent. it has never helped another agent and never would. an
affordance is how a fact like that stops being one agent's note.
says not to include a `$` prompt, because that gets copied too and then it
does not run — which is the specific way a well-meant fence still fails.
AskUserQuestion renders real buttons the user can really click, and returns
"The user did not answer the questions." every single time — it resolves
before the buttons have painted, because the SDK has no answer channel. the
choice comes back as the next user message instead.
an agent cannot discover that. what it sees is a tool that always reports
failure, so the readings available to it are "the user refused" or "the tool
is broken", and both are wrong. the cost is asking again, or waiting for a
turn that already ended.
second on the same page because it is the other thing invisible from the
filesystem: markdown renders in BOTH directions now, so a table beats
hand-aligned columns.
Image rendering, the platform's first core affordance. It tells an agent
something it cannot discover from the filesystem: markdown images render, and
the USER'S DEVICE fetches the URL — so a local path renders nothing, silently.
Only authored content is tracked. The six item directories are created by the
platform at boot and are where the owner authors their own work, so versioning
them here would be claiming somebody else's files.
pastilhasandClaude Opus 5