Files

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

Skill name+description pairs are preloaded into every session, costing
~6,200 tokens across 39 skills before any skill is invoked. The authoring
rules mandated that growth: skill-author:104 and description-quality.md:21
both required padding, while skill-author:102 (the deflating rule) had no
FAIL condition behind it.

Gates (blocking, no baseline file):
- description 250 chars SUGGESTION / 400 FAIL, measured on the folded
  YAML value
- body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged
  whole-file 2770-word / 500-line spec backstop
- every boundary-clause routing target must resolve to a real skill or
  agent; catches skill-improve, neuledge-context and gitea-labels
- agents take the description gates but deliberately no body gate; a test
  pins that absence

Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule
banning architecture notes from descriptions. 10 hits, 0 false positives.

Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars
(-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow
dispatch pattern. Fixes the skill-improve dangling route and the
agent-author misroute to manual review.

Also fixes a pre-existing false positive where any line-initial 'read '
was flagged as interactive input, which had already caused two scripts to
be rewritten around it.

Refs: ADR-0020

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

3.3 KiB

Raw Blame History

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

3.3 KiB Raw Blame History