Agent Harness Doctor

Automated audit and fix for OpenClaw agent harnesses. Scans your setup, scores on 8 dimensions (Session Bridge, Startup Sequence, Smoke Test, Atomic Checkpoi...

Security Scan

The skill's declared purpose (audit + P0 auto-fix) matches the code, but there are important mismatches in the instructions/metadata (a supposedly read-only tool can modify files) and it will write to and edit workspace files without backups — review before installing or let it run only in a sandboxed copy of your repo.

Purpose & Capability

Name/description align with behavior: the skill scans repository files (AGENTS.md, memory/*) and can create agent-progress.json and update AGENTS.md. The actions performed (diagnose and apply fixes to harness files) are coherent with the stated purpose.

Instruction Scope

SKILL.md declares a tool 'harness_check' with permission 'read_only' but the implementation accepts a 'fix_apply' list and will call apply_fix to write files (create agent-progress.json, modify AGENTS.md). SKILL.md also lists fixes like 'inject self-check prompt into system instructions' that are not implemented in the provided code, indicating inconsistency between described and actual behavior. The skill will modify workspace files without prompting for backups — this is expected for an auto-fixer but should be explicit and safeguarded.

Install Mechanism

Instruction-only skill with a small included script and no install spec — nothing is downloaded or installed system-wide.

Credentials

No environment variables, credentials, or external endpoints are requested. The code operates only on local workspace files.

Persistence & Privilege

The skill does not request persistent 'always' inclusion. It does write and edit files in the repository (workspace root and AGENTS.md). This is normal for a repair tool but means it can alter your agent harness and documentation — run on a copy or ensure backups.

What to consider before installing

This skill appears to do what it says (diagnose and auto-fix harness files) but has two important surprises: 1) the 'harness_check' tool is advertised as read-only yet can apply fixes when given fix IDs, and 2) it will create/modify files in your workspace (agent-progress.json, AGENTS.md) without making backups. Before installing or running: (a) run it in a disposable/sandbox copy of your repo, (b) review the created/changed files (agent-progress.json, AGENTS.md) after a diagnostic run and before allowing any auto-fix, (c) prefer invoking apply_fix explicitly rather than relying on harness_check's fix_apply to avoid accidental writes, and (d) if you accept it, ensure you have a VCS snapshot or other backup so changes can be reviewed/reverted. If you need higher assurance, ask the publisher for: explicit backup behavior, a dry-run mode for apply_fix, and correction of the metadata so 'harness_check' is not labeled read-only when it can modify files.

Based on Anthropic's "Effective Harnesses for Long-Running Agents" and ClawHub's agent-harness-architect, this skill automatically diagnoses and hardens your OpenClaw harness.

The 8 Dimensions

Dimension	What it checks	Why it matters
Session Bridge	Is there a structured state file (agent-progress.json) that survives restarts?	Without this, every session starts blank
Fixed Startup Sequence	Does the agent have a mandatory first N steps (read bridge, smoke test, etc.)?	Prevents skipping crucial initialization
Smoke Test	Does the agent verify environment (network, API keys, disk) before tasks?	Catches failures early
Atomic Checkpoint	After each task, does agent commit/save state?	Ensures progress isn't lost
Output Self-Verification	Before saying "done", does agent validate the result?	Prevents false completions
State File Format	Is state stored as JSON (not Markdown) to resist accidental edits?	Markdown is too easy for LLM to mangle
Multi-Agent Protocol	If multiple agents, is there clear message passing?	Avoids race conditions and confusion
Fallback Plan	Does agent have a Plan B if a dependency fails?	Increases robustness

Usage

Run Diagnostic

tool("agent-harness-doctor", "harness_check", {"fix_apply": []})

Output includes:

{
  "summary": {
    "score": 6.5,
    "grade": "B",
    "weakest_dimension": "Session Bridge"
  },
  "dimensions": [
    {
      "id": "session_bridge",
      "name": "Session Bridge",
      "score": 2,
      "max": 10,
      "finding": "No agent-progress.json file found",
      "recommendation": "Create agent-progress.json with lastSession, taskTracking, environmentStatus sections",
      "p0": true
    },
    ...
  ],
  "plan": {
    "P0": ["create_session_bridge", "fix_startup_sequence"],
    "P1": ["add_smoke_test", "enable_atomic_checkpoint"],
    "P2": ["output_verification_gate", "multi_agent_protocol"]
  }
}

Auto-Apply P0 Fixes

tool("agent-harness-doctor", "harness_check", {"fix_apply": ["create_session_bridge", "fix_startup_sequence"]})

The tool will:

1. Create agent-progress.json in workspace root with template
2. Update AGENTS.md or CLAUDE.md to include a fixed startup sequence section
3. Log changes made

Apply Single Fix

tool("agent-harness-doctor", "apply_fix", {"fix_id": "create_session_bridge"})

Fixes Implemented

• create_session_bridge — generates agent-progress.json with schema v1.0
• fix_startup_sequence — inserts mandatory startup steps into AGENTS.md (if present)
• add_smoke_test — adds pre-task environment check (gateway status, API connectivity)
• enable_atomic_checkpoint — adds post-task commit template
• output_verification_gate — injects self-check prompt into system instructions
• state_json_format — migrates existing state files from MD to JSON
• fallback_plan_template — adds fallback handling patterns to AGENTS.md

Integration with Memory Stack

If memory-stack-core is installed, harness doctor will:

• Check WAL and buffer health as part of "Session Bridge" score
• Recommend enabling WAL auto-capture if missing
• Verify buffer threshold is set appropriately

Pricing

$99 one-time. Includes:

• Unlimited diagnostics
• Auto-fix application
• Future dimension additions

---

Based on ClawHub's agent-harness-architect skill, extended with auto-fix capabilities.