agent-skills

Problem still asserts the pre-#474 payload shape ( / ). After #474 the hook emits the host-required envelope: On current , fails immediately: CONTRIBUTING.md still tells contributors to run that test before any hook PR, so the documented regression check is red on a clean checkout. Hosts that validate hook output (Codex CLI, Claude Code) already reject the old shape; the test was the leftover. Root cause #474 updated (and the no-jq fallback) to so hosts stop rejecting the hook. and the CONTRIBUTING wording about an -priority payload were not moved with it. Sibling: the jq-missing path uses the same envelope with different ; it was also untested against the new shape. This is not a Windows SessionStart fix (#475 / PR #480) and does not change hook runtime. Fix Assert and a non-empty . With jq: require the startup preface and in . Without jq: require the guidance in . CONTRIBUTING.md: describe the envelope fallback, not -priority. Verification jq-missing path (jq hidden from PATH) also prints . Sabotage: restoring the old assertion on this branch fails with . Risks None to runtime. If a host still consumed , that already broke in #474; this only makes the test match what hosts accept.

Specifying what an operation does when a dependency times out, stalls, or leaves an outcome unknown — at design time, rather than after the incident. The gap, per CONTRIBUTING rule 4 I checked rather than assumed. A concept scan across all 24 existing skills: The vocabulary that does exist is almost all in , which owns the request axis: deriving and honouring an idempotency key. The adjacent skills own different jobs — is reactive triage for something already broken, and is about assumptions rather than dependency behavior. None of them decides what happens on a timeout before the code is written. I also checked all 56 open PRs: none adds a skill on this topic. It routes to those siblings rather than restating them* — the idempotency implementation to , live diagnosis to , telemetry to . What it contains A three-outcome table per boundary, where the third column — unknown — is the one usually left blank, and only three answers are legitimate: make it safe to repeat, make it detectable, or make it impossible. "Retry and hope" is not on the list. Then blast-radius classification, a degradation ladder with measurable triggers, and an injection plan, on the rule that a failure mode you cannot inject cannot be tested. The eval router shaped this, and that is worth reporting I named and worded it around rather than against it, and the gate caught three real problems in my first draft: It was called failure-mode-analysis. Skill names are weighted double in the ranker, so the token made it rank #1 for "Add a dark mode toggle to the settings page". stems together with , so it outranked on that skill's own positive prompt — the exact boundary the skill claims to respect. A later draft leaned on "boundary" and "design" and collided with instead. Two findings from that which may be useful beyond this PR: Removing the clause from the description made things worse, not better. A bag-of-words ranker scores a negative clause exactly like a positive one, so was injecting diagnose, failure and happening into the vector — the debugging prompt's own vocabulary. That guidance now lives in the body, where it reads to a human and not to the ranker. Adding a 25th skill shifts the IDF corpus and can demote an unrelated skill below the top-3 threshold even when the new skill is nowhere near the prompt.* At one point dropped to #4 with my skill absent from the top 3 entirely. A shorter, more distinctive description perturbs less, which is why the final one is two sentences rather than five. Verification Ran the repo's own CI steps locally: I confirmed the baseline too: without this skill is , so every collision above was mine to fix rather than something pre-existing I could have shrugged at. Eval case has 3 positive triggers, 2 negative triggers with , and one behavioral eval backed by a real fixture at . Note on provenance An earlier version of this skill exists in a small pack of my own. I wrote it, and this is a deliberate adaptation rather than a copy — the cross-references are repointed at this pack's skills, the framing defers to for idempotency instead of owning it, and the name and description were rewritten for this repo's router. Mentioning it because you should know where it came from. Happy to fold it into an existing skill instead if you'd rather not add a directory — the content is designed to sit beside , not on top of it.

The bug scans every line of a , so a path shown inside a fenced code block is treated as a link to resolve. That makes this rule undocumentable: the validator's own failure message says use , not and a skill that shows that contrast as an example fails the check that is explaining it. Reproduced on by appending a fenced markdown example to : — the guidance printed directly underneath the link it had just rejected for demonstrating it. The fix Lines inside a fence are skipped. The scan is line-by-line rather than one regex over the document, so the three CommonMark fence forms all hold: tilde fences, up to three spaces of indent, and a closing fence longer than its opener — and a without the fix: 10 tests, 7 pass, 3 fail ✖ a link inside a fenced block is an example, not a link to resolve ✖ fence exemption follows CommonMark rather than a bare The third is the important one — it pins that a genuinely broken link outside a fence is still reported, so the exemption cannot quietly swallow the breakage this validator exists to catch. (It fails on too, because there the fenced example is counted as a second error.) With the fix: 10/10, and all five validators pass — , , , , — plus and (86%, 67/78). Screening No open PR touches . #437 and #444 concern 's stripper, and #387's heuristic list is about section checks and cross-reference patterns in the same file — a different validator and a different rule from this one.