Skill: doctor

The doctor-buddy-agent-harness skill checks whether a repository’s harness bridges still resolve — its skills into .agents/skills, and its instructions into AGENTS.md. A bridge that has stopped resolving is silent: the harness finds nothing and loads zero project skills, or reads none of the repository’s instructions, with no warning anywhere. Reach for this skill when either has happened, or before you conclude a skill or an instruction is being ignored.

The command it runs writes nothing. A repair does write, so the skill names the init command it is about to run and runs that as a separate step.

Run it

In Claude Code:

/buddy-agent-harness:doctor-buddy-agent-harness

The skill also loads on its own when an agent hits the symptom, so “my skills are missing after cloning this repo” or “Claude is ignoring our AGENTS.md” is enough to reach it.

Its one action is to run buddy-agent-harness doctor and act on the report. If you would rather run that yourself, the plugin is not a prerequisite: see the CLI reference.

The skill runs a self-contained bundle of the CLI shipped in its own scripts/ directory, so an installed plugin downloads nothing and needs no node_modules beside it. It falls back to npx, pinned to the version it shipped with, when that bundle is missing or cannot be run — the case for a git-sourced install, which does not carry it. Skill Scripts covers the pattern, and Introduction covers why the plugin wants an npm-backed install.

What it checks

It checks every bridge init would create for this repository. Both read the same registry, so the two cannot describe different bridge sets.

The report has two of them. bridges covers the skills projections into .agents/skills; instructions covers everything standing between a harness and AGENTS.md — the context.fileName entry in .gemini/settings.json, which is the one bridge left, and the files that suppress an AGENTS.md a harness would otherwise read, which is what a CLAUDE.md now is. They are separate sections because their statuses and their repairs have nothing in common; the CLI reference has the reasoning.

For each one the report gives a kind (what is on disk now) and a status (whether it works). A findings entry explains each problem and a help row carries its repair in two columns: a command that runs verbatim and completes it, and an instruction in the imperative. An empty command means no single invocation does the job — act on the instruction. Apply the repair, then run doctor again.

A third section, globalInstructions, looks past the repository to you: whether each harness installed for you loads ~/.agents/AGENTS.md through its own user-scope file, such as ~/.claude/CLAUDE.md. No harness reads that file by itself, so text placed there reaches only the harnesses whose row is ok. The repair is a line or a symlink in your home directory, and the skill hands it to you rather than writing it. Reaching ~/.agents/AGENTS.md has the details.

Every instruction repair is /buddy-agent-harness:init-buddy-agent-harness rather than a command. Those files carry prose someone wrote, and restoring a bridge without discarding what displaced it — or deciding whether a redundant one is being kept on purpose — is the init-buddy-agent-harness skill’s judgment.

A healthy repository says so outright instead of printing an empty section, so an agent does not re-run with other flags to check whether “nothing” meant “nothing wrong”.

The report is TOON by default, which is what the agent parses. Ask for --format text when you want to read it yourself.

Statuses, findings, and their repairs are tabulated in the CLI reference. The skill body carries the same table, generated from the source the command prints from, so the guidance an agent follows cannot drift from what the command reports.

The failure it was built for

A committed symlink such as .claude/skills → ../.agents/skills breaks on a native Windows checkout, where git writes it out as a regular file instead. That is the degraded status, and the CLI reference explains why git does it silently.

The repair there is init --copy --force rather than recreating the link. Creating a link is the operation that already failed on that machine.

Configuration findings

Beyond the bridges, doctor reports configuration that is present and wrong: a superseded harness name still projected, a .gitignore rule swallowing a bridge, an AGENTS.local.md no harness reads, and a skill whose frontmatter makes every harness skip it. Each resolves fine and is still wrong.

Those four go to the repair skill, which offers each correction with its before and after and writes only what you approve. Everything else doctor finds goes to init.

MCP findings

Where the repository keeps a golden MCP server set, the command also reports how each harness’s own MCP config has drifted from it, and it reports a literal credential in any MCP file whether or not a golden set exists. This skill does not act on any mcp-* finding itself — every repair is carried in the finding, and passing it on is the whole of what this skill does with it. Four name the repair skill, which drives mcp project for mcp-unprojected and mcp-diverged-golden and mcp reconcile for mcp-undeclared and mcp-diverged-target, each with approval; every other mcp-* finding is a person’s call. Two rules bind this skill regardless: never merge a mcp-diverged-both conflict automatically, and never read a reported secret’s value back into the conversation; the report deliberately does not contain it. MCP Servers is the home for the golden set, the per-harness files, and the findings.

Agent worktree findings

In a repository with a .claude/ directory, the command reports a missing .gitignore rule, a Biome config that does not exclude .claude/worktrees, and an unset worktree.baseRef. The skill passes each to init or enhance, which offers it. worktree-base-unset is a choice, so put the trade-off to the owner. Agent Worktrees is the home for all three.

What it will not do

There is no --fix, and the skill does not invent one. Three rules hold whatever you ask for mid-run:

• Never repair a diverged-both or diverged-unknown bridge by re-running init. Both sides moved, so rebuilding discards one of the edits. Reconcile the two directories first.
• Edit skills at .agents/skills/<name>/SKILL.md. Editing through a bridge is only safe when that bridge is a symlink, because a copy takes the write and keeps it.
• Never add a bridge to .gitignore. An untracked bridge swallows a real edit silently.
• Never repair an unbridged instruction file by replacing it. Something displaced the import, and it may be the only copy of that content.

Because it writes nothing and always exits 0, the command is safe to wire into a session-start hook. Why the exit code stays 0, and why divergence gets a direction rather than a diff, are covered in the CLI reference.