Defame1297
e849a823f7
boundary_clause_status() ran BOUNDARY_ARROW.search() and _arrow_targets()
over the whole description, so one arrow clause that parsed suppressed the
diagnostic for every other clause in it. A backticked hyphenated routing
target wrapped across lines in a folded scalar was therefore silently
unchecked -- no error, no suggestion, exit 0 -- whenever the description
carried one other clause that parsed. Written bare, the same wrap errors
correctly. That is the shape #100 regressed on.
The check is now per clause. Nothing that passed starts failing: all 68
routing targets across the 38 SKILL.md files resolved before and still do.
26 of those descriptions carry more than one arrow clause, so the
suppression was live across two thirds of the corpus, not an edge case.
validate-skill.bats pins the shape. test-adr0020-targets.sh's comment
described the #100 regression as a backticked wrap; the historical text was
unbackticked, which is precisely the shape the gate did not catch.
Also closes three README misroutes the branch left in the enforcement
layer: CompositionNote.yml's message, agent-description-quality.md:58 and
vale-wrap.sh's header still sent overflow to a skill-root README.md and
named the two skills ADR-0025 merged away. 1ec3e8a fixed the prose and
missed the rules that enforce it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2
4.2 KiB
name, description, allowed-tools, metadata
| name | description | allowed-tools | metadata | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| factory-audit | Use when the user wants a skill directory or agent definition audited, including "is this ready to ship", or after hand-editing one outside its author skill. Not applying skill fixes -> skill-author. Not applying agent fixes -> agent-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 file 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. - Vale reporting
0 filesscanned means NOT RUN, not clean. Fall back to full Step 3 judgment for every dimension it would have covered.
Step 0 — Dispatch
Resolve the flow from the target path before running anything. The two flows run different validators over different dimension vocabularies, so dispatching after Step 1 means the wrong validator has already produced the wrong findings. The rows mirror the shapes scripts/validate.sh accepts; take the first that matches.
| Target | Flow | Read |
|---|---|---|
A directory containing SKILL.md |
skill | references/skill-flow.md |
A file named SKILL.md — audit its parent directory |
skill | references/skill-flow.md |
A file named *.agent.md |
agent | references/agent-flow.md |
A .md file whose immediate parent directory is agents/ (.apm/agents, .claude/agents, .github/agents, .copilot/agents) |
agent | references/agent-flow.md |
Anything else — a missing path, a directory without SKILL.md, any other file |
none | — |
Read only the file its row matched. Each carries Steps 1 to 3 — the deterministic checks, the read, and the qualitative audit — and is self-contained. Return here for Step 4.
On the last row, stop: run no validator and tell the user the two accepted shapes — a skill directory (or its SKILL.md), or an agent file (*.agent.md, or a .md directly under an agents/ directory). Guessing a flow audits the path against the wrong spec.
The scripts re-detect the flow from the path. If validate.sh reports on the other artifact type than your row, discard what you have and restart here — the flow file, not the script, picked your rubrics, coverage line and remediation line.
Step 4 — Report
Open with the coverage line for the flow you took, naming every dimension checked.
Skill flow:
Checked: structure · description · body-discipline · patterns · file-structure · formatting · scripts · internal-consistency · provenance
Agent flow:
Checked: structure · provider-safety · description · body · delegation · comment-discipline · pair-consistency · provenance
On the agent flow at plugin/APM scope, drop pair-consistency — there is no pair to check.
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 whenever there is at least one finding — Run skill-author to address findings. on the skill flow, Run agent-author to address findings. on the agent flow. Do not apply fixes — report and propose only.