Files

Defame1297 164948a0bc fix(apm-workflow): type: selects processing, it does not validate content

configure.md said apm.yml's `type:` field "constrains what .apm/ may
contain" and that changing it later "does not retroactively validate what
is already on disk" — both implying a validation step that does not exist.
Read against the installed apm-cli 0.28.0: PackageContentType controls how
a package is processed during install/compile, apm_package.py only
enum-checks the declared string, and validate_apm_package() branches on the
structural type derived from files on disk, never on the declared field.
There is no content-vs-type mismatch check anywhere.

The hazard is therefore the opposite of what the wording primed for:
silent omission. A package declaring type: instructions while shipping
.apm/skills/ installs no skill and compiles AGENTS.md only, exits 0, and
reports success having shipped none of its primitives. The rule is now to
verify deployed output rather than the exit code. apm-orchestrate carried
the same wording as a Hard Rule and is corrected in step; its separate
defects stay with #120.

Also refreshes the exemplar figures this branch had re-staled. 264a5db set
them to 3,222 words of references; 6cb47f8 then added 63 words and
invalidated them, and the correction above adds more. Re-measured after
all edits: body 237 and whole-file 304 both still hold, references total
3,416. body-discipline.md's "roughly 3,200" moves with it.

ADR-0020 is deliberately untouched — it self-pins its citations to
f9b919d — as is the git-commits negative example pinned to 5e23250.

Refs #99

2026-08-30 20:51:45 +00:00

assets/vale

feat(kyberforge): enforce the ADR-0020 context contract for skills and agents

2026-08-14 21:13:13 +00:00

references

fix(apm-workflow): type: selects processing, it does not validate content

2026-08-30 20:51:45 +00:00

scripts

fix(gates): restore byte-identity of the shared ADR-0020 boundary resolver

2026-08-30 16:42:51 +00:00

README.md

fix(kyberforge): restore skill-audit's script-failure fallback and E100 diagnostic

2026-08-16 16:40:00 +00:00

SKILL.md

fix(kyberforge): restore the authoring rules the ADR-0020 trim dropped

2026-08-16 19:49:38 +00:00

README.md

skill-audit

Audit a skill directory against the agentskills.io specification and the house context-budget contract (ADR-0020). Runs structural validation then a qualitative review across description quality, body discipline, patterns, formatting, file structure, scripts, and internal consistency, plus a provenance chain check.

What it does

Runs scripts/validate.sh and scripts/validate-provenance.sh for structural and provenance checks, plus scripts/vale-wrap.sh — a Vale prefilter that deterministically flags non-imperative description openers, composition and architecture notes, vague wording, padding phrases, and "There is/are" sentence openers
Reads all files in the skill directory
Applies qualitative checks across five dimension groups, loading one rubric from references/ per group
Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to skill-author

validate.sh enforces two independent length families that must not be conflated: the agentskills.io spec conformance ceilings (500 lines, 2,770 words, both counting the whole file) and the ADR-0020 context budget (250/400 description characters, 600/900 body-only words).

Alongside those it runs four shape checks that are not length measurements at all. Two are FAILs: every routing target named in the description — in the compressed Not <thing> -> <name> arrow and in the prose form — must resolve to a real skill or agent, and every references/<file>.md the body names must exist on disk. Three are SUGGESTIONs: a missing boundary clause, a Gotchas section over five entries, and a Gotchas section over 25% of the body. The resolution universe for boundary targets is derived by walking up from the audited SKILL.md — the authoring root above it, its own apm package, and that package's declared apm.yml dependencies — so a fresh clone and a machine that has run apm install return the same verdict. When no universe can be determined the check prints INFO ... DID NOT RUN and does not silently pass.

Usage

/skill-audit

Provide the path to the skill directory to audit when invoking.

Files

File	Purpose
`SKILL.md`	Skill instructions for agents
`scripts/validate.sh`	Structural validator — checks name format, name matches directory, description presence and length, body-only word count, line and whole-file word ceilings, boundary-clause presence, boundary-target resolution, `references/` pointer existence, Gotchas entry count and body share, placeholder detection, script executable bit, and interactive-prompt detection
`scripts/validate-provenance.sh`	Provenance validator — checks sources.md completeness, source_keys/slug consistency, Contributing files existence, bidirectional linkage, Research doc: fields, and upstream research doc alignment
`scripts/vale-wrap.sh`	Vale prefilter wrapper — runs the bundled `Kyberforge` Vale styles against SKILL.md and reports alerts as deterministic FAILs ahead of Step 3's qualitative review
`assets/vale/.vale.ini`	Vale configuration — points Vale at the bundled `Kyberforge` style path, self-located relative to `vale-wrap.sh`
`assets/vale/styles/Kyberforge/CompositionNote.yml`	Vale rule — flags composition and architecture notes in a description (e.g. "cross-cutting", "entry point", "rather than duplicating")
`assets/vale/styles/Kyberforge/DescriptionOpener.yml`	Vale rule — flags non-imperative "This..." description openers
`assets/vale/styles/Kyberforge/PaddingPhrase.yml`	Vale rule — flags generic "see references/" padding phrasing in conditional references
`assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml`	Vale rule — flags body sentences starting with "There is"/"There are"
`assets/vale/styles/Kyberforge/VagueWording.yml`	Vale rule — flags known filler wording (e.g. "helps with", "utilize")
`references/description-quality.md`	Rubric for the description dimension — three-part shape, the 250/400-character budget, the hand-invoked (`disable-model-invocation`) contract, and the internal-mechanics FAIL
`references/body-discipline.md`	Rubric for the body-discipline dimension — the core test, the 600/900 body-only budget against the 2,770-word whole-file backstop, the mandatory-dispatch rule, and the Gotchas constraints
`references/patterns.md`	Rubric for the patterns dimension — which instruction construct fits which job, and how each is correctly formed
`references/file-structure.md`	Rubric for the file-structure and internal-consistency dimensions — permitted directories, cross-plugin path rules and their two structural exemptions, README drift
`references/formatting-and-scripts.md`	Rubric for the formatting and scripts dimensions — heading and fencing conventions, and the agentic-use criteria for bundled scripts
`references/validation-scripts.md`	Step 1 troubleshooting — the manual structural fallback when `validate.sh` cannot run, and the script exit codes that are easy to misread (loaded only on a script failure)
`references/sources.md`	Provenance record — agentskills.io sources that informed this skill and which files each contributed to
`tests/validate.bats`	(source-only) Bats test suite for validate.sh
`tests/validate-provenance.bats`	(source-only) Bats test suite for validate-provenance.sh
`tests/README.md`	(source-only) Setup instructions for bats-support and bats-assert test dependencies

Rows marked (source-only) exist in the authoring source (.apm/skills/skill-audit/) but are not present in an installed plugin: scripts/sync-plugin-content.sh strips <category>/<name>/tests when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.