Defame1297
175ea89c0a
Check 9 shipped in #130 to close #118, but three defects meant it could not do the job it was added for. Why: - It is INFO-only, so it always exits 0 — and SKILL.md graded exit 0 "a genuine pass" and said the script "prints nothing on success". Every check-9 INFO was discarded before it reached a report, behind three further doors that only opened on a non-zero exit. - `parse_field_raw()` matched `(.+)`, which does not span newlines, so only the first physical line of a wrapped value was compared. Rewriting only the continuation line of a wrapped Description from a hedge to a confident claim produced no finding at all — verbatim the regression #118 was filed about. The bullet branch had the same shape: a wrapped bullet broke the loop and dropped every later entry. - A `git show` failure at the base ref was treated as "creation, nothing to flag" and skipped the whole skill with no output, collapsing "absent at that ref" with "not tracked under that name". A gitignored `.claude/skills/` copy reported clean while the authoring path reported four changed claims. The script's own usage text promises this is "never a silent skip". Implementation notes: - Exit-code guidance re-keyed on output as well as code: 0-and-silent passes, 0-with-output is INFO-only findings, 1 is FAILs, 2 never ran. - `parse_field_raw()` is line-based and joins continuation lines; `normalize_field_text()`'s docstring is now true rather than aspirational. A reorder deliberately fires: the two fields share one parser, and order-insensitivity would mean splitting a prose Description on commas. - The discarded `show_err` is now surfaced as one whole-check INFO naming both readings. - `--base-ref=` given empty now beats the env var, as the usage text always claimed. `validate.sh` gains an ADR-0022 `metadata.version` check at FAIL tier, because any lower tier lets skill-author Step 4 report done on a file the commit gate then refuses. Its `read` heuristic now skips here-doc bodies — reflowing the one offending line would have cleared the finding and left the cause, since every usage() heredoc is one wrap from putting the English verb in column 0. Impact: provenance tests 73 -> 82, validate tests 64 -> 72. Test 72 previously deleted origin/main before asserting the override, so it proved the flag works with no default rather than that it beats one; it now moves origin/main forward first. Refs: #118 ADR: 0022 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
5.4 KiB
name, description, allowed-tools, metadata
| name | description | allowed-tools | metadata | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| skill-audit | Use when the user wants a skill directory audited against the agentskills.io spec — "audit this skill", "review my SKILL.md", "is this ready to ship" — or after hand-editing a skill outside skill-author. Not applying fixes -> skill-author. | Bash Read |
|
Gotchas
- Do not narrate PASS/FAIL per check while auditing. Gather findings internally and surface them only in the Step 4 report. Narrating each check as you go is the default failure mode here.
- A skill carrying
disable-model-invocation: trueis hand-invoked — its description is never routed against, so the trigger, capability and boundary rules do not apply. Audit it as one plain human-facing sentence instead. validate.shreports two independent length families: the 500-line / 2,770-word pair counts the whole file for spec conformance, while the 250/400-character and 600/900-word pair is the house context budget and its word half counts the body only. A skill can sit inside one and fail the other — report them separately.- Vale reporting
0 filesscanned means NOT RUN, not clean. Fall back to full Step 3 judgment for every dimension it would have covered.
Step 1 — Deterministic checks
Resolve all three paths against this skill's own directory so they work from a repo checkout and an installed plugin cache alike. Run exactly:
bash scripts/validate.sh <skill-dir>
bash scripts/validate-provenance.sh <skill-dir>
bash scripts/vale-wrap.sh <skill-dir>/SKILL.md
validate.sh findings become the ### Structure dimension — its FAILs and its SUGGESTIONs both, at the tier the script assigned. Report each once; never re-grade one under another dimension. Unresolved boundary targets are where this bites, because their tier turns on notation.
Read references/validation-scripts.md when any of the three cannot run or exits non-zero for a reason other than findings, and whenever validate-provenance.sh exits 0 having printed anything. Ordinary content FAILs are the expected outcome here and need no fallback.
validate-provenance.sh reports through exit code and output; neither alone is the verdict. 0, silent is a genuine pass. 0 with output is INFO-only findings — still a ### Provenance dimension; references/validation-scripts.md says what each obliges — for a check-9 INFO, reading rather than relaying. 1 is FAILs plus any INFOs; it emits Why and Fix itself — surface those verbatim. 2 means it never ran — a usage or environment error, reason on stderr, often no stdout — so report ### Provenance unverified and quote that reason. Never grade an exit 2, or an exit 0 that printed, as a clean pass.
vale-wrap.sh applies the bundled Kyberforge style as a prefilter. Pass no --config; the wrapper locates its own. Every rule is graded error, so every alert is a FAIL. Report each one citing its rule ID, filed under the dimension it belongs to, and do not re-derive it by judgment:
| Rule | Dimension |
|---|---|
Kyberforge.DescriptionOpener, Kyberforge.CompositionNote, Kyberforge.VagueWording |
description |
Kyberforge.SentenceOpenerThereIs |
body-discipline |
Kyberforge.PaddingPhrase |
patterns |
Step 2 — Read the whole skill
Read SKILL.md, README.md, and every text file under scripts/, references/, assets/ and tests/. Skip binaries only — internal-consistency findings need the full picture.
Step 3 — Qualitative audit
Read references/finding-criteria.md first — every dimension's FAIL and SUGGESTION criteria. Load the rubric below only for a dimension the criteria put in play: one carrying a candidate finding, or one where the criterion alone does not settle the call.
| Dimension | Rubric |
|---|---|
| description | references/description-quality.md |
| body-discipline | references/body-discipline.md |
| patterns | references/patterns.md |
| file-structure, internal-consistency | references/file-structure.md |
| formatting, scripts | references/formatting-and-scripts.md |
Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget (ADR-0020). Cite file and line number for every finding.
Step 4 — Report
Open with a coverage line naming every dimension checked:
Checked: structure · description · body-discipline · patterns · file-structure · formatting · scripts · internal-consistency · provenance
Then output only the dimensions that have findings, grouped under H3 headings, FAILs before SUGGESTIONs within each. Omit clean dimensions — their absence is what confirms they passed.
Each finding:
FAIL/SUGGESTION <finding> — file:line
Why: <why this is a problem>
Fix: <exact change — quote before/after where applicable>
Close with a ## Result block holding one line: PASS, PASS (N suggestions), or FAIL (N fails · M suggestions), each optionally followed by · P info. INFO findings are observational and never change PASS/FAIL; omit · P info when there are none. Add a second line, Run skill-author to address findings., whenever there is at least one finding. Do not apply fixes — report and propose only.