debug-my-harness
/debug-my-harness
Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
Original author description
Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
How it works
- What's in the ledger
- Instructions
SKILL.md preview
---
name: debug-my-harness
allowed-tools: Read, Glob, Grep
description: Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
---
Diagnose harness misbehavior from the **flight recorder** — the local, append-only ledger
at `.vigiles/runs.jsonl` that vigiles writes as your harness runs. It records what actually
happened, so you debug from evidence instead of guessing.
## What's in the ledger
One JSON record per line, each with a `kind`:
- `hook` — a compiled-hook gate decision: `{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}`.
- `agent` — a subagent tool-contract decision: `{name, tool, allowed, reason}` (a `false` = the agent went outside its lane).
- `skill` — a skill activation: `{name, fired}`.
- `eval` — a measured metric: `{name, metric, value}` (e.g. trigger-rate recall/precision).
- `capability-diff` — a blast-radius change: `{pr, added, removed, widened}`.
## Instructions
### Step 1: Read the ledger
Read `.vigiles/runs.jsonl` (JSONL — one record per line; tolerate a torn last line). If it's
absent or empty, say so — there's nothing recorded yet; suggest running the harness (or
`vigiles audit`) first. Do NOT fabricate records.
### Step 2: Answer the specific question, evidence-first
Match the user's question to the ledger:
- **"Why did skill X stop firing / why does the wrong one run?"** — count `skill` fires by
name over time. If X's fire-rate dropped, look for a sibling that fired on the same kinds
of prompts (a **selection collision**) and check their descriptions for overlap. Recommend
differentiating or merging the descriptions.
- **"Why didn't my hook block that?"** — find `hook` records for the event. A `decision:
allow` on something that should be denied, or `mode: observe` (shadow, never blocks), or
the absence of any record, tells you which. Recommend flipping `observe`→`enforce` or
fixing the gate logic.
- **"Did a subagent misbehave?"** — list `agent` records with `allowed: false`: the agent
reached for a tool outside its declared contract. Point at the contract to tighten or widen.
- **"Is it getting worse?"** — compare `eval` metric values (recall/precision) across runs;
a downward trend is drift (often after a harness/model upgrade).
### Step 3: Recommend a fix, tied to the evidence
Prefer **promoting an ignored-but-decidable rule from prose to a deterministic gate**: a
repeated `agent` violation or a rule the agent keeps breaking → a compiled hook or a tighter
tool-contract (the `strengthen` skill can help). A description collision → differentiate the
skill descriptions. Always cite the specific records you based the diagnosis on.
### Step 4: Offer the next step
If the fix is a spec change, hand off to `edit-spec`. If it's promoting guidance to a linter
rule, hand off to `strengthen`. If a behavioral claim needs measuring (does the skill fire
now?), hand off to `test-harness` (`measureTriggerRate`).
Versions
The database has no other skills named debug-my-harness.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version cd10ff1ba94c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100test-harness
Install vigiles and test a Claude Code harness — hooks, skills, agents, settings, CLAUDE.md — by picking the right tier (unit / deterministic / eval) and writing a test that passes. Use to check that a hook fires or blocks, that a skill triggers, that injected context lands; or… - 100harness-design
Decide where each piece of a Claude Code harness belongs (CLAUDE.md, rules, skills, hooks, subagents, scripts, MCP) with token budgets, then build the files from templates. Use when designing or building skills, agents, commands, hooks or CLAUDE.md for a harness or plugin, when… - 100harness
Stage map and operating rules for building or improving a Claude Code harness (skills, agents, commands, hooks, CLAUDE.md, scripts) with research, evals against a no-harness baseline, and cost optimization. Use at the start of any harness-building session, when the user asks to… - 90coding-agent-harness
搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent,或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。 - 100harness
Run harness tests to verify everything-evenhub skill quality. Dispatches an implementer subagent guided by the skill, then a verifier subagent with a structured checklist. Use to validate any skill works correctly. - 100debug-hooks
Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.