How do I install the Harness Doctor skill?

Run npx skillmds@latest add bossjones/harness-doctor in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Harness Doctor safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Harness Doctor?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Harness Doctor free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Harness Doctor?

bossjones (@bossjones) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Harness Doctor by bossjones — Agent Skill

Name: Harness Doctor
Author: bossjones

Harness Doctor

Inspect agent-harness environment readiness and runtime storage without changing files. Use when asked to diagnose agent-harness, check hook prerequisites, find harness logs or data, learn which plugin repository names the harness root, inspect stale logs, .claude/data, or a legacy repository-named harness directory, or run a harness health check.

bossjones Updated Sep 17, 2026

File contents

Harness doctor

Use this read-only diagnostic before changing an agent-harness installation or when hook output is missing. It reports advisory tool readiness, the resolved harness root with the plugin namespace that names it, sizes for its logs, data, and cache directories, enabled plugin identities when settings expose them, and stale pre-migration artifacts. It never deletes, moves, or edits files.

Triggers

Use this skill for concrete requests such as:

"run the agent-harness doctor"
"why are my agent-harness logs missing?"
"check whether my hook environment is ready"
"is old logs/ or .claude/data/ safe to remove?"
"why is there a dot-directory named after this repo?"
"which agent-harness plugin is enabled?"

Run the report

Run from the repository to inspect, or pass an explicit repository path:

$ uv run "${CLAUDE_SKILL_DIR}/scripts/harness_doctor.py"
$ uv run "${CLAUDE_SKILL_DIR}/scripts/harness_doctor.py" --repo-root /path/to/repo

Read the JSON report and summarize its advisory hints. harness_root.namespace is the plugin's marketplace repository, and harness_root.namespace_source is the directory that supplied it — the same name is used in every repository the plugin runs in. A stale logs/, .claude/data/, or legacy_project_root result means the directory predates the current layout; report each as safe to delete only after the user has reviewed it. Do not delete anything as part of this skill.

Follow-up

Missing uv, python3, git, gh, ruff, or tmux is advisory. Explain the affected capability and its reported hint.
If GitHub CLI is installed but unauthenticated, suggest $ gh auth login.
If the resolved root is unexpected, inspect CLAUDE_HARNESS_DIR and CLAUDE_PLUGIN_OPTION_HARNESS_DIR; CLAUDE_HOOKS_LOG_DIR only overrides the logs subtree. A namespace_source of null means no marketplace manifest was found above the plugin, so the root falls back to .agent-harness.
Use /setup-agent-harness only when the user wants to update repository settings or the managed .gitignore block.

---name: harness-doctordescription: Inspect agent-harness environment readiness and runtime storage without changing files. Use when asked to diagnose agent-harness, check hook prerequisites, find harness logs or data, learn which plugin repository names the harness root, inspect stale logs, .claude/data, or a legacy repository-named harness directory, or run a harness health check.---# Harness doctorUse this read-only diagnostic before changing an agent-harness installation orwhen hook output is missing. It reports advisory tool readiness, the resolvedharness root with the plugin namespace that names it, sizes for its `logs`,`data`, and `cache` directories, enabled plugin identities when settings exposethem, and stale pre-migration artifacts. It never deletes, moves, or editsfiles.## TriggersUse this skill for concrete requests such as:- "run the agent-harness doctor"- "why are my agent-harness logs missing?"- "check whether my hook environment is ready"- "is old logs/ or .claude/data/ safe to remove?"- "why is there a dot-directory named after this repo?"- "which agent-harness plugin is enabled?"## Run the reportRun from the repository to inspect, or pass an explicit repository path:```text$ uv run "${CLAUDE_SKILL_DIR}/scripts/harness_doctor.py"$ uv run "${CLAUDE_SKILL_DIR}/scripts/harness_doctor.py" --repo-root /path/to/repo```Read the JSON report and summarize its advisory hints. `harness_root.namespace`is the plugin's marketplace repository, and `harness_root.namespace_source` isthe directory that supplied it — the same name is used in every repository theplugin runs in. A stale `logs/`, `.claude/data/`, or `legacy_project_root`result means the directory predates the current layout; report each as safe todelete only after the user has reviewed it. Do not delete anything as part ofthis skill.## Follow-up- Missing `uv`, `python3`, `git`, `gh`, `ruff`, or `tmux` is advisory. Explain the affected capability and its reported hint.- If GitHub CLI is installed but unauthenticated, suggest `$ gh auth login`.- If the resolved root is unexpected, inspect `CLAUDE_HARNESS_DIR` and `CLAUDE_PLUGIN_OPTION_HARNESS_DIR`; `CLAUDE_HOOKS_LOG_DIR` only overrides the logs subtree. A `namespace_source` of `null` means no marketplace manifest was found above the plugin, so the root falls back to `.agent-harness`.- Use `/setup-agent-harness` only when the user wants to update repository settings or the managed `.gitignore` block.

Frequently asked questions