toolkit

Scenario · Before you touch a site

A skill just errored, or I'm new here

“It broke.” Or, on a new machine: “How do I get this working?”

When something in the toolkit errors out, or a new machine can't get it running at all, the instinct is to start reading the failing code — but most reported breakage turns out to be an install problem: a stale checkout, a missing key, an integration that's simply not configured yet and is behaving exactly as designed. This checks the install itself first — what's linked, what's set, what's out of date — which resolves most reported issues in seconds and saves the deeper investigation for the cases that are actually a real defect.

What to ask for

Setup & doctorThe toolkit's friendly front door, onboarding guide and doctor — routes a business outcome to an approved workstream before a focused capability; guides setup, use, maintenance and contribution; and diagnoses agent links, masked key status, checkout freshness, and Node/OS.

See it work

A real run of Setup & doctor:

Setup & doctor · setup-and-doctor — checking your toolkit …

READY
  · installed for Claude Code + opencode
  · 19/35 optional key(s) set (most skills need none)
  · wiki enrichment on — reports link your team wiki

  Claude Code  69/96 linked
  opencode     69/96 linked
  keys         19/35 set (your own; add via node scripts/setup-keys.mjs)
  wiki         on — reports link your team wiki

  text:   ./out/setup-and-doctor-setup-and-doctor.txt
  report: ./out/setup-and-doctor-setup-and-doctor.html

The captured report, exactly as a run hands it to a client —open the full report ↗

Two situations, one entry point, because they are the same question: is the toolkit set up correctly on this machine? Most reported breakage is an install problem rather than a defect, and the order below is cheapest-first for that reason.

  1. Run the doctor before reading any code. It reports which agents have the skills linked, which API keys are present (values hidden), whether the checkout is behind the remote, and the Node and OS versions. A stale checkout and a missing key account for most of what gets reported as a bug.
  2. Check whether the skill is inert rather than broken. Several skills are optional integrations that do nothing without their environment variables, by design. An inert skill reports that it is inert; it is not a failure and the fix is configuration.
  3. Read the verdict, not the absence of output. BLOCKED means bot protection refused the fetch, SKIPPED means a dependency is missing, INFO means the skill does not grade. None of these is a FAIL, and treating them as one sends the investigation somewhere pointless.
  4. Reproduce with the exact command and target. A skill that fails on one URL and passes on another is reporting something about the URL. This is also the information any fix will need.
  5. [manual] Decide whether this is an install problem, a target problem, or a defect. The first two are the common cases and end here. Only the third continues.
  6. Capture the scenario and offer the fix upstream. For a genuine defect, the doctor’s report-a-bug path records the exact command, target and output, and a reviewed pull request goes upstream — never automatically sent.

Cheapest cause first

The instinct on an error is to read the skill’s source. The doctor takes seconds and eliminates a stale checkout, an unlinked skill and a missing key — which is what it usually was. Step 1 is first because skipping it is how an afternoon gets spent on a configuration problem.

What this does not cover

Fixing the skill. The doctor reports the state of the install — which agents have skills linked, which keys are set, whether the checkout is behind the remote, the Node and OS versions — and captures the failing scenario. Repairing a genuine defect is a code change, and whether one is warranted is a judgement about the skill, not about the install.

← All scenarios