Defame1297
1ec3e8a1ea
skill-author still told authors to move description overflow "to the body or to README.md" while this branch deleted every per-skill README.md, every references/README.md and the README scaffold template. factory-audit's skill-file-structure.md bans non-spec files at the skill root, and the line that used to carve README out of that rule went with them. So skill-author created the file, factory-audit failed it, and nothing read it.8ce5392fixed the two scripts and missed the reference prose. The two contract.md files now differ deliberately: a skill's overflow goes to the body or a references/ file, an agent's to the body alone, because an agent is a single file with no references/ directory to disclose to. agent-description-quality.md's "the plugin's README.md" is left alone, plugin READMEs being the ones that survive. Deleting retrofit.md also dropped three instructionsbaa2f5ddid not restore with the cut list, two of which retrofit.md itself recorded as having no validator behind them: re-cite sources.md's Contributing files after content moves, since validate-provenance exits 0 on exactly that drift, and re-check a relocated gate's reachability, since a Gotcha moved into one flow's file is invisible to the others and the word counts improve either way. The third is that boundary clauses are plural — contract.md read as a cap where git-remotes carries four. Also: contract.md named an unqualified scripts/validate.sh that does not exist in skill-author, which skill-file-structure.md calls a hard error; and agent-body-and-delegation.md's simile pointed at a stale README row as the characteristic skill defect, a defect class that can no longer occur, replaced with a SKILL.md naming a references/ file that is not there. skill-author 1.0.4, agent-author 1.0.3, factory-audit 1.0.2. 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.