Problem
The pack resolver treats every top-level .md in a pack as a rule candidate. A file without title + applies_when frontmatter draws a warning:
skipped pack file `<id>/README.md` (missing `title`/`applies_when` frontmatter)
See skills/ce-setup/scripts/packs-resolve.py, the loop after _is_knowledge_file (around line 433).
That leaves pack authors two options, both awkward:
- Give the README frontmatter. Then it becomes a rule: its
applies_when fires during planning and review, and the whole README body (index, evidence notes, maintenance guidance) loads into context as if it were a prescriptive rule. The frontmatter also duplicates the "when to add this pack" section a human README wants.
- Leave the frontmatter off and accept a warning per pack on every resolve and every
/ce-setup health check.
We hit this in EveryInc/compound-packs, where each pack has a README written for people deciding whether to add the pack. The docs/guides/packs.md layout example already shows a repo-level README.md as "ignored — no frontmatter", but that only holds at the source root, not inside a pack directory.
Proposal
Treat README.md (case-insensitive) inside a pack directory as a human-facing file: never a rule, never warned about. Everything else keeps the current behavior.
Smallest change: in the enumeration loop, skip the warning when name.lower() == "readme.md", and have _is_knowledge_file return False for it so a README that happens to carry frontmatter is still not ingested.
Docs: add one line to the "Big data in packs" layout rule in docs/guides/packs.md saying README.md is reserved for humans and ignored by the resolver.
Why it matters
A pack is a published artifact people browse on GitHub before adopting. The file GitHub renders first should be able to explain the pack without being loaded as guidance or emitting a warning.
🤖 Generated with Claude Code
Problem
The pack resolver treats every top-level
.mdin a pack as a rule candidate. A file withouttitle+applies_whenfrontmatter draws a warning:See
skills/ce-setup/scripts/packs-resolve.py, the loop after_is_knowledge_file(around line 433).That leaves pack authors two options, both awkward:
applies_whenfires during planning and review, and the whole README body (index, evidence notes, maintenance guidance) loads into context as if it were a prescriptive rule. The frontmatter also duplicates the "when to add this pack" section a human README wants./ce-setuphealth check.We hit this in
EveryInc/compound-packs, where each pack has a README written for people deciding whether to add the pack. Thedocs/guides/packs.mdlayout example already shows a repo-levelREADME.mdas "ignored — no frontmatter", but that only holds at the source root, not inside a pack directory.Proposal
Treat
README.md(case-insensitive) inside a pack directory as a human-facing file: never a rule, never warned about. Everything else keeps the current behavior.Smallest change: in the enumeration loop, skip the warning when
name.lower() == "readme.md", and have_is_knowledge_filereturnFalsefor it so a README that happens to carry frontmatter is still not ingested.Docs: add one line to the "Big data in packs" layout rule in
docs/guides/packs.mdsayingREADME.mdis reserved for humans and ignored by the resolver.Why it matters
A pack is a published artifact people browse on GitHub before adopting. The file GitHub renders first should be able to explain the pack without being loaded as guidance or emitting a warning.
🤖 Generated with Claude Code