Packs: skip README.md silently so a pack can carry a human-facing README without frontmatter
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_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. - Leave the frontmatter off and accept a warning per pack on every resolve and every
/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. 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
Source: EveryInc/compound-engineering-plugin