Skip to content
Skills Library
AI & agents · Analysis

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).

Repository
vigiles ↗
Licence
MIT
Last repository change
14.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

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

  1. What's in the ledger
  2. Instructions
Original SKILL.md headings · 53 lines, 434 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.