Defame1297
edcc57c0d6
Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
---
|
|
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.
|