docs(wiki): add a Codeman Skill page with the skill GIFs

The skill only had a section inside "Driving Codeman From An Agent". It now
has its own page, docs/wiki/Codeman-Skill.md, built around three real runs:

- five Claude Code workers powering on in the tile grid (2026-10-15)
- eight worker tabs with lineage lines back to the lead (2026-10-15)
- a DeepSeek Harness worker and a Claude Code worker from one prompt
  (2026-10-10)

plus every install route, prompts that work as written, a run start to
finish, which workers it can drive, what it will and will not do on its
own, the Codex notes and what is in the skill. The page says that the grid
recording put each worker on the grid as it started, since sessions an
agent starts do not join the grid by themselves.

The agent page keeps a short skill section (the heading anchor stays) and
links to the new page; the sidebar, Home, FAQ and Settings Reference link
to it too. The FAQ answer no longer says the skill is enabled per case only.
docs/media-assets.md records the new embeds.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/media-assets.md

@@ -26,9 +26,9 @@ A GIF that leaves `docs/images/` stays in git history, so removing it does not s
 | `tile-grid-20261009.gif` | README, Tile Grid section | the Tiles button opening six live sessions side by side, and closing them |
 | `zerolag-demo-20260728.gif` | README, wiki `Input-And-Voice`, `packages/xterm-zerolag-input/README.md`, CHANGELOG, getcodeman.com docs | instant local echo next to slow server echo, on two phones |
 | `codeman-tab-states-20261010.gif` | README, Tab Alerts section | annotated tab states: working, blocked on a question, idle |
-| `codeman-skill-crt-20261010.gif` | README, agent skill section | one prompt to Claude Code spawning and driving two worker sessions through the skill |
+| `codeman-skill-crt-20261010.gif` | README, agent skill section; wiki `Codeman-Skill` (getcodeman.com docs show the MP4 cut) | one prompt to Claude Code spawning and driving two worker sessions through the skill |
-| `codeman-skill-grid-20261015.gif` | README, agent skill section (Step 2) | one prompt to a Claude Code lead, five Claude Code workers powering on as tiles in the grid |
+| `codeman-skill-grid-20261015.gif` | README, agent skill section (Step 2); wiki `Codeman-Skill` (getcodeman.com docs show the MP4 cut) | one prompt to a Claude Code lead, five Claude Code workers powering on as tiles in the grid |
-| `codeman-skill-tabs-20261015.gif` | README, agent skill section (Step 3) | one prompt to a Claude Code lead, eight worker tabs powering on with lineage lines, then a click into a live worker |
+| `codeman-skill-tabs-20261015.gif` | README, agent skill section (Step 3); wiki `Codeman-Skill` (getcodeman.com docs show the MP4 cut) | one prompt to a Claude Code lead, eight worker tabs powering on with lineage lines, then a click into a live worker |
 | `subagent-demo-20260724.gif` | the "mission control" article on dev.to, Hashnode and Medium (hotlinked from `master`) | subagent windows fanning out |
 
 Before removing one, search for hotlinks: `README*.md`, `docs/wiki/`, `packages/*/README.md`, `CHANGELOG.md`, the site (`pr/website/`), and published articles, which link `raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/<file>` and break silently.
@@ -43,7 +43,7 @@ On 2026-10-13, seven GIFs that no page embedded left `docs/images/` and moved in
 
 ## Website media (getcodeman.com)
 
-The site is built and deployed from `pr/website/` (gitignored) with `pr/deploy-site.sh`. Its videos and GIFs sit in `pr/website/assets/` because that directory is what gets uploaded: they are web cuts (1280 to 1600 px wide, high CRF, posters next to them) derived from masters in the library. `pr/site-notes.md` records how each one was cut and from which master. A few superseded files stay deployed on purpose, so links that point at them keep resolving.
+The site is built and deployed from `pr/website/` (gitignored) with `pr/deploy-site.sh`. Its `/docs` pages are generated from `docs/wiki/`, and a wiki GIF that has an MP4 cut of the same run on the site is shown there as that video (the README and the GitHub wiki keep the GIF, since GitHub cannot autoplay inline video). Its videos and GIFs sit in `pr/website/assets/` because that directory is what gets uploaded: they are web cuts (1280 to 1600 px wide, high CRF, posters next to them) derived from masters in the library. `pr/site-notes.md` records how each one was cut and from which master. A few superseded files stay deployed on purpose, so links that point at them keep resolving.
 
 ## Release notes and the media kit (`design-assets` branch)
 

docs/wiki/Codeman-Skill.md

@@ -0,0 +1,166 @@
+# The Codeman Skill
+
+The codeman skill lets the agent inside a Codeman session drive Codeman itself. You ask in
+plain English, and the agent starts worker sessions in any installed CLI, hands each one its
+task, waits for them, reads their answers and cleans up after itself. No curl, no endpoint
+names, no session ids in your prompt.
+
+It is one skill for every agent CLI, in the `SKILL.md` format that Claude Code, Codex,
+Gemini CLI, OpenCode, Grok, OMP and most other agent CLIs read. It lives in the repo at
+[`skills/codeman`](https://github.com/Ark0N/Codeman/tree/master/skills/codeman).
+
+## See it work
+
+Three real runs on a live Codeman: real sessions, real agents, one typed prompt each.
+Nothing on screen is mocked up; the long waits are sped up and labelled as time-lapse.
+
+### Five workers in the tile grid
+
+The lead Claude Code session gets `use codeman to start 5 claude workers, one per TODO item`,
+and five Claude Code workers power on, one per item, with all six agents working at once.
+
+![A real codeman skill run in the tile grid: the lead Claude Code session powers on as the only tile, the prompt use codeman to start 5 claude workers, one per TODO item is typed, then five Claude Code worker sessions power on as new tiles one after another with the CRT animation, and all six agents work at once](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-skill-grid-20261015.gif)
+
+Sessions an agent starts do not join the grid by themselves. In this recording each worker
+was put on the grid as it started, the way `Ctrl`+click or dragging its tab does it: see
+[Tile Grid](Tile-Grid).
+
+### Eight workers, eight tabs
+
+The same prompt with eight workers, in the normal view. Every worker gets its own tab, and a
+lineage line runs from the lead to each one, so you can see who spawned whom. Clicking a
+worker's tab shows it at work.
+
+![A real codeman skill run in the normal view: the prompt use codeman to start 8 claude workers, one per TODO item is typed, eight worker tabs power on left to right while lineage lines draw from the lead to each one, then clicking a worker tab shows a live Claude Code worker receiving its task](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-skill-tabs-20261015.gif)
+
+### Two CLIs from one prompt
+
+Workers do not have to run the same CLI as the lead. Here the prompt is
+`use codeman to have a dsh worker on qwen build search and a claude one build checkout`: a
+DeepSeek Harness worker on a local qwen model and a Claude Code worker power on side by side.
+
+![A real codeman skill run: one short prompt typed into Claude Code, the tile grid powering on, then a DeepSeek Harness worker on a local qwen model and a Claude Code worker powering on as new tiles, with lineage lines from the lead to both](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-skill-crt-20261010.gif)
+
+## Install it
+
+Pick one route. The skill only acts inside a Codeman session, so a global install is safe.
+
+| How                | Command                                                                         | Scope |
+| ------------------ | ------------------------------------------------------------------------------- | ----- |
+| Skills CLI         | `npx skills add Ark0N/Codeman --skill codeman -g`                               | Global, any skills-aware agent. The way to give it to pi. |
+| Claude Code plugin | `/plugin marketplace add Ark0N/Codeman`, then `/plugin install codeman@codeman` | Global, through Claude Code's plugin manager. `/plugin update codeman` follows releases. |
+| Bundled CLI        | `codeman skill install`                                                         | Global, at `~/.claude/skills/codeman`. |
+| Bundled CLI        | `codeman skill install --case <name> [--mode <mode>]`                           | One case. `--mode codex` (or any other run mode) writes it where that CLI looks for skills. |
+| Web UI             | **App Settings → Agents & CLIs → All agent CLIs → Codeman Agent Skill**         | Injects it into each case when a session is created, where that session's CLI looks: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI, OpenCode, Antigravity, Grok, DeepSeek and OMP. Off by default. |
+
+Use the plugin **or** `codeman skill install`, not both: a Claude Code with both lists the
+skill twice (`codeman` and `codeman:codeman`).
+
+The web UI route skips pi, because a project skill makes pi ask to trust the folder at
+startup. A pi or plain shell session uses the [`codeman agent`
+commands](Driving-Codeman-From-An-Agent#the-codeman-agent-commands) instead, which are the
+same verbs as shell commands.
+
+### Remove it
+
+`codeman skill uninstall [--case <name>]` reverses the CLI installs (with `--case`, every
+Codeman-managed copy in that case, whichever CLI's directory it sits in). It never touches a
+`skills/codeman` you wrote yourself.
+
+Turning the web UI setting back off **does not remove copies it already injected**, because
+a sweep at session start would pull the skill out from under other live sessions sharing
+that directory. Remove them per case with `codeman skill uninstall --case <name>`.
+
+## Then just ask
+
+These prompts work as written:
+
+| You say                                                                                   | What happens |
+| ----------------------------------------------------------------------------------------- | ------------ |
+| "What sessions are running right now?"                                                     | Lists them with name, mode and status. Read-only. |
+| "Use codeman to start 5 claude workers, one per TODO item."                                | One worker per item, each handed its task, answers gathered as they finish. |
+| "Start a shell worker on the `myapp` case, run the test suite, tell me if it passes."      | Spawns, waits on a completion marker, reads the exit code, cleans up. |
+| "Spin up 3 workers for lint, typecheck and tests, run them in parallel, report failures."  | One session per task, all started first, then gathered as each finishes. |
+| "Have a claude worker summarize `src/session.ts`, then close it."                          | Spawns, waits until the worker is ready, sends and waits, reads the answer, deletes the session. |
+| "Have a DeepSeek Harness worker build search and a claude worker build checkout."          | A mixed fleet: one worker per CLI, started in one go. |
+| "Watch session w4 and tell me if it gets stuck on a permission prompt."                    | Blocks on the `blocked` signal and brings the question to **you**. |
+
+Sessions the agent creates are deleted when it is done, so you can watch the tabs appear and
+disappear in the dashboard while it works.
+
+### A run, start to finish
+
+> **You:** spin up 3 shell workers, run lint / typecheck / the frontend syntax check in
+> parallel, and tell me which failed.
+
+```text
+lint       -> 9f2d8e5f   dispatched
+typecheck  -> aff9c691   dispatched     3 tabs appear in the dashboard
+syntax     -> be9f1f15   dispatched
+
+lint         DONE_lint_17909      rc=0
+typecheck    DONE_typecheck_3409  rc=0   gathered as each one finishes
+syntax       DONE_syntax_18501    rc=0
+
+deleted 9f2d8e5f, aff9c691, be9f1f15    tabs disappear
+```
+
+The `DONE_<task>_<random>` strings are the
+[split-marker trick](Driving-Codeman-From-An-Agent#the-split-marker-trick): a shell session
+has no "turn finished" signal, so the skill waits for a marker in the output, typed in two
+halves so that only the command's real output ever contains the joined string.
+
+## Which workers it can drive
+
+Any run mode installed on the machine can be a worker. Claude Code and DeepSeek Harness are
+the two with real completion signals (Claude's from its hooks, DeepSeek's from the harness),
+so the skill can wait for "turn finished" and read the answer as clean text. Every other CLI
+and plain shell sessions are synchronized on an output marker instead, which works the same
+from your side. See [Agent CLIs](Agent-CLIs) for the run modes.
+
+With Claude Code workers, where the installed Claude Code supports it, the lead can also
+message a worker directly instead of typing into its terminal.
+
+## What it will and will not do
+
+- **It self-gates.** Outside a Codeman session (`CODEMAN_MUX` unset) it refuses to act and
+  never guesses an API URL, so a global install costs an unrelated agent session nothing.
+- **Unprompted, it may only** start sessions, prompt them, and delete the ones **it created
+  in that conversation, by exact id**, behind a guard that refuses to delete the agent's own
+  session.
+- **It will not** answer another session's permission prompt on your behalf. It brings the
+  question to you instead.
+- **Only when you ask, naming the target:** deleting a case (which erases a real directory
+  of your code), bulk kills, respawn, Ralph, cron, the orchestrator, and settings changes.
+
+## When the agent is Codex
+
+Two things to know:
+
+- Codex's default sandbox blocks network access, even to this machine, so the skill needs
+  **Bypass approvals and sandbox** (App Settings, Codex).
+- Codex 0.162 runs its commands in a shared background process, whose Codeman variables can
+  belong to the session that started it.
+
+The skill checks for both and says so instead of acting.
+
+## What is in the skill
+
+| File | Contents |
+| ---- | -------- |
+| [`SKILL.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/SKILL.md) | Safety rules, the fast path (start N workers, task them, collect the answers) and the verb index. Always loaded. |
+| [`reference/verbs.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/verbs.md) | Every verb in detail: readiness, send-and-wait, markers, interrupts, cleanup. Loaded on demand. |
+| [`reference/recipes.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/recipes.md) | Worked flows: claude, DeepSeek Harness and shell workers, fan-out, watching a blocked worker, messaging. Loaded on demand. |
+| [`reference/endpoints.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/endpoints.md) | Endpoint tables, error codes, the signals each mode emits, capacity limits. Loaded on demand. |
+| [`reference/messaging.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/reference/messaging.md) | Talking to claude workers directly through Claude Code's cross-session messaging. Loaded on demand. |
+
+Only `SKILL.md` sits in the agent's context; the references load when a job needs them, so a
+quick run stays quick.
+
+## Read next
+
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the `codeman agent`
+  commands, the MCP server, and the raw HTTP rules the skill is built on.
+- [Tile Grid](Tile-Grid) - watching several workers side by side.
+- [The Dashboard](The-Dashboard) - tabs, lineage lines and status dots.
+- [Watching Agents Work](Watching-Agents-Work) - the subagents inside each session.

docs/wiki/Driving-Codeman-From-An-Agent.md

@@ -12,58 +12,19 @@ everything else.
 
 A skill in the `SKILL.md` format that Claude Code, Codex, Gemini CLI, OpenCode, Grok, OMP
 and most other agent CLIs read. It teaches the agent the whole API, so you ask in plain
-English instead of pasting endpoint documentation into prompts.
+English instead of pasting endpoint documentation into prompts:
 
-### Install it
+```bash
+codeman skill install    # or: npx skills add Ark0N/Codeman --skill codeman -g
+```
 
-| How          | Command                                                     | Scope                                                       |
+Then ask the agent in a Codeman session something like *"use codeman to start 5 claude
-| ------------ | ----------------------------------------------------------- | ----------------------------------------------------------- |
+workers, one per TODO item"*. It starts the workers, hands each one its task, gathers the
-| Skills CLI   | `npx skills add Ark0N/Codeman --skill codeman -g`            | Global, any skills-aware agent. The way to give it to pi.    |
+answers and deletes the sessions it created.
-| Claude Code plugin | `/plugin marketplace add Ark0N/Codeman`, then `/plugin install codeman@codeman` | Global, through Claude Code's plugin manager. `/plugin update codeman` follows releases. Pick this or `codeman skill install`, not both, or the skill is listed twice (`codeman` and `codeman:codeman`). |
-| Bundled CLI  | `codeman skill install`                                      | Global, at `~/.claude/skills/codeman`.                       |
-| Bundled CLI  | `codeman skill install --case <name> [--mode <mode>]`        | One case. `--mode codex` (or any other run mode) writes it where that CLI looks for skills. |
-| Web UI       | **App Settings → Agents & CLIs → All agent CLIs → Codeman Agent Skill** | Injects into each case when a session is created, where that session's CLI looks: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Gemini CLI, OpenCode, Antigravity, Grok, DeepSeek and OMP. Not pi: a project skill makes pi ask to trust the folder at startup. Off by default. |
 
-`codeman skill uninstall [--case <name>]` reverses the CLI installs (with `--case`, every
+**[The Codeman Skill](Codeman-Skill)** has the rest: recordings of real runs, every install
-Codeman-managed copy in that case), and never touches a `skills/codeman` you wrote yourself.
+route (Claude Code plugin, skills CLI, per case, the web UI setting), prompts that work as
-
+written, what it will and will not do on its own, and the notes for Codex. It drives
-Two things to know when the agent is **Codex**: its default sandbox blocks network access
-even to this machine, so the skill needs **Bypass approvals and sandbox** (App Settings,
-Codex); and Codex 0.162 runs its commands in a shared background process, whose Codeman
-variables can belong to the session that started it. The skill checks for both and says so
-instead of acting.
-
-### Then just ask
-
-| You say                                                                                 | What happens                                                                             |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| "What sessions are running right now?"                                                   | Lists them with name, mode, and status. Read-only.                                          |
-| "Start a shell worker on the `myapp` case, run the test suite, tell me if it passes."     | Spawns, waits on a completion marker, reads the exit code, cleans up.                       |
-| "Spin up 3 workers for lint, typecheck and tests, run them in parallel, report failures." | One session per task, all started first, then gathered as each finishes.                    |
-| "Have a claude worker summarize `src/session.ts`, then close it."                         | Spawns, runs the readiness ladder, sends and waits, reads the answer, deletes the session.  |
-| "Watch session w4 and tell me if it gets stuck on a permission prompt."                   | Blocks on the `blocked` signal and surfaces the question to **you**.                        |
-
-Sessions the agent creates get deleted when it is done. You can watch the tabs appear and
-disappear in the dashboard while it works.
-
-### What it will and will not do
-
-- **It self-gates.** Outside a Codeman session it refuses to act and does not guess an API
-  URL, so a global install costs an unrelated Claude Code session nothing.
-- **Unprompted, it may only** spawn sessions, prompt them, and delete ones **it created in
-  that conversation, by exact id**, behind a guard that refuses to delete the agent's own
-  session.
-- **It will not** answer another session's permission prompt on your behalf. It surfaces the
-  question instead.
-- **Deleting a case** (which erases a real directory of your code), bulk kills, respawn,
-  Ralph, cron, orchestrator, and settings writes all require you to ask, naming the target.
-
-Turning the setting back off **does not remove already-injected copies**, because a
-create-time sweep would yank the skill out from under other live sessions sharing that
-directory. Remove them per case with `codeman skill uninstall --case <name>`.
-
-The skill ships with the verb index always loaded, plus on-demand references for the verbs,
-worked multi-worker recipes, endpoint tables, and cross-session messaging. It drives
 DeepSeek Harness workers the same way it drives Claude ones (`spawn_workers alpha
 beta:deepseek` is a mixed fleet in one call), since those are the two modes with real
 completion signals.
@@ -281,6 +242,7 @@ failing the spawn, because a cosmetic field must never break a worker.
 
 ## Read next
 
+- [The Codeman Skill](Codeman-Skill) - the skill in action, its install routes and its limits.
 - [HTTP API](HTTP-API) - the endpoint map and the envelope.
 - [Hooks And Integrations](Hooks-And-Integrations) - events flowing the other way.
 - [Watching Agents Work](Watching-Agents-Work) - seeing the fan-out in the UI.

docs/wiki/FAQ.md

@@ -207,10 +207,13 @@ cover them properly.
 ### Can agents start and supervise other agents?
 
 Yes. Codeman ships an agent skill that lets an agent inside a session drive the HTTP API:
-list sessions, spawn workers, send prompts, and block until a worker's turn finishes. It is
+list sessions, spawn workers in any installed CLI, send prompts, and block until a worker's
-off by default and enabled per case.
+turn finishes. Install it once with `codeman skill install` or the Claude Code plugin, then
+ask in plain English, for example *"use codeman to start 5 claude workers, one per TODO
+item"*. The web UI setting that injects it into every new session's case is off by default.
 
-See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
+See [The Codeman Skill](Codeman-Skill), with recordings of real runs, and
+[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) for the other routes.
 
 ### Can I run a case in a container?
 

docs/wiki/Home.md

@@ -41,7 +41,8 @@ codeman web    # then open http://localhost:3000
 
 **Driving it from code**
 
-- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the bundled skill, worker sessions, wait primitives.
+- [The Codeman Skill](Codeman-Skill) - one prompt, a whole crew: an agent starting and supervising worker sessions.
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the `codeman agent` commands, the MCP server, wait primitives.
 - [HTTP API](HTTP-API) - the envelope, auth, the endpoint map, SSE events.
 - [Hooks And Integrations](Hooks-And-Integrations) - events flowing back into Codeman.
 
@@ -101,6 +102,7 @@ codeman web    # then open http://localhost:3000
 
 | Page                                                              | What it answers                              |
 | ----------------------------------------------------------------- | -------------------------------------------- |
+| [The Codeman Skill](Codeman-Skill)                                | How do I get an agent to start and run workers for me? |
 | [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent)    | How does an agent spawn and drive workers?   |
 | [HTTP API](HTTP-API)                                              | What can I call, and what comes back?        |
 | [Hooks And Integrations](Hooks-And-Integrations)                  | How do I wire Codeman into something else?   |

docs/wiki/Settings-Reference.md

@@ -146,7 +146,7 @@ instead of its native cloud backend. See [Custom Model Endpoints](Custom-Model-E
 | Allowed Tools                    | The list used by the explicit mode.                                                            |
 | Ralph / Todo Tracker             | Enables the Ralph loop surfaces.                                                               |
 | Agent Teams                      | Experimental teams. Also needs the CLI's own environment flag.                                 |
-| Codeman Agent Skill              | Under **All agent CLIs**. Injects the agent skill into each new session's case, where that session's CLI looks for skills (every CLI except Pi and a plain shell). Off by default. See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent). |
+| Codeman Agent Skill              | Under **All agent CLIs**. Injects the agent skill into each new session's case, where that session's CLI looks for skills (every CLI except Pi and a plain shell). Off by default. See [The Codeman Skill](Codeman-Skill). |
 | Remote auto-reconnect            | Reattaches dropped remote SSH sessions. On by default.                                         |
 | Nice priority / value            | Runs agent processes at a lower CPU priority.                                                  |
 | Default Codex model              | Model for new local Codex sessions; empty uses Codex's own config. Letters, digits, `.` `_` `-` `/` only. |

docs/wiki/_Sidebar.md

@@ -42,6 +42,7 @@
 
 **Automation**
 
+- [The Codeman Skill](Codeman-Skill)
 - [Driving It From An Agent](Driving-Codeman-From-An-Agent)
 - [HTTP API](HTTP-API)
 - [Hooks & Integrations](Hooks-And-Integrations)