zernie
ff542b7c4b
Rename the read-only scan verb to `vigiles audit` — a local, zero-config Lighthouse-style report scoring a harness across four deterministic rings (Truthfulness/Triggering/Structure/Tested) with each finding's fix inline + a shareable HTML report and a versioned AuditReport JSON.
audit is a local report, not a CI step (CI uses `vigiles lint`). The executing checks (live MCP resolution + trigger-rate + the adoption preview) run only behind one interactive consent; there is no execution flag. The safety battery is not an audit ring — it lives in the vigiles/testing API.
Adds the adoption-gateway preview ("what would vigiles catch in your repo?"): the model drafts a spec from the instruction file, the cross-reference engine verifies every drafted ref deterministically.
BREAKING CHANGE: the `scan` verb is renamed to `audit` (no alias); the `--check-hooks`/`--verify-mcp`/`--trigger`/`--fix-plan`/`--explain`/`--deep`/`--measure`/`--fast`/`--no-measure` flags are removed.
2.5 KiB
skill-frontmatter
Recommend (not require) that a SKILL.md declares an explicit name and
description in frontmatter. Per the skills docs
these are optional — name falls back to the directory name and
description to the first paragraph of the body — so a frontmatter-less
skill still loads and fires. But relying on the fallbacks is fragile: the
directory name may be unclear, and the first body paragraph is often a heading or
boilerplate, making a weak, accidental trigger surface. An explicit
name + description is the reliable, intentional choice.
This is a best-practice nudge, not a correctness check — distinct from
subagent-frontmatter, which flags subagents that
genuinely won't register without required frontmatter. Same detector scan uses
(skillMetaIssues); reported as a soft ℹ note in scan (never counted as a
structural defect or scored on the leaderboard).
What it flags
A skill (skills/*/SKILL.md) with no explicit frontmatter name and/or
description. The skill still works — this only suggests making the trigger
surface deliberate.
Configuration
{ "rules": { "skill-frontmatter": "warn" } }
Severity
| Value | Behavior |
|---|---|
"error" |
vigiles lint exits non-zero (2) — enforce it on your own skills |
"warn" (default) |
Prints a recommendation, exits 0 |
false |
Skip the check |
Default is warn, deliberately. The skill loads regardless, so erroring by
default would break a working third-party plugin. Set "error" in your own repo
to hold your skills to the explicit-metadata standard.
Scope
skills/*/SKILL.md + .claude/skills/*/SKILL.md. Deterministic, model-free.
Why
The fallback description is what the model selects on — and an accidental one (a
# Heading or a boilerplate first line) is exactly how a structurally-fine skill
ends up never firing. Whether a description actually triggers is the behavioral
audit trigger-tier question; this rule is the cheap, deterministic upstream nudge to
write a real one in the first place.
See also
subagent-frontmatter— the subagent requirement (won't register), vs this skill recommendation (still loads).