agentleFS
Othmane-KhadriOthmane-Khadri/YALC-the-GTM-operating-system/.claude/skills/run-doctor/SKILL.md

run-doctor

Skill298 starsChanged 6 months agoMITView on GitHub

Run the GTM-OS health check across all 5 diagnostic layers (environment, database, configuration, provider connectivity, runtime state). Use when the user says 'is YALC working', 'diagnose YALC', 'check YALC health', 'is everything configured', 'run the health check', or 'are my keys set up'. Read-only — never writes anything. Surfaces /keys/connect/<provider> URLs alongside any failed provider so the user has a one-click path to fix.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when the user says:

    line 13
  2. Distinctive:

    Onboarding interruption guard: Run:

    line 45
  3. Distinctive:

    Don't run the dashboard command unless they say yes.

    line 133
  4. Very specific:

    If the inline runner errors out (e.g., the import path moves, the function signature changes, an unhandled exception escapes runDoctor), …

    line 139

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Run Doctor

I'll run the 5-layer health check and tell you what's missing. This is the read-only diagnostic that proves YALC is wired up correctly — environment file, SQLite schema, framework + user config, live provider connectivity, and runtime state. Nothing here writes to disk or burns credits.

When This Skill Applies

Use this skill when the user says:

  • "is YALC working"
  • "diagnose YALC"
  • "check YALC health"
  • "is everything configured"
  • "run the health check"
  • "are my keys set up"

NOT this skill (use debugger instead):

  • A specific command failed — debugger walks the error funnel layer by layer.
  • "fix", "not working", "broken", "troubleshoot" — those route to debugger.

NOT this skill (use setup instead):

  • "set up YALC" — that's the onboarding flow.

What This Skill Does

  1. Imports the runDoctor function from src/lib/diagnostics/doctor.ts directly (no fresh CLI subprocess).
  2. Captures the printed health check output by intercepting console.log and process.exit.
  3. Renders a clean per-layer summary: PASS / FAIL / WARN / SKIP for each check.
  4. For any FAIL'd or WARN'd provider, surfaces the matching /keys/connect/<provider> URL (the URL hint A5 added).
  5. Offers to walk you through fixing each failure — typically by opening the relevant /keys/connect/... route in your browser via yalc-gtm dashboard --route /keys/connect/<provider>.

What This Skill Does NOT

  • Modify env files, configs, or the database. Read-only.
  • Send any external requests beyond the live provider probes that doctor itself runs.
  • Auto-fix anything. All fixes need your approval.

Pre-flight (do this before step 1)

Onboarding interruption guard. Run:

test -f ~/.gtm-os/.in-flight-setup && echo "BLOCKED" || echo "OK"

If BLOCKED, surface a soft warning: setup is mid-flight and the diagnostic snapshot may be incomplete (config + DB are still being assembled). Since this skill is read-only and never writes anything, ask the user whether to (a) run anyway against the in-flight state, or (b) finish yalc-gtm setup --resume first and re-invoke. Default to (b) unless the user explicitly opts in to (a).

Workflow

Step 0: No user input needed

This is a read-only command. Skip straight to step 1.

Step 1: Generate the inline runner

Generate /tmp/yalc-skill-run-doctor.mjs from the gtm-os root (~/Desktop/gtm-os/). The runner imports runDoctor directly (the import-direct pattern from 0.13.0), monkey-patches console.log and process.exit so the output is collected as structured lines, and prints JSON to stdout.

Important — the import path must be absolute. tsx resolves relative imports against the script's own directory, not against cwd. Since the runner lives in /tmp/, a relative ./src/... import resolves to /tmp/src/... and fails. Build the runner with the absolute path baked in via heredoc expansion:

cd ~/Desktop/gtm-os && cat > /tmp/yalc-skill-run-doctor.mjs <<RUNNEREOF
import { runDoctor } from '\${PWD}/src/lib/diagnostics/doctor.ts'

const lines = []
const origLog = console.log
const origExit = process.exit

console.log = (...args) => {
  lines.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' '))
}

let exitCode = 0
process.exit = (code) => {
  exitCode = typeof code === 'number' ? code : 0
}

let runError = null
try {
  await runDoctor({ report: false })
} catch (err) {
  runError = err instanceof Error ? { message: err.message, stack: err.stack } : { message: String(err) }
}

console.log = origLog
process.exit = origExit

process.stdout.write(JSON.stringify({ exitCode, runError, lines }, null, 2))
process.stdout.write('\n')
RUNNEREOF

Note: do not add a --json flag — runDoctor does not accept one; this wrapper is how we get JSON.

Step 2: Run it

From the gtm-os root (~/Desktop/gtm-os/):

npx tsx /tmp/yalc-skill-run-doctor.mjs

Step 3: Parse the JSON output

The runner emits { exitCode, runError, lines }. The lines array is the verbatim sequence of console.log calls doctor made — including the layer headers (── Environment ──, ── Database ──, etc.), the per-check rows ( ✓ [OK ] ANTHROPIC_API_KEY, ✗ [FAIL] Crustdata), and the summary block.

Parse it like this:

  • A line starting with ── and ending with ── opens a new layer.
  • A line starting with ✓ [OK ], ✗ [FAIL], ! [WARN], or ✓ [SKIP] is a check row. The bracketed token is the status; the rest is the check name.
  • Indented lines (prefix ) that follow a non-PASS check carry the detail/explanation.
  • The summary lines (X passed, Y failed, Z warnings, W skipped) appear under ── Summary ──.
  • A trailing line of MCP-loader noise ([mcp-loader] ...) may appear between the layer headers — ignore it.

Step 4: Render a clean diagnosis

Group checks by layer. For each layer, list the checks in order with their status. For any check whose detail contains Fix: http://localhost:3847/keys/connect/<provider>, surface the URL prominently next to the failing line.

See references/example-output.md for a full rendered example.

End the summary with the overall verdict: healthy / minor warnings / N issues need attention.

Step 5: Offer to fix any FAIL or provider-related WARN

For each FAIL or WARN row whose detail includes a /keys/connect/<provider> URL, ask the user:

"Want me to open /keys/connect/<provider> in your browser? I'll run yalc-gtm dashboard --route /keys/connect/<provider>."

Don't run the dashboard command unless they say yes. The dashboard command (A2) starts the SPA on port 3847 and routes the user to the connect screen for that provider.

For non-provider failures (missing .env file, missing core tables, malformed YAML), surface the specific recovery hint the doctor itself emitted in the detail line — those are already actionable.

Step 6: Fallback path

If the inline runner errors out (e.g., the import path moves, the function signature changes, an unhandled exception escapes runDoctor), fall back to the CLI:

npx tsx src/cli/index.ts doctor

The CLI command takes only --report (no --json flag). Its stdout is the same human-readable output doctor would have printed; parse it the same way as the captured lines from the runner.

Notes

  • runDoctor accepts only { report?: boolean }. There is no { json: true } option. The inline runner is the JSON wrapper.
  • The 5 layers are: Environment, Database, Configuration, Provider Connectivity, Runtime State. Two optional layers — Preview Confidence (when a _preview/ folder exists) and Retired Frameworks (when ≥1 retired framework is installed) — appear only when relevant.
  • Doctor never prints secrets. Env values are masked before any line is logged. Safe to re-render the lines verbatim.
  • The /keys/connect/<provider> URLs hard-code http://localhost:3847 — they're only useful once the dashboard is running.
  • The runner's heredoc must use '\${PWD}/...' (single-quoted with escaped $) so the shell expands $PWD on write but the resulting JS file contains a literal absolute path. Inside JS, plain string literal syntax — no template literal needed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.