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

Merged

coilysiren merged 1 commit from aos/claude/aw85-skill-size-owner into main

2026-08-17 01:22:23 +00:00

coilyco-ops commented

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

Member

Closes #1109. Unblocks four repos on coilysiren/inbox#374.

Two hooks in one suite disagreed about the same file. documentation-layout applied the band's per-file cap to SKILL.md and COMPOSED.md (40 lines / 3,000 chars on small) while check-skills allows 500 lines / 10,000 bytes for those same files from categories.yaml.

The failure a skill got was also the wrong instruction:

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

A skill overflows into its own references/, which check-skills leaves uncapped on purpose.

Scope of the exemption

The two entrypoint basenames only. Every other Markdown file under a skill directory still takes the band cap, and the test asserts an ordinary doc of the same size still fails, so this is not a hole in the check.

Why it matters now

Measuring the fleet for the band migration found 56 skill files in this state across 23 repos, and it was the dominant burden in four repos whose docs/ were already clean: agentic-os-kai (73 non-docs files), deploy (42), agentic-os-xxx (34), agentic-os-hardware (15). Their issues told them not to start that part pending this decision.

Verification

Mutation: removing the two basenames fails test_skill_entrypoints_take_no_size_cap_from_this_hook.

pre-commit run --all-files clean, 540 tests green.

Closes #1109. Unblocks four repos on coilysiren/inbox#374. Two hooks in one suite disagreed about the same file. `documentation-layout` applied the band's per-file cap to `SKILL.md` and `COMPOSED.md` (40 lines / 3,000 chars on small) while `check-skills` allows 500 lines / 10,000 bytes for those same files from `categories.yaml`. The failure a skill got was also the wrong instruction: ``` .agents/composed/kai-aws-auth/COMPOSED.md: 3628 chars exceeds the 3000-char cap. Split large docs into smaller docs/*.md files. ``` A skill overflows into its own `references/`, which `check-skills` leaves uncapped on purpose. ## Scope of the exemption The two entrypoint basenames only. Every other Markdown file under a skill directory still takes the band cap, and the test asserts an ordinary doc of the same size still fails, so this is not a hole in the check. ## Why it matters now Measuring the fleet for the band migration found **56 skill files** in this state across 23 repos, and it was the dominant burden in four repos whose `docs/` were already clean: agentic-os-kai (73 non-docs files), deploy (42), agentic-os-xxx (34), agentic-os-hardware (15). Their issues told them not to start that part pending this decision. ## Verification Mutation: removing the two basenames fails `test_skill_entrypoints_take_no_size_cap_from_this_hook`. `pre-commit run --all-files` clean, 540 tests green.

coilyco-ops added 1 commit

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

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

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

Details

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

Details

ci / gate (pull_request) Successful in 50s

Details

fd59232972

Two hooks in one suite disagreed about the same file. documentation-layout
applied the band's per-file cap to SKILL.md and COMPOSED.md, 40 lines and 3,000
chars on the small band, while check-skills allows 500 lines and 10,000 bytes
for those same files from categories.yaml.

So a skill could pass the validator that owns skills and fail the one that owns
layout. The failure it got was also wrong for it:

  .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 handbook documents.

Both entrypoints are exempt here now, scoped to those two basenames so every
other Markdown file under a skill directory still takes the band cap. A test
pins that split, and removing the exemption fails it.

Found while measuring the fleet for the band migration: 56 skill files across
23 repos were in that state, and it was the dominant burden in four repos whose
docs were already fine. Kai's call on coilysiren/inbox#374.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

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

coilyco-ops referenced this pull request from coilyco-flight-deck/agent-compose

2026-08-17 01:11:07 +00:00

docs: 65 docs to 40 #293

coilyco-ops referenced this pull request from coilyco-flight-deck/agent-proxy

2026-08-17 01:11:11 +00:00

docs: 68 docs to 20, 43 oversized docs #133

coilyco-ops referenced this pull request from coilyco-flight-deck/infrastructure

2026-08-17 01:11:15 +00:00

docs: 127 docs to 40, 1 oversized docs #856

coilyco-ops referenced this pull request from coilyco-flight-deck/lunch-money-k8s