---
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, and the sourced libraries those entry
  points load. A `lib-*.sh` that is never invoked on its own belongs here beside the entry point
  that sources it — it is executable code, not documentation, so do not flag it for failing to run
  standalone. 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-author's references/contract.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/contract.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:` and `Basis:` fields are development-time
  provenance pointers, not runtime references. A `Research doc:` path that does not resolve after
  install is expected, so `validate-provenance.sh` does not treat an absent path as a FAIL — it
  emits an INFO naming the slug and stating that check 7 did not run for it. Flagging them as
  broken references would make every correctly-provenanced skill fail. Where the path DOES
  resolve, it is checked: `Research doc:` names exactly one Research registry (a `sources.md`
  whose H2 headings are the source slugs), and a slug missing from it, a topic document in its
  place, or a list of paths is a FAIL. An entry with no registry writes `Research doc: none` plus
  `Basis:` repo paths, which are existence-checked unless annotated `(removed in <sha>)`.
- **`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/skill-finding-criteria.md`,
which Step 3 loads on every run.