benelser/docent / packages/agent/skills/docent-doctor
docent-doctor
FlaggedFirst-run bootstrap and ongoing health check for docent. On first invocation, clones the docent engine into ~/.local/share/docent/engine, installs every cascade dependency (uv, ffmpeg, Kokoro voice weights, Remotion), and puts the `docent` CLI on PATH. On subsequent invocations, just runs `docent doctor --install --yes` to verify and repair. Use when the user says "/docent-doctor", asks to set up docent, hits a missing-dependency error from another docent skill, or wants to confirm the cascade can render end-to-end.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
SKILL.md
View on GitHub---
name: docent-doctor
description: First-run bootstrap and ongoing health check for docent. On first invocation, clones the docent engine into ~/.local/share/docent/engine, installs every cascade dependency (uv, ffmpeg, Kokoro voice weights, Remotion), and puts the `docent` CLI on PATH. On subsequent invocations, just runs `docent doctor --install --yes` to verify and repair. Use when the user says "/docent-doctor", asks to set up docent, hits a missing-dependency error from another docent skill, or wants to confirm the cascade can render end-to-end.
---
# docent-doctor — bootstrap or verify the docent environment
You are responsible for getting docent ready to render a film, or for
confirming it still is. Two paths to walk depending on whether docent is
already on PATH:
## Path A — first run (`docent` not on PATH)
The user just installed the skills via `apm install` and has never used
docent before. You need to clone the engine, bootstrap the cascade, and
put the `docent` CLI on PATH.
Detect this case by running `command -v docent`. If it returns nothing,
take Path A.
Execute these steps in order. Walk through each with the user so they
see what's happening; do not paste the whole block silently.
1. **Pick the engine location.** Default:
```bash
DOCENT_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/docent/engine"
```
Tell the user this is where the engine will live — about 1 GB after
`bun install` + `uv sync` + Kokoro weights. They can override by
exporting `DOCENT_HOME` before re-running.
2. **Verify bun is on PATH.** If `command -v bun` returns nothing, stop
and tell the user:
```
docent requires bun. Install it first:
curl -fsSL https://bun.sh/install | bash
exec $SHELL -l
Then re-invoke /docent-doctor.
```
Bun is the only prerequisite docent itself can't bootstrap (it is
the runtime that runs the bootstrap).
3. **Clone the engine** (or fast-forward an existing clone):
```bash
mkdir -p "$(dirname "$DOCENT_HOME")"
if [ -d "$DOCENT_HOME/.git" ]; then
git -C "$DOCENT_HOME" pull --ff-only
else
git clone https://github.com/benelser/docent "$DOCENT_HOME"
fi
```
4. **Bootstrap the cascade.** This is the long step — `uv sync` pulls
torch + transformers + kokoro, Kokoro downloads ~300 MB of voice
weights, and `bun install` materializes Remotion. Allow 3-8 minutes
on a warm machine, longer on a cold one.
```bash
cd "$DOCENT_HOME" && bun packages/agent/scripts/doctor.ts --install --yes
```
That command installs uv, ffmpeg, gh, apm if missing; writes
`~/.local/bin/docent` (the shim that lets you call `docent <cmd>`
from any cwd); and records `DOCENT_HOME` at
`~/.config/docent/home`. Show the user the live output — every
step is labeled.
5. **Verify the shim is callable.** From the user's original cwd:
```bash
command -v docent && docent env | head -5
```
If `command -v docent` returns nothing, the shim is installed but
`~/.local/bin` is not on PATH. Print:
```
Add ~/.local/bin to PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec $SHELL -l
```
and stop.
6. **Hand back.** Print:
- the engine location (`$DOCENT_HOME`)
- "Ready" if every required check is green; otherwise list the
failing check ids
- "Next: `/docent-explain <subject>`" as the next step
## Path B — re-verify (`docent` already on PATH)
The user has docent installed and wants a health check or a repair.
```bash
docent doctor --install --yes
```
This re-runs every check and installs anything missing — Kokoro
weights got evicted, `node_modules` got blown away by a clean-slate,
ffmpeg got upgraded oddly, etc. Show the user the raw output (it is
already formatted with per-stage grouping and remediation hints on
every failure).
If `docent doctor` exits 0, print **Ready** and suggest
`/docent-explain <subject>`.
If it exits non-zero, list the failing check ids by stage so the user
can resume mid-setup, and explain what each one means in one line.
## What "ready" means
Required by cascade stage:
- **system**: `bun`, `git`
- **survey**: at least one of `claude` or `codex` on PATH (the agent
that authors the spec); `apm` (the install channel)
- **tts**: `uv`, the `.venv` materialized, the Kokoro voice weights
cached
- **render**: `ffmpeg`, `ffprobe`, Remotion (from `bun install`), and
the `docent` shim on PATH
Optional (warnings, not failures): `gh-auth` (interactive — `docent
ar` and the PR poster need it eventually), `manim` (only films with
a `manim/<id>` directory use it).
## Codex-specific install behaviors (worth flagging to the user)
These are not docent bugs — they are how the `codex plugin` CLI behaves
today. Knowing them up front saves debugging time when something is
silently wrong:
- **`marketplace.json` `source.path` must be relative**, not absolute.
An absolute path is silently accepted by `codex plugin marketplace add`
but `codex plugin list -m <name>` then shows "no plugins found in
marketplace `<name>`" — no error, no warning. The docent repo's
`.agents/plugins/marketplace.json` uses `./packages/agent` (relative)
for this reason.
- **The marketplace's `name:` field is the collision key**, not the
directory path. If the user already has a marketplace named `docent`
(e.g. from a prior install), `codex plugin marketplace add <newpath>`
refuses to add a second one with the same name. They can either
`codex plugin marketplace remove docent` first, or accept that the
existing one will be re-resolved.
- **`codex plugin remove docent-agent` leaves the cache dir on disk**.
Cached files live at `~/.codex/plugins/cache/<marketplace>/`. If a
re-install gets stuck reading stale skills, the fix is
`rm -rf ~/.codex/plugins/cache/docent/` and re-running `codex plugin
add docent-agent@docent`.
If the user reports "I installed but `/docent-doctor` doesn't show up in
Codex", check these three before anything else.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |