flywheel

See the retrieval-flywheel status and trigger an incremental utterance-generation run. Use this skill when the user asks about the flywheel, "how many skills have utterances / triggers", "flywheel cov

SKILL.md

GitHub

skill-concierge flywheel

Surface and drive the retrieval flywheel — the utterance layer (ADR-0026). For each indexed skill the flywheel stores short, LLM-generated "how a user actually asks for this" phrases (English + Vietnamese) under llm_triggers in the canonical corpus ~/.claude/skill-concierge/triggers.json (operator home — personal data, kept out of the public repo since 0.37.0); those phrases lift retrieval recall. Generation is offline and incremental — the generator content-hashes each skill, so only new or changed skills ever hit the LLM. Skills with no utterances still work (graceful fallback to description+body retrieval); the flywheel just makes them easier to find.

This skill is the seamless surface for two things: seeing where the flywheel stands, and running an incremental generation pass.

Steps

  1. Status (default, read-only) — endpoint config + reachability and per-skill coverage:

    python3 "$CLAUDE_PLUGIN_ROOT/scripts/flywheel.py"
    

    It prints the full observability card:

    • Endpoint — the configured FLYWHEEL_LLM_ENDPOINT + model, whether an API key is set, the schema mode, and a live ping() reachability result.
    • Coverage — installed N/M plus one line per configured external catalog (antigravity: N/M), with missing skills by name. Indexed names come from the live Qdrant claude_skills index; covered = a non-empty llm_triggers.triggers in the canonical corpus at ~/.claude/skill-concierge/triggers.json.
    • State — lock free vs IN PROGRESS; while a run holds the lock (including the detached auto-flywheel pass) status samples coverage twice (5s) and prints live throughput + ETA — the only way to observe a detached run's progress.
    • Auto-flywheel — gate value, workers/cap/throttle config, throttle-window countdown from the machine stamp, and the last hook log line.
    • Recent runs — the last 3 manifest runs (model, generated/error/skipped, coverage, last_error) plus per-skill error detail from the most recent run.
  2. Generate (--generate) — fill utterances for new/changed skills, then reindex:

    python3 "$CLAUDE_PLUGIN_ROOT/scripts/flywheel.py" --generate
    

    It preflights the endpoint with ping() and fails loud if unreachable (pointing at the provider-setup doc — do not generate against a dead endpoint). On success it runs BOTH incremental generators — the eval scenarios (llm_eval_gen.py) and the utterance triggers (llm_triggers.py), under the engine venv — then skill-search --reindex so the new utterance points land live, and prints before/after coverage. Only new/changed skills call the LLM (each generator content-hashes the description), so re-running when nothing changed is cheap and safe. Every run is recorded to the global manifest (below).

    Flags: --triggers-only skips the measurement-only scenario pass (triggers are what serve retrieval); --limit <N> caps how many skills are processed in one pass; --rate <seconds> spaces out LLM calls when sharing a busy endpoint; --catalog <alias> runs generation against ONE external catalog's <alias>:* skills instead of installed skills (the ADR-0031 D10 deferral, owner-commissioned — default coverage counts stay installed-only); --workers <N> fans the LLM network phase out over N concurrent calls while all file writes stay single-threaded (default 1 = sequential; effective gateway load scales with N). Full rationale: ADR-0043.

Auto-flywheel (background, default ON) + the run manifest

You usually do not need to run --generate by hand. The auto_flywheel SessionStart hook (ADR-0027, gated SKILL_AUTO_FLYWHEEL, default ON) does it for you: when an endpoint is configured and reachable, on session start it detects skills missing utterances, generates for just those, and reindexes — detached and non-blocking (it never delays the session), throttled (AUTO_FLYWHEEL_THROTTLE_S, default 6h) and capped per run (AUTO_FLYWHEEL_MAX_PER_RUN, default 25). If no endpoint is configured or it's unreachable, the hook is a silent no-op — the graceful description+body fallback is untouched.

Because the run is a background process, its results are written to a global manifest at ~/.claude/skill-concierge/flywheel-manifest.json — timestamp, endpoint+model, per-skill status, totals, coverage, last error (last 20 runs). Any agent or the user can read it to verify what the flywheel did, without watching a live process. Status mode (above) prints the last run from it, and doctor reports it too.

When it can't run

  • Endpoint unreachable → --generate fails loud. Configure a provider first; the three documented setups (LM-Studio, Ollama, OpenAI-compatible gateway) live in ../../references/flywheel-llm-providers.md. The four FLYWHEEL_LLM_* env vars belong in the machine's cross-harness env file ~/.config/harness-env.sh (sourced by ~/.zshenv + the bash entry files), NOT in ~/.claude/settings.json env — the settings env block reaches Claude sessions only, so a Codex session's doctor reported "not configured" against a fully configured machine and its auto_flywheel silently no-opped (caveats §20). Status mode still works — it just reports NO.
  • Engine venv missing → --generate points you at the skill-concierge:setup skill, which builds the venv. After a reindex, retrieval picks up the new points immediately (no restart needed).

Doctor's check_flywheel() reports the same coverage + reachability inside the normal health workflow; this skill is the place to act on it.