Defame1297
a85bdbed42
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
79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
---
|
|
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
|