relay-doctor

Diagnose mismatches between Relay flow definitions and repo-provided agents, skills, and commands.

Updated Jul 22, 2026
One-click install
npx skills add https://github.com/jeremylightsmith/relay-config --skill relay-doctor-jeremylightsmith
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: relay-doctor
Source: https://github.com/jeremylightsmith/relay-config/tree/main/.claude/skills/relay-doctor
Command: npx skills add https://github.com/jeremylightsmith/relay-config --skill relay-doctor-jeremylightsmith

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? A Relay board's flow names agents, skills, and binaries, but nothing verifies those names resolve until a run fails mid-execution. This Skill audits every flow against the repo's actual capabilities and board health, reports each disagreement, and fixes them interactively with the user. ## Core Features & Use Cases - Nine alignment checks: Validates that node agents and slash commands resolve against the executor's own capability inventory, trigger fields are set, shell binaries exist on PATH, executors are fresh and current, and node read/write contracts are declared and honored. - Board health audit: Surfaces relay audit findings such as dropped review findings, verdict flips on retries, and CI parity gaps between GitHub workflows and flow gate nodes. - Interactive fixing: Reports errors first, then walks through each one asking whether to grow the repo (create the missing agent or skill) or shrink the flow (edit and push the flow document), always with explicit confirmation before any flow push. - Use Case: After renaming a .claude/agents file, run the doctor to catch every flow node that still references the old name before a run dies on it. ## Quick Start Ask the assistant to run the relay doctor to check all flows for alignment with this repo's agents, skills, and commands.

Frequently Asked Questions about relay-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a Relay flow matches my repo's agents and skills?▼

Run /relay-doctor with no argument to check every flow, including disabled ones, or pass a flow key to narrow the scope. It compares each node's agent and slash command against the executor's own capability inventory and reports errors and warnings grouped by flow.

Why did my Relay run fail with an unknown agent or skill?▼

The flow names an agent or slash command that does not exist in .claude/agents, .claude/skills, .claude/commands, or the built-ins. The doctor's checks 1 and 2 detect exactly this by resolving names through the executor's collect_capabilities function rather than a re-implemented lookup.

Can relay-doctor modify my flows automatically?▼

No. Every flow push is a real board mutation, so the skill shows the exact node-level change and requires explicit confirmation first. Fixes are interactive: you choose between creating the missing repo file or editing the flow document.

What does the relay audit check for board health?▼

The audit reports dropped review findings in foreach loops, verdict flips where a retry turned a failure into a pass on the same git SHA, and CI parity gaps where required GitHub workflow commands are not run by any enabled flow's gate node.

When should I not run relay-doctor?▼

Never run it from a flow node, because it asks interactive questions and a runner has nobody to answer them. Also note its binary and CI checks are heuristics about the current machine's PATH and working directory, not the executor fleet.