---
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.