coilyco-flight-deck/agentic-os

Watch

fix(documentation-layout): stop capping the references/ files check-skills tells authors to write #1332

Merged

coilyco-ops merged 1 commit from ops/skill-references-uncapped into main

2026-08-28 03:23:12 +00:00

coilyco-ops commented

2026-08-28 03:21:51 +00:00

Owner

Two hooks disagreed about one file, and the docs already said so

docs/documentation-bands.md names this outright: "Two hooks disagreeing about one file is a defect in the suite, not a decision an author can act on." It then recorded the leftover case rather than closing it.

check-skills caps SKILL.md and answers an over-long one with "Move detail into a sibling references/ file". It caps nothing under references/ itself.
docs/skill-discipline.md:47 states it plainly: "Reference files are not capped."
documentation-layout capped them at the band caps anyway.

So an author who followed the remedy the suite handed them failed a different hook for doing it. This is the same defect #1110 fixed for SKILL.md and COMPOSED.md; that fix was scoped to the two entrypoint basenames and never carried to the tree those entrypoints overflow into.

Scope

The exemption is the remedy check-skills names, not a blanket pass on skill trees:

A Markdown file sitting directly in a skill directory still takes the cap.
references must be a directory component, so a file named references.md is not exempt.
Outside a skill root, docs/references/a.md is unaffected.

Each of those is a test.

Provenance

Found from coilyco-gaming/galaxy-gen, whose pyproject.toml said this in a comment and called the fix upstream:

The .agents/skills entries fail a cap their own spec disclaims - tooling-skill-authoring says SKILL.md is capped at 500 lines / 10 KB and "Reference files are not capped" - so two validators disagree and the fix is upstream.

Right on both counts. Its two wikipedia-concepts.md reference files become legal at the next tag with no content edit, and inbox#439 measured this same class as the dominant burden across three other repos, where it was only masked by flipping a band.

Doc change is line-neutral

docs/documentation-bands.md sits at exactly 120 lines against a 120-line cap, so the paragraph was rewritten in place rather than extended.

750 tests pass and pre-commit run --all-files exits 0.

## Two hooks disagreed about one file, and the docs already said so `docs/documentation-bands.md` names this outright: **"Two hooks disagreeing about one file is a defect in the suite, not a decision an author can act on."** It then recorded the leftover case rather than closing it. * `check-skills` caps `SKILL.md` and answers an over-long one with *"Move detail into a sibling `references/` file"*. It caps nothing under `references/` itself. * `docs/skill-discipline.md:47` states it plainly: *"Reference files are not capped."* * `documentation-layout` capped them at the band caps anyway. So an author who followed the remedy the suite handed them failed a different hook for doing it. This is the same defect #1110 fixed for `SKILL.md` and `COMPOSED.md`; that fix was scoped to the two entrypoint basenames and never carried to the tree those entrypoints overflow into. ## Scope The exemption is the remedy check-skills names, not a blanket pass on skill trees: * A Markdown file sitting directly in a skill directory **still takes the cap**. * `references` must be a **directory component**, so a file named `references.md` is not exempt. * Outside a skill root, `docs/references/a.md` is unaffected. Each of those is a test. ## Provenance Found from `coilyco-gaming/galaxy-gen`, whose `pyproject.toml` said this in a comment and called the fix upstream: > The `.agents/skills` entries fail a cap their own spec disclaims - `tooling-skill-authoring` says SKILL.md is capped at 500 lines / 10 KB and "Reference files are not capped" - so two validators disagree and the fix is upstream. Right on both counts. Its two `wikipedia-concepts.md` reference files become legal at the next tag with no content edit, and inbox#439 measured this same class as the dominant burden across three other repos, where it was only masked by flipping a band. ## Doc change is line-neutral `docs/documentation-bands.md` sits at exactly 120 lines against a 120-line cap, so the paragraph was rewritten in place rather than extended. 750 tests pass and `pre-commit run --all-files` exits 0.

coilyco-ops added 1 commit

2026-08-28 03:21:51 +00:00

fix(documentation-layout): stop capping the references/ files check-skills tells authors to write

ci / aos-eval-tests (pull_request) Successful in 7s

Details

ci / ward-doctor (pull_request) Successful in 7s

Details

ci / aos-cli-tests (pull_request) Successful in 33s

Details

ci / gate (pull_request) Successful in 53s

Details

1330457be7

Two hooks in this suite disagreed about one file, which docs/documentation-bands.md
already names as a defect in the suite rather than a decision an author can act on.

check-skills caps SKILL.md and answers an over-long one with "Move detail into
a sibling references/ file". It caps nothing under references/ itself, and
docs/skill-discipline.md states outright that reference files are not capped.
documentation-layout capped them at the band caps anyway, so an author who
followed the remedy the suite gave them failed a different hook for it.

This is the same defect #1110 fixed for SKILL.md and COMPOSED.md. That fix was
scoped to the two entrypoint basenames and never carried to the tree the
entrypoints overflow into, and the bands doc recorded the leftover tension in
so many words rather than closing it. Closing it now.

The exemption is the remedy check-skills names, not the whole skill tree: a
Markdown file sitting directly in a skill directory still takes the cap, and
`references` has to be a directory component rather than a filename.

Found from coilyco-gaming/galaxy-gen, whose pyproject said this in a comment
and called the fix upstream. It was right on both counts. The two
wikipedia-concepts.md reference files it was failing on are legal at the next
tag with no edit, and inbox#439 measured this same class as the dominant
burden across three other repos.

Refs coilysiren/inbox#374, coilysiren/inbox#439

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

coilyco-ops merged commit c1d0cbb923 into main

2026-08-28 03:23:12 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-28 03:23:13 +00:00

fix(documentation-layout): stop capping the references/ files check-skills tells authors to write (#1332)

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/agentic-os!1332

No description provided.

Rows
Columns