holocron/plugins/kyberforge/skills/skill-audit/references/file-structure.md

source_keys

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.