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.
76 lines
4.1 KiB
Markdown
76 lines
4.1 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 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/templates` climbs one level from a `scripts/`
|
|
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`.** Its `Research doc:` fields are development-time provenance pointers,
|
|
not runtime references. They are expected to be unresolvable after install, so
|
|
`validate-provenance.sh` does 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 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.
|
|
|
|
The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
|
|
which Step 3 loads on every run.
|