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

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