epoko77-ai

Harness Diagnostic — AI skill for Claude Code

AI community

System-level lint for multi-agent harnesses.

How to install Harness Diagnostic

This entry records only its repository, not the path inside it, so there is no exact command to give. Open epoko77-ai/harness-diagnostic and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Harness Diagnostic does

System-level lint for multi-agent harnesses. Catches the 21 structural traps single-file linters miss — including the LLM-when-you-should-use-code patterns that burn tokens.

Alternatives in AI

Jcodemunch MCP — Cut AI token costs 95%+ on code exploration 2.6k ★
Wiki Lint — Health-check the LLM Wiki for issues 2.3k ★
Gsap Skills — Official AI skills for GSAP 1.7k ★

README

Harness Diagnostic

**System-level lint for multi-agent harnesses.** Catches the structural traps single-file linters miss — including the LLM-when-you-should-use-code patterns that burn tokens. agnix lints your files. Harness Diagnostic lints your system.

File-level linters check whether each `CLAUDE.md`, `SKILL.md`, or `AGENTS.md` conforms to its own schema. They cannot see the failures that live *between* files — the FAIL gate without a cascade actor, the 91-minute citation step that should have been 30 seconds of Python, the drafter that saves its output and then dies producing a report.

This catalog enumerates 21 such gaps observed while building `paper-maker`, a 15-agent academic-paper harness (v1.0 → v1.2; private companion harness, not yet public). Each gap is mapped onto a five-layer architectural model adopted from agentic-system reliability research (arXiv 2604.08906 and its 409-bug analysis).

Why this also saves money

Roughly a third of the catalog (6 of 21 gaps) is a direct cost regression — not a quality issue, a *bill* issue. The flagship case:

paper-maker's `pm-citation-formatter` once ran for **91 minutes on Claude Opus** without producing an artifact. It had been asked to verbatim-map 60 facts against 31 KB of body text against 48 reference items in one LLM call. The transformation is deterministic — regex plus a dictionary lookup. After splitting the agent into a Python phase + a short LLM review, the same work takes **30 seconds**.

That is not a 2× speedup. It is a **~99% cost reduction** on one of the most expensive agents in the pipeline. The pattern — *deterministic work routed through an LLM* — is invisible to file-level linters because each agent definition is internally well-formed.

Gap	Cost effect
HD-003 Deterministic work routed through an LLM ★	The flagship cost trap. 91 min Opus tool-call loop → 30 sec Python.
HD-007 Parallel fanout not parameterized by content size	Preve