Files

Defame1297 5a52949c57 feat(kyberforge): make Research doc name one Research registry

validate-provenance.sh assumed `Research doc:` names a research
sources.md whose H2 headings are the source slugs, but 29 corpus entries
named topic docs and 6 values were not a single path, so checks 7 and 8
reported INFO for 36 entries and nothing ever failed.

`Research doc:` now takes exactly one path. An entry with no registry
writes `none` plus one `- **Basis:** <path>` bullet per path; each Basis
path is existence-checked unless annotated `(removed in <sha>)`.

- Check 7 FAILs when a resolved registry lacks the slug, when the value
  is a topic doc, or when it is a list. An unresolvable path stays INFO.
- Check 8 is retired: one registry serves many skills, so requiring
  every registry slug in each skill's sources.md is unsatisfiable.
- The Research doc and Basis parsers accept the inline, bullet and
  header-plus-bullets spellings, so a differently spelled field is no
  longer read as absent.

Refs: #121
ADR: 0028
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EGHFJextYtVQseaHPDDhxB

2026-09-21 17:28:08 +00:00

4.4 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, and the sourced libraries those entry points load. A lib-*.sh that is never invoked on its own belongs here beside the entry point that sources it — it is executable code, not documentation, so do not flag it for failing to run standalone. 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-author's references/contract.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/contract.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: and Basis: fields are development-time provenance pointers, not runtime references. A Research doc: path that does not resolve after install is expected, so validate-provenance.sh does not treat an absent path as a FAIL — it emits an INFO naming the slug and stating that check 7 did not run for it. Flagging them as broken references would make every correctly-provenanced skill fail. Where the path DOES resolve, it is checked: Research doc: names exactly one Research registry (a sources.md whose H2 headings are the source slugs), and a slug missing from it, a topic document in its place, or a list of paths is a FAIL. An entry with no registry writes Research doc: none plus Basis: repo paths, which are existence-checked unless annotated (removed in <sha>).
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/skill-finding-criteria.md, which Step 3 loads on every run.

4.4 KiB Raw Blame History

File Structure and Internal Consistency Reference

Permitted directories

Cross-plugin path references

Internal consistency

4.4 KiB

Raw Blame History