Instructions

Telemetry

.claude/skills/test-skills/test-skills.sh "$ARGUMENTS"
echo "sidecar exit: $?"

• it already ran, so there is no command to issue
• no argument runs every sidecar under plugins/*/skills/ and .claude/skills/; a path scopes it
• scanned: N sidecar(s) → what the run covered, which is one sidecar per skill directory
• adopted: N without a --test case → skills still outside the contract, and each one is a WARN
• help: requested from a --help invocation → read ## Help and run nothing
• fail (sidecar exit > 0) → a tier failed, or a WARN landed under --strict; quote the findings table verbatim inside a markdown code block, and fix nothing until the user has read it
• success (sidecar exit = 0) → report errors and warnings, then work the table top to bottom
• --quick reports inline and writes nothing, --strict promotes warnings to errors
• IF --quick, STOP after the inline report; audit_file: none confirms it, and nothing is appended

1. READ the table and group the rows by tier, since one broken shared file fails many skills at once
2. NAME the tier each failure landed in, since the tier says how far the sidecar got before it broke
3. TREAT a t0 row as the most urgent, since a file that will not parse never ran at all
4. TREAT a t3 row as a lie the exit code told, since the case returned 0 and proved nothing
5. QUOTE the detail column verbatim for every FAIL, since it carries the path or the repair
6. RUN the handover's per-skill line to read one failure in full, rather than re-running the tree
7. STOP after reporting; a repair is the user's to approve, and the tool mutates nothing itself

the artifact

append one entry to [audit_file], in the shape under ## the entry below:

• the heading reads ## Smoke Audit #[next_audit]: [timestamp], both taken from the telemetry
• state is the scan counts and the probes directory, as hyphen bullets, one clause each
• results is the skill/tier/result/detail table the sidecar printed, as a markdown table
• telemetry is the sidecar's whole output, fenced and unedited, pasted last
• CREATE the file first if it does not exist, with # <audit_file> as its only line
• the sidecar names the path and the count and writes nothing, so a ci run leaves no entry
• the run writes nothing under that directory itself, so an absent file means nobody recorded a run

the entry

the artifact this skill appends to; /gitgud:audit grades the shape on its next run

.construct/maintainer/test-skills/YYYY-MM-DD.md

one file per day, appended to by every run:

• an entry captures one run at a moment in time, so it is never edited after the fact
• lines are hyphen bullets holding a single clause, capped at 100 characters

Smoke Audit #1: YYYY-MM-DD HH:MM

state

the sidecars scanned, the two counts, the skills still without a case, and the probes directory

example:

• scanned: 32 sidecar(s), 0 error(s), 0 warning(s)
• probes: .construct/maintainer/test-skills/probes, kept: no

results

the table the sidecar printed, one row per tier per skill

example:

| gitgud:audit | t3-artifact | ok | 6 check(s), 0 note(s), 0s |

telemetry

the sidecar's whole output, fenced and unedited

the tiers

each tier runs only when the one before it passed, so one break reports once rather than four times:

• t0 parses the file: bash -n, the shebang, shellcheck at error level, and the tracked exec bit
• t1 asks it two questions: --help prints its marker, and an unknown flag is refused
• a refusal is any non-zero exit, since fatal: and usage: both refuse and the wording is nobody's
• a confirm gate refuses too, by pricing the run and stopping before it ever parses a flag
• the flag question is asked only of a skill whose argument-hint declares nothing past its flags
• a skill taking prose or a path reads a dash-leading word as its own argument, and is right to
• the hint is the declaration, so the doc decides which skills the question even applies to
• t2 resolves what the sidecar declares about itself, reading its text and never running it
• t3 runs --test, which is the only tier that executes the skill's file at all
• nothing here does the skill's work; a real run belongs to the trigger a user invokes on purpose
• a t0-mode row is the break that only ever lands on someone else's machine, so it is an error here

what t2 resolves

every check reads the sidecar's own text, so a broken reference is named whether or not it runs:

• source stats every # shellcheck source= path, since a sourced file dying takes the plugin down
• ci runs shellcheck --severity=warning, where a missing source is SC1091 at info and passes
• so this tier is the only gate in the repo that fails a sourced file that moved or was deleted
• see stats every path on the @see line, which is how a rename that missed one gets caught
• a missing FILE on that line is a failure, and a missing DIRECTORY is a note, never a failure
• an artifact directory is written by a run nobody has made yet, so its absence proves nothing
• tool resolves every binary the file guards on with command -v, naming a machine gap as one

the --test contract

every sidecar answers --test the same way, so the case is COPIED rather than written:

case " $* " in *" --test "*) echo "test: ok"; exit 0;; esac

• it sits directly below the --help case, above every preflight and every confirm gate
• a test that has to pay for a confirm is a test nobody runs, which is why it sits that high
• the line is identical in all 32 sidecars: no path, no invocation name, nothing to paste wrong
• it proves the file parses and the guards above it returned, and deliberately nothing more
• the checks that need a sidecar's declarations live in t2, which reads them from outside
• one shared helper for this would be three byte-identical copies, one per plugin, to print a marker

Verify

not part of the trigger; these run after a doc or a sidecar changes

• RUN .claude/skills/test-skills/test-skills.sh after moving a shared file or renaming any path
• EXPECT zero warnings, since ci runs --strict and every sidecar already carries the case
• CONFIRM a new sidecar carries the --test case, since validate-skills warns and does not block
• CONFIRM this sidecar reads 100755 under git ls-files -s, since the disk bit lies
• FIX every t0-mode row, since that break reaches only the people who installed from a clone
• RERUN a disagreeing t3 row scoped to that one path, since this sidecar writes no scratch to keep

Help

IF the invocation carries --help or -h, this section is the whole turn:

SKILL: /plugin:name
DESCRIPTION: <the `description` frontmatter, verbatim>
POSTURE: <the readme index's keyword for this skill>
FLAGS:
- --flag: <what it changes, in the telemetry bullet's own words>
ARGUMENTS:
- <arg>: <what it names>
ARTIFACT: <the `metadata.artifact` path, or none>
OUTPUT: <what lands in the turn: an audit entry, a handover block, an inline report>
SPEC: <this doc's own path>

• every field prints, in this order; one with nothing to say prints none
• every value is COPIED from the source named beside it, never composed fresh
• ask what they are actually trying to do, and what they have already tried
• name the flag or the sibling skill that fits their answer, then STOP
• run no step, write no file, and never fall through to step 1