Setup

---
description: "Verify the biome-format hook's runtime prerequisites and configuration for this repository. Use when: 'set up biome-format', 'configure biome-format', 'is biome-format working', formatting silently isn't happening, or the hook reported a missing prerequisite. Actions: check (read-only verification, default) | apply (resolve what check found). Re-runnable and safe."
argument-hint: "[check|apply] [install-biome]"
user-invocable: true
disable-model-invocation: true
shell: bash
---

## Pre-computed context

`check`'s `jq` probe ran at load time. Read this row instead of re-issuing it; it shows
the tool's path when present, or `absent` when missing:

- `jq`: !`{ command -v jq 2>/dev/null || echo "absent"; }`

A row reading `[shell command execution disabled by policy]` carries no result: run that tool's
`command -v` probe via Bash instead.

## Purpose

Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md`
"Setup is explicit and repeatable" in the marketplace repository): `check` inspects and
reports, `apply` resolves. This plugin owns no consumer-project configuration. Rules come
from the repository's own Biome config, and the only tunable is the native `userConfig`
toggle, so `apply` is guidance-and-verify, with exactly one write path: the explicitly
invoked `apply install-biome` dependency install described below.

Action routing: no argument or `check` runs the check; `apply` runs the check first, then
remediation; `apply install-biome` additionally authorizes the consumer-repo dependency
install described below. All are non-interactive. Never prompt when the action is given.

## `check` (read-only)

The hook script (`${CLAUDE_PLUGIN_ROOT}/hooks/biome-format.sh`) is the single source of
truth for what it requires and how it resolves things.

**Read it first.** Probe what it actually does, don't recite this file. Then read the
pre-computed `jq` row, run the remaining probes via Bash, and report a PASS/FAIL/INFO
table with one remediation line per FAIL. Do not modify anything.

When the plugin's toggle is disabled, every prerequisite absence except Node.js (probe 7)
downgrades from FAIL to INFO. The hook exits through its enabled-gate before probing
anything, so a deliberately disabled plugin is not broken. Report those probes
informationally and note that re-enabling restores the FAIL semantics. Node.js stays FAIL
when disabled: the runner must start `node` before `exec-bash.mjs` can evaluate the gate.

1. **Bash version.** Check against the hook's documented floor (README Requirements),
   noting any features the hook degrades without (for example telemetry's `EPOCHREALTIME`,
   Bash 5.0+).
2. **`jq`.** The pre-computed `jq` row. FAIL if absent: the hook then skips with a visible
   notice instead of formatting (README Requirements states how often the notice repeats).
3. **Biome binary.** Resolve it exactly the way the hook's resolution code does: its
   repo-local install walk (the `node_modules/.bin` path it tests, walking up from the
   edited file toward the repo root) and then `PATH`. Test only what the hook tests. A
   binary the hook would not accept must not PASS here. FAIL when nothing the hook would
   resolve is present while a Biome config governs the repo; the hook then emits a visible
   skip notice instead of formatting (README Requirements states how often it repeats). The
   `SessionStart` probe resolves biome separately: read
   `local_bin` in `${CLAUDE_PLUGIN_ROOT}/prerequisites.json` and `findLocalBin` in
   `${CLAUDE_PLUGIN_ROOT}/lib/prerequisites.mjs` for its walk limit and file tests
   and compare them with the hook's, instead of assuming they match. The probe does not check
   for a Biome config, so it reports a missing biome in repositories with no `biome.json` too;
   only the per-edit hook's skip notice is opt-in gated. A PASS here means the hook resolves it.
4. **Consumer Biome config.** Mirror the hook's opt-in walk: it records the topmost
   governing config found walking from the edited file's directory up to the repo root, and
   deliberately accepts only the config names the hook treats as the opt-in. Read the hook:
   the hidden dotted variants are intentionally excluded. Report the governing config the
   walk discovers, or INFO that none exists. Absence is the opt-out by design, so the
   plugin is inert (INFO, not FAIL), matching the README's "ships no rules of its own"
   stance.
5. **Hook toggle and gitignore option.** Report the effective `biome_format_enabled` value:
   `${user_config.biome_format_enabled}` (unexpanded or empty means default `true`), and the
   effective `biome_format_lint_gitignored` value:
   `${user_config.biome_format_lint_gitignored}` (unexpanded or empty means default `false`).
6. **Hook registration.** INFO: confirm the plugin is enabled for this project
   (`/plugin` → Installed) rather than parsing settings files.
7. **Node.js.** Run `command -v node` via Bash. FAIL when absent: every hook launch goes
   through `node hooks/exec-bash.mjs`, so a missing `node` is a hook launch error, not a skip
   notice. Bash's `PATH` can differ from the one Claude Code resolves hook commands with (a
   shell initializer such as nvm may add Node only to Bash; see
   `docs/formatter-path-probes.md`), so a PASS means Node is on Bash's `PATH` only. Say
   so, and report INFO that hook availability is not established when the hooks still fail
   to start.

## `apply` (idempotent)

Run `check`, then for each FAIL offer the resolution. Never install anything without the
consumer's explicit go-ahead in the invocation. `apply install-biome` adds
`@biomejs/biome` as a dev dependency in the consumer repository **using the repository's
own package manager**, resolved in order: lockfile (`pnpm-lock.yaml` → `pnpm add -D`,
`yarn.lock` → `yarn add -D`, `bun.lock`/`bun.lockb` → `bun add -d`, `package-lock.json` →
`npm install --save-dev`), then the `package.json` `"packageManager"` field when no
lockfile exists, then npm only when neither signal is present. With no `package.json`, an
ambiguous multi-lockfile state, or a lockfile that contradicts `packageManager`, stop with
manager-specific guidance instead of guessing. Never introduce a competing lockfile. The
change is stated before running. For a Yarn repository, don't infer the linker. Ask the
repo's own Yarn: run `yarn config get nodeLinker` in the repo. `pnp` (Berry's default when
unset) → skip the install and give guidance, because Plug'n'Play generates a loader file,
not the `node_modules/.bin` shim the hook resolves; install `@biomejs/biome` on `PATH` or
switch the linker. `node-modules`/`pnpm`, or Yarn Classic (which has no such setting and
always materializes `node_modules`) → install. The verify-after-remediation rule below is
the backstop when an install still yields no usable shim. After ANY remediation, re-run the
relevant `check` probe live via Bash (a pre-computed row predates the remediation) and report
its actual result. Never claim resolved on the install
command's exit code alone. For everything else `apply` only points:

- missing `jq` / Bash: platform install instructions from the README Requirements section;
  this skill never installs system packages.
- toggle off: reconfigure through Claude Code's native flow, per the marketplace's
  plugin-reconfiguration convention
  (<https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-reconfiguration/README.md>,
  which owns the verified-version record): interactive
  `/plugin configure biome-format@<marketplace>` any time, or headless
  `claude plugin install biome-format@<marketplace> -s <scope> --config biome_format_enabled=true`
  (repeatable per key). Against an already-installed plugin it prints `already installed`
  **and still writes the value**. Do **not** uninstall to reconfigure: that drops this plugin's
  entire stored `pluginConfigs` entry, resetting every option in the README's Options reference
  to its manifest default. `-s` defaults to `user`; pass the scope `claude plugin list` reports
  for this plugin, and run from that project's directory for a `project`/`local` scope, or the
  rerun adds a second install record at the scope passed and enables the plugin there; the
  value itself always lands in user settings. A rejected value prints a warning yet exits 0,
  so read the output. This skill never writes user settings or
  `pluginConfigs`. Afterwards rerun `check` in a **fresh session**. The rendered
  `${user_config.*}` is injected at skill load and each hook receives its
  `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at session start, so a same-session
  `check` still reports the OLD value; report the observed effective value, never an
  unobserved change.
- no Biome config: offer to create a minimal `biome.json` in the repository root only when
  explicitly asked. The plugin imposes no rules of its own.

Re-running `apply` after everything passes changes nothing and reports "already configured".

## What this skill does NOT do

- Run the formatter. Editing any supported file exercises the hook end-to-end.
- Write the plugin cache, Claude Code user settings, or `pluginConfigs`.
- Download or execute tools during `check`; network use happens only in an explicitly
  requested `apply install-biome` inside the consumer repository.