From lodestone
Diagnose lodestone install issues — uv presence, venv state, MCP registration, DB writability, prewarm status, HF model cache, LLM provider config. Use when mcp__lodestone__* tools are missing, when /lodestone:doctor is invoked, or after a fresh /plugin install lodestone.
How this skill is triggered — by the user, by Claude, or both
Slash command
/lodestone:doctorThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Diagnose the lodestone install. Each section below runs a check; interpret the output and print one PASS/FAIL line per check, then a single fix line per FAIL. Be terse — no preamble, no recap. After diagnostics, run any applicable remediations in the order described in **Remediation order** below. Finish with a one-line overall verdict.
Diagnose the lodestone install. Each section below runs a check; interpret the output and print one PASS/FAIL line per check, then a single fix line per FAIL. Be terse — no preamble, no recap. After diagnostics, run any applicable remediations in the order described in Remediation order below. Finish with a one-line overall verdict.
uv on PATH!command -v uv 2>&1 || echo "uv not on PATH"
Required for the prewarm hook and venv. If missing, fix line is: install uv from https://astral.sh/uv and restart Claude Code.
!bash "${CLAUDE_SKILL_DIR}/scripts/check-venv.sh"
If missing, the prewarm hook hasn't completed. Most common cause: /plugin install lodestone was run mid-session and /reload-plugins doesn't fire SessionStart hooks. Fix line: Claude will run the prewarm hook now — see Remediation below; after it completes run '/reload-plugins'.
!bash "${CLAUDE_SKILL_DIR}/scripts/check-install-hash.sh"
Informational. Presence of a hash means a uv sync has succeeded for the current pyproject/lock.
!bash "${CLAUDE_SKILL_DIR}/scripts/check-db.sh"
Informational. Empty DB is fine — mcp__lodestone__overview works against an empty corpus.
!claude mcp list 2>&1 | grep -i lodestone || echo "lodestone not in 'claude mcp list' output"
If absent: the plugin's root .mcp.json didn't register. Fix line: open /mcp -> find lodestone -> enable or reconnect; if not listed, confirm '/plugin install lodestone' completed and the plugin is enabled (/plugin), then restart Claude Code.
!bash "${CLAUDE_SKILL_DIR}/scripts/check-hf-cache.sh"
Two CPU-only HuggingFace models are required at ingest time: BAAI/bge-small-en-v1.5 (~133 MB, embeddings) and fastino/gliner2-large-v1 (~285 MB, entity extraction). The script uses huggingface_hub.snapshot_download(local_files_only=True) to verify completeness — same call path the loader libraries use, just with the network door closed — so partial downloads and missing variant files surface as "NOT cached" rather than false-positive PASSing on directory existence alone. If both report "cached", PASS. If either reports "NOT cached" (or "cached (loose check…)" when the venv isn't ready yet — that's a weaker check), FAIL — fix line: Claude will download the missing model(s) now — see Model download remediation below.
!bash "${CLAUDE_SKILL_DIR}/scripts/check-config.sh"
The output is a single JSON line. Parse config_status:
"ok" → PASS (config exists, provider+model set, matching env var present)."missing" with providers_with_keys: [] → FAIL. Fix line: set one of $OPENAI_API_KEY, $ANTHROPIC_API_KEY, or $GEMINI_API_KEY in your shell, then re-run /lodestone:doctor. Stop — no remediation possible."missing" or "incomplete" with at least one key present → FAIL. Fix line: Claude will walk you through provider/model selection — see Provider + model setup remediation below."malformed" → FAIL. Fix line: ${config_path} is malformed TOML — open it manually and fix the syntax, then re-run /lodestone:doctor. Stop — no remediation possible."key_missing" → FAIL. Fix line: config pins provider=${config_provider} but its env var is not set in this shell — either export the key or edit ${config_path} to pick a different provider, then re-run /lodestone:doctor. Stop — no remediation possible.Run remediations in this order. Skip any whose check PASSed.
run_in_background: true to kick off the HF download (using the --models-only flag — see Remediation — Model download). Immediately run the Provider + model wizard while the bytes stream in. After writing config.toml, wait for the background Bash to complete — you'll be notified automatically; do not poll.Skip this section unless the Plugin venv check above FAILed.
Claude — to fix a missing venv, invoke the Bash tool (not the ! injection mechanism) with:
bash "${CLAUDE_SKILL_DIR}/../../bin/lodestone-prewarm.sh"
The prewarm script self-discovers its plugin root from its own location, so no env-var setup is needed. If it exits non-zero, surface the error and stop — likely uv is not on PATH or pyproject.toml/uv.lock is missing.
After the prewarm finishes (look for [lodestone] Dependency install complete.), tell the user to open /mcp -> find lodestone -> enable or reconnect so the MCP server retries against the now-populated venv. If that doesn't surface mcp__lodestone__* tools, fully quit and relaunch Claude Code (not /reload-plugins).
Skip this section unless the HuggingFace model cache check above FAILed.
Before invoking the Bash tool, tell the user:
Downloading lodestone models (~400 MB total: BAAI/bge-small-en-v1.5 + fastino/gliner2-large-v1). This can take a few minutes depending on your connection — progress isn't visible here, but the download is running.Starting the ~400 MB model download in the background (BAAI/bge-small-en-v1.5 + fastino/gliner2-large-v1) — while it runs, I need a couple quick choices from you for the LLM config.Then invoke the Bash tool (not the ! injection mechanism) with this command:
uv run --no-sync --directory "${CLAUDE_SKILL_DIR}/../.." python -m _system.scripts.validate_models --models-only
Parallel mode: when the Provider config check also FAILed, set run_in_background: true on the Bash call so the wizard can run while the download streams. Otherwise run in the foreground.
The --models-only flag skips the provider-config check inside validate_models (doctor's own LLM provider config check covers it). The script is idempotent — any already-cached model is a no-op, so a partial cache resumes safely. On success the script prints <model-id>: present for both models. If it exits non-zero, surface the error and stop — likely a network or HuggingFace issue.
Skip this section unless the LLM provider config check returned a "missing" or "incomplete" status with at least one provider key present. The "malformed", "key_missing", and zero-keys cases are not remediable here — they require user action.
Re-read the JSON output from check-config.sh (above) to recover providers_with_keys, config_status, config_provider, and config_path. Then:
references/provider_select.md to resolve a single provider. That reference handles the 0 / 1 / many providers cases via AskUserQuestion.references/model_select.md to pick a model and write ~/.config/lodestone/config.toml. That reference handles the WebSearch + AskUserQuestion + Write flow.After the config is written, if you launched the HF download in background, wait for it to finish (you'll be notified). Then continue to the verdict.
After printing PASS/FAIL per check, the fix line per FAIL, and (if applicable) any remediation results, print one final line:
lodestone looks healthy — if mcp__lodestone__* tools still don't appear, open /mcp -> find lodestone -> enable or reconnect; if that doesn't surface them, restart Claude Code once more (full quit, not /reload-plugins).prewarm completed — open /mcp -> find lodestone -> enable or reconnect to retry against the now-populated venv. If tools still don't register, **fully quit and relaunch Claude Code** (not /reload-plugins).lodestone is ready — no restart needed; the next /deep-sota run will use the freshly-written config and cached models.fix the FAIL(s) above per their instructions, then re-run /lodestone:doctor.fix the FAILs above (top to bottom), then re-run /lodestone:doctor.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub piercelamb/lodestone --plugin lodestone