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

## 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 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. Two 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.
- Placeholder READMEs inside `scripts/`, `tests/` and `assets/` say the same thing about each
  directory that `SKILL.md` does.

The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
which Step 3 loads on every run.