How do I install the Diag Harness skill?

Run npx skillmds@latest add ruvnet/diag-harness 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 Diag Harness safe to use?

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

Which AI agents work with Diag Harness?

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 Diag Harness free to use?

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

Who published Diag Harness?

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

Diag Harness by ruvnet — Agent Skill

Name: Diag Harness
Rating: 4.2 (5 reviews)
Author: ruvnet

Diag Harness

Kernel-version skew check (ADR-027). Reports manifest surface + manifest kernel + installed kernel + verdict (match/patch-diff/minor-diff/major-diff). Exits 1 on minor/major skew with a copy-pasteable `npm install @metaharness/kernel@X.Y.Z` next step. Exits 2 if no .harness/manifest.json at path.

ruvnet Updated Sep 10, 2026

File contents

diag-harness

Codex skill: kernel-version skew check for a scaffolded harness — the ADR-027 diagnostic UX loop.

What it does

Single-question check: does my local @metaharness/kernel match what this harness was scaffolded against? That's the cross-machine compatibility question almost every "this harness doesn't work" support ticket turns out to be.

Reads .harness/manifest.json:

Field	Source	Meaning
`meta.surface`	iter 56	Which surface produced the harness (`cli` or `web-ui`)
`meta.kernel_version`	iter 58	The `@metaharness/kernel` version stamped at scaffold time

Resolves the local @metaharness/kernel via createRequire rooted at the harness's own package.json (real Node resolution). Computes the skew verdict and prints a copy-pasteable next step.

Verdict	Exit	Message
`match`	0	`PASS kernel versions match exactly`
`patch-diff`	0	`WARN patch-level skew (usually safe; may include bugfixes)`
`minor-diff`	1	`WARN minor-level skew (new kernel features may be missing)` + `Run: npm install @metaharness/kernel@X.Y.Z`
`major-diff`	1	`FAIL MAJOR skew — APIs may have changed; expect breakage` + `Run: npm install @metaharness/kernel@X.Y.Z`
no `.harness/manifest.json` at path	2	`FAIL no .harness/manifest.json found at this path`

Usage from Codex

/diag-harness                           # cwd
/diag-harness path=./my-harness

Equivalent CLI

harness diag                            # cwd
harness diag ./my-harness               # explicit path
harness diag ./my-harness --json        # machine-readable for CI
harness diag ./my-harness --bundle      # support-ticket JSON (iter 90)

The --bundle form (iter 90) emits a single JSON snapshot of the diag report + sanitised manifest + @metaharness/* deps + Node/platform info — everything a maintainer needs to triage a bug report. Object keys matching secret|token|key|password|api_key are redacted so the bundle is safe to paste into a public GitHub issue.

Sample output

harness diag — checking /tmp/my-harness

  surface:              cli
  manifest kernel:      0.1.0
  installed kernel:     0.1.0

  PASS kernel versions match exactly

When to run

After cloning someone else's harness — first thing
After bumping @metaharness/kernel in a harness's package.json
When harness doctor fails with cryptic shape errors (skew is the usual cause)
In CI before any other harness subcommand — fail fast

Lifecycle position

scaffold (create-agent-harness)
    ↓
 your code lives in the harness
    ↓
 diag (this skill)           <- before anything else, check compatibility
    ↓
 doctor / validate / sign / publish

ADR-027 — CLI ↔ Web-UI integration (the parity contract diag enforces)
iter 56 — manifest.meta.surface added
iter 58 — manifest.meta.kernel_version stamped at scaffold time
iter 66 — harness diag subcommand

---name: diag-harnessdescription: Kernel-version skew check (ADR-027). Reports manifest surface + manifest kernel + installed kernel + verdict (match/patch-diff/minor-diff/major-diff). Exits 1 on minor/major skew with a copy-pasteable `npm install @metaharness/kernel@X.Y.Z` next step. Exits 2 if no .harness/manifest.json at path.---# diag-harness> Codex skill: kernel-version skew check for a scaffolded harness — the ADR-027 diagnostic UX loop.## What it doesSingle-question check: **does my local `@metaharness/kernel` match what this harness was scaffolded against?** That's the cross-machine compatibility question almost every "this harness doesn't work" support ticket turns out to be.Reads `.harness/manifest.json`:| Field | Source | Meaning ||---|---|---|| `meta.surface` | iter 56 | Which surface produced the harness (`cli` or `web-ui`) || `meta.kernel_version` | iter 58 | The `@metaharness/kernel` version stamped at scaffold time |Resolves the local `@metaharness/kernel` via `createRequire` rooted at the harness's own `package.json` (real Node resolution). Computes the skew verdict and prints a copy-pasteable next step.| Verdict | Exit | Message ||---|---|---|| `match` | 0 | `PASS kernel versions match exactly` || `patch-diff` | 0 | `WARN patch-level skew (usually safe; may include bugfixes)` || `minor-diff` | 1 | `WARN minor-level skew (new kernel features may be missing)` + `Run: npm install @metaharness/kernel@X.Y.Z` || `major-diff` | 1 | `FAIL MAJOR skew — APIs may have changed; expect breakage` + `Run: npm install @metaharness/kernel@X.Y.Z` || no `.harness/manifest.json` at path | 2 | `FAIL no .harness/manifest.json found at this path` |## Usage from Codex```/diag-harness # cwd/diag-harness path=./my-harness```## Equivalent CLI```bashharness diag # cwdharness diag ./my-harness # explicit pathharness diag ./my-harness --json # machine-readable for CIharness diag ./my-harness --bundle # support-ticket JSON (iter 90)```The `--bundle` form (iter 90) emits a single JSON snapshot of the diag report + sanitised manifest + `@metaharness/*` deps + Node/platform info — everything a maintainer needs to triage a bug report. Object keys matching `secret|token|key|password|api_key` are redacted so the bundle is safe to paste into a public GitHub issue.## Sample output```harness diag — checking /tmp/my-harness surface: cli manifest kernel: 0.1.0 installed kernel: 0.1.0 PASS kernel versions match exactly```## When to run- After cloning someone else's harness — first thing- After bumping `@metaharness/kernel` in a harness's `package.json`- When `harness doctor` fails with cryptic shape errors (skew is the usual cause)- In CI before any other harness subcommand — fail fast## Lifecycle position```scaffold (create-agent-harness) ↓ your code lives in the harness ↓ diag (this skill) <- before anything else, check compatibility ↓ doctor / validate / sign / publish```## Related- ADR-027 — CLI ↔ Web-UI integration (the parity contract diag enforces)- iter 56 — `manifest.meta.surface` added- iter 58 — `manifest.meta.kernel_version` stamped at scaffold time- iter 66 — `harness diag` subcommand

Frequently asked questions