Defame1297
dac9cad912
skill-audit loaded roughly 4,268 words of rubric on every run, most of it criteria for findings a clean skill never triggers. The auditing guidance moves into finding-criteria.md, read only when a finding is actually raised, cutting a clean audit to about 999 words. The named-skill exemption is replaced with properties, so the rubric stops carrying a list that ages the moment a skill is renamed. apm-workflow's `type:` trap sat in one flow while biting several, so it is promoted to a common gate reachable from all of them; its claim to be self-contained was untrue once it started routing to apm-install. skill-author's contract had drifted from body-discipline.md and is realigned, and agent-audit's field inventory is brought in line with the same split.
4.1 KiB
source_keys
| source_keys | |
|---|---|
|
File Structure and Internal Consistency Reference
Upstream source: agentskills.io — specification (optional directories, file references).
Read this when judging the file-structure and internal-consistency dimensions.
Permitted directories
Only four: scripts/, references/, assets/, tests/. The specification permits additional
directories; this house does not, because an unlisted directory is content no auditor and no host
knows to look at. Flag any other directory as a FAIL.
scripts/holds only executable code an agent can run. Test files (.bats,*_test.*,test_*.sh) there are a FAIL — they belong intests/.- No non-spec files at the skill root: no
META.md, no stray config outside the four directories. - An optional directory that exists must hold real content, not an unfilled placeholder README.
README.mdis present and describes the skill and its files accurately.
Cross-plugin path references
A plugin is copied to a cache on install, and a path that climbs out of the skill directory stops
resolving there. Flag a path in SKILL.md, scripts/, references/ or assets/ when it
resolves outside the skill directory — an absolute repo path
(plugins/<plugin>/skills/<other>/ and its APM-native equivalent .apm/skills/<other>/), a
plugin-root path (docs/, bin/), or a ../ chain that leaves the skill root.
Resolve before flagging, twice over:
- Resolve the path.
$SKILL_DIR/../assets/templatesclimbs one level from ascripts/directory and lands back inside the same skill, so it resolves in a cache install and is not a finding. A bare../is not the defect; leaving the skill is. - Skip fenced code blocks. A path inside a fenced block is an example, and rubrics quote outside paths deliberately as negative examples of what not to write. Flag a fenced path only when the surrounding prose presents it as the form to copy.
Referring to another skill's file. There is one sanctioned spelling, and it is possessive:
skill-audit's references/validation-scripts.md. Write the skill by name and let the reader
resolve it — do not spell the repo path. The full path is the thing this section forbids, and
references/validation-scripts.md on its own is a hard ERROR from the ADR-0020 gate, which
requires an unqualified references/ pointer to exist in the skill's OWN directory. The
possessive form is the only spelling both rules accept; the gate recognises it and skips the
on-disk check. Flag any other spelling of a cross-skill reference.
Two directories are exempt, and the exemptions are structural rather than discretionary:
references/sources.md. ItsResearch doc:fields are development-time provenance pointers, not runtime references. They are expected to be unresolvable after install, sovalidate-provenance.shdoes not treat an absent path as a FAIL — it emits an INFO naming the slug and stating that checks 7 and 8 did not run for it. Flagging them as broken references would make every correctly-provenanced skill fail.tests/. Test files are dev-only and may reference repo-level infrastructure such as a sharedtests/test_helper/. The exemption is conditional on the dependency being declared: iftests/exists andtests/README.mdis absent or does not document it, that is a FAIL.
Internal consistency
The skill has to agree with itself. Three checks:
SKILL.md's steps match what the scripts actually do — the arguments, the exit codes, and the output shape it tells the agent to expect.README.md's file table lists every file that exists, with no missing rows and no stale rows for files since deleted.- Placeholder READMEs inside
scripts/,references/andassets/say the same thing about each directory thatSKILL.mddoes.
A stale README row is the most common finding here and the easiest to miss from inside an authoring pass, because the author knows what was intended and reads it into the gap.
The FAIL and SUGGESTION criteria for this dimension live in references/finding-criteria.md,
which Step 3 loads on every run.