Skill entrypoints take the band size cap, contradicting check-skills #1109

New issue

Closed

opened 2026-08-17 01:05:49 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-17 01:05:49 +00:00

Member

documentation-layout applies the band's per-file cap to every Markdown file, SKILL.md and COMPOSED.md included. On the small band that is 40 lines and 3,000 chars. check-skills allows 500 lines and 10,000 bytes for the same file, from categories.yaml.

A skill can therefore pass the hook that owns skills and fail the hook that owns layout. Both ship in this suite.

The failure is also wrong advice:

.agents/composed/kai-aws-auth/COMPOSED.md: 3628 chars exceeds the 3000-char cap.
Split large docs into smaller docs/*.md files.

A skill does not overflow into docs/. It overflows into its own references/, which check-skills deliberately leaves uncapped and the skill-discipline handbook documents.

Scale

Measured across the 23 repos running the hook: 56 skill files are in this state. It is the dominant burden in four repos whose docs/ are already fine, so their band migration was really a skill-catalog rewrite.

Decision

Kai's call on coilysiren/inbox#374: ignore skills. The entrypoints are exempt from this hook's size cap and check-skills owns them.

Acceptance

SKILL.md and COMPOSED.md take no size cap from documentation-layout.
The exemption is scoped to those basenames, so other Markdown under a skill directory still takes the band cap.
A test pins the split and fails if the exemption is removed.

`documentation-layout` applies the band's per-file cap to every Markdown file, `SKILL.md` and `COMPOSED.md` included. On the small band that is 40 lines and 3,000 chars. `check-skills` allows 500 lines and 10,000 bytes for the same file, from `categories.yaml`. A skill can therefore pass the hook that owns skills and fail the hook that owns layout. Both ship in this suite. The failure is also wrong advice: ``` .agents/composed/kai-aws-auth/COMPOSED.md: 3628 chars exceeds the 3000-char cap. Split large docs into smaller docs/*.md files. ``` A skill does not overflow into `docs/`. It overflows into its own `references/`, which `check-skills` deliberately leaves uncapped and the skill-discipline handbook documents. ## Scale Measured across the 23 repos running the hook: **56 skill files** are in this state. It is the dominant burden in four repos whose `docs/` are already fine, so their band migration was really a skill-catalog rewrite. ## Decision Kai's call on coilysiren/inbox#374: ignore skills. The entrypoints are exempt from this hook's size cap and `check-skills` owns them. ## Acceptance * `SKILL.md` and `COMPOSED.md` take no size cap from `documentation-layout`. * The exemption is scoped to those basenames, so other Markdown under a skill directory still takes the band cap. * A test pins the split and fails if the exemption is removed.

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-17 01:05:52 +00:00

fix(docs): skill entrypoints belong to check-skills, not the band cap #1110