# Router Health

> >

- **Type:** Skill
- **Install:** `agentstack add skill-glitchwerks-claude-wayfinder-router-health`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [glitchwerks](https://agentstack.voostack.com/s/glitchwerks)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [glitchwerks](https://github.com/glitchwerks)
- **Source:** https://github.com/glitchwerks/claude-wayfinder/tree/main/skills/router-health
- **Website:** https://pypi.org/project/claude-wayfinder/

## Install

```sh
agentstack add skill-glitchwerks-claude-wayfinder-router-health
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Router Health Skill

You are reporting on the health of the deterministic-dispatch router. This is
a **read-only** skill — never mutate state, logs, or the catalog.

## What this skill does

1. Runs `python -m claude_wayfinder health --report`.
2. Prints the report verbatim.
3. Adds an **Analysis** section with drill-down on any FAIL'ing or
   near-threshold metric.
4. Adds an extended **Notable Findings** section with qualitative
   observations from `dispatch-log.jsonl` (top agents, top skills, catalog
   freshness) that complement the script's built-in Notable Findings.

If invoked with `--brief`, skip step 2 and produce only Analysis + extended
Notable Findings. Useful for mid-session quick checks where the user does
not need the full report.

## Path resolution

The script (`claude_wayfinder._health.main`) resolves each path argument via
env var override or ``~/.claude/...`` home-dir default (Issue #262).  Explicit
flags always win; passing no flag is equivalent to the default shown below.

| Argument                  | Env var override              | Default (when env var absent)                |
| ------------------------- | ----------------------------- | -------------------------------------------- |
| `--drift-log`             | `$ROUTER_DRIFT_PATH`          | `~/.claude/state/router-drift.jsonl`         |
| `--dispatch-log`          | `$DISPATCH_LOG`               | `~/.claude/state/dispatch-log.jsonl`         |
| `--catalog-path`          | `$DISPATCH_CATALOG_PATH`      | _(omit; catalog section will be empty)_      |
| `--skills-dir`            | `$ROUTER_SKILLS_DIR`          | `~/.claude/skills`                           |
| `--agents-dir`            | `$ROUTER_AGENTS_DIR`          | `~/.claude/agents`                           |
| `--plugin-overrides-dir`  | `$ROUTER_PLUGIN_OVERRIDES_DIR`| `~/.claude/triggers`                         |

Absent log files are treated as empty (telemetry sections render with zero
events). Missing skills/agents/overrides directories produce a FAIL on the
corresponding CI invariants, which is the correct signal.

Note: `--drift-log` uses `$ROUTER_DRIFT_PATH` (matching
`scripts/analyze-drift-causes.py`), not `$ROUTER_DRIFT_LOG`.  Both tools
resolve the drift log from the same env var so overriding one overrides both.

## Step 1: Run the report

Use the plugin-installed `claude-wayfinder` package via `python -m`. This
assumes the plugin venv's `python` is on `$PATH` (the standard setup after
`/setup-wayfinder`). If the user's shell does not have the venv activated,
substitute the absolute interpreter path:
`${CLAUDE_PLUGIN_DATA}/venv/bin/python` (POSIX) or
`${CLAUDE_PLUGIN_DATA}/venv/Scripts/python.exe` (Windows).

Bare invocation uses the home-dir defaults automatically:

```bash
python -m claude_wayfinder health --report
```

Override individual paths via env vars when needed:

```bash
ROUTER_DRIFT_PATH=/custom/drift.jsonl python -m claude_wayfinder health --report
```

Or pass explicit flags (these override both env vars and defaults):

```bash
python -m claude_wayfinder health --report \
  --drift-log    /path/to/router-drift.jsonl \
  --dispatch-log /path/to/dispatch-log.jsonl \
  --skills-dir   /path/to/skills \
  --agents-dir   /path/to/agents \
  --plugin-overrides-dir /path/to/triggers
```

`--catalog-path` is omitted intentionally — the script falls back to
`$DISPATCH_CATALOG_PATH` when no flag is passed.

If `--brief` was passed by the user, capture the output but do not print it
verbatim — only use it as input to Step 2.

## Step 2: Print the report verbatim

Unless `--brief` was passed, emit the captured markdown unchanged. Begin
your response with the report.

## Step 3: Analyze the report

The script already emits an `ACTION REQUIRED` block for FAIL'ing CI
invariants and a `THRESHOLD BREACH` block for FAIL'ing runtime telemetry.
The Analysis section adds **warning-zone** drill-down for metrics that pass
today but are within 80% of the FAIL threshold, plus drift-event
correlation.

Parse each row of the **CI Invariants** and **Runtime Telemetry** tables for
the `Status` column. For every row whose status is **FAIL** OR is within
**80% of the FAIL threshold**, produce a sub-bullet under the Analysis
section explaining the most likely driver.

### How to compute "warning zone"

| Metric                   | Healthy direction | Warning zone (>80% toward FAIL)        |
| ------------------------ | ----------------- | -------------------------------------- |
| Dispatch invocation rate | ≥ 80%             | between 80% and 84%                    |
| Bypass rate              | ≤ 10%             | between 8% and 10%                     |
| Advisory override rate   | ≤ 30%             | between 24% and 30%                    |
| Catalog availability     | = 100%            | any sub-100% reading is already a FAIL |
| Catalog stability        | identical bytes   | byte-difference is FAIL outright       |
| Schema validation        | exit 0, 0 fatal   | any fatal entry is FAIL outright       |
| Trigger firing accuracy  | 10/10 smoke tests | 

## Analysis

### Recent drift events

## Extended Notable Findings

### Top dispatched agents (last 30 days)

### Top invoked skills (last 30 days)

### `self_handle_unaided` rate (catalog coverage)

### Catalog entry counts

### Catalog freshness

```

If `--brief`: omit the verbatim report (Step 2) — start the response with
`## Analysis`.

## Tone and discipline

- Be specific and quantitative. Cite exact counts, percentages, session-id
  prefixes, dates.
- Do not invent metrics that the script does not produce. Stick to the
  observed data.
- Do not recommend changes to thresholds — those are codified in
  `src/claude_wayfinder/_health.py` and changing them is a separate
  decision.
- Where a finding suggests action (regenerate catalog, investigate a
  bypass-heavy session), name the next step concretely with the command
  to run.
- If a log file is missing or empty, say so — never silently fall through
  with zero counts that look like "everything is healthy."

## Failure modes

- **Script exits non-zero**: surface stderr verbatim, recommend the user
  run the command directly to see the failure. Do not produce Analysis or
  Notable Findings sections — the source data is unreliable.
- **Log files missing**: if `dispatch-log.jsonl` or `router-drift.jsonl`
  do not exist, the corresponding hooks are not firing. Flag this as a
  dispatch-pipeline drift event in its own right and recommend checking
  the PreToolUse / Stop hooks in the consumer's hook registry.
- **Catalog file missing**: report this as a catalog-availability outage
  and recommend running `/refresh-catalog` or
  `claude-wayfinder catalog build`.
- **`python` not on PATH**: the user has not run `/setup-wayfinder` yet,
  or the plugin venv is not activated. Recommend `/setup-wayfinder` and
  re-running this skill in a fresh session.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [glitchwerks](https://github.com/glitchwerks)
- **Source:** [glitchwerks/claude-wayfinder](https://github.com/glitchwerks/claude-wayfinder)
- **License:** MIT
- **Homepage:** https://pypi.org/project/claude-wayfinder/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-glitchwerks-claude-wayfinder-router-health
- Seller: https://agentstack.voostack.com/s/glitchwerks
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.