Files

Defame1297 a85bdbed42 fix(kyberforge): restore skill-audit's script-failure fallback and E100 diagnostic

The ADR-0020 body trim took `skill-audit` from 2,623 body words to a dispatch
shape, and two things went out with it that were not padding.

The manual structural fallback was one. Its replacement was a single sentence
telling the auditor to report an INFO when `validate.sh` cannot run — so with no
`python3` or no PyYAML, `skill-audit` reported the gap honestly and then audited
nothing structural at all. Every ADR-0020 measurement, the whole-file ceilings,
the name-to-directory match, the `references/` pointer check and the script
hygiene checks silently left the audit. A skill's whole Structure dimension
hanging on one optional interpreter is the same vacuous-pass shape the gate
scripts were just fixed for, one layer up.

The `E100 Runtime error ... does not exist` diagnostic was the other. That exit
code means an explicit relative `--config` was passed to `vale-wrap.sh` while
vale itself was installed and working; without the note, Step 1's fallback reads
exit 2 as "vale unavailable" and downgrades the description, body-discipline and
patterns dimensions to full LLM judgment for a config error it could have fixed.
That misreading is already recorded in CONTEXT.md as the reason both audit skills
stopped passing `--config` at all.

Both are restored in `references/validation-scripts.md`, loaded only when a Step 1
script fails — so the body pays nothing for them on a clean run, which is what the
dispatch pattern is for. The file also carries the by-hand boundary-target
procedure and the three ways to misread the result, including that
`INFO ... DID NOT RUN` is not a pass.

`references/file-structure.md` gains the one sanctioned spelling for a cross-skill
reference. The possessive form (``skill-audit's references/validation-scripts.md``)
is the only spelling both rules accept: a full repo path is what that section
already forbids, and a bare `references/<file>.md` is now a hard ERROR from the
ADR-0020 pointer check, which requires the file to exist in the skill's *own*
directory. Without the rule the two constraints look mutually exclusive.

Refs: ADR-0020

2026-08-16 16:40:00 +00:00

3.9 KiB

Raw Blame History

source_keys

agentskills-spec

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 in tests/.
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.md is 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 any ../, ../../, or absolute repo path (plugins/<plugin>/skills/<other>/ and its APM-native equivalent .apm/skills/<other>/) appearing in SKILL.md, scripts/, references/ or assets/.

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. Its Research doc: fields are development-time provenance pointers, not runtime references. They are expected to be unresolvable after install, and validate-provenance.sh handles that by skipping upstream checks silently when the path is absent. Flagging them would make every correctly-provenanced skill fail.
tests/. Test files are dev-only and may reference repo-level infrastructure such as a shared tests/test_helper/. The exemption is conditional on the dependency being declared: if tests/ exists and tests/README.md is 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/ and assets/ say the same thing about each directory that SKILL.md does.

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.

Auditing guidance

Flag as FAIL if:

A directory outside the four permitted ones exists
Test files sit in scripts/
A non-spec file sits at the skill root
A cross-plugin or parent-relative path appears outside the two exempt locations
tests/ exists but tests/README.md is missing or does not document its repo-level dependency
README.md is absent, or its file table has a missing or stale row
SKILL.md describes a script invocation the script does not accept

Flag as SUGGESTION if:

An optional directory exists but holds only a placeholder README
README.md is accurate but describes a file's purpose more thinly than SKILL.md does

3.9 KiB Raw Blame History