Packs: skip README.md silently so a pack can carry a human-facing README without frontmatter

Author: kieranklaassenCreated Sep 10, 2026Updated Sep 10, 2026

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:

  1. 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.
  2. 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

Source: EveryInc/compound-engineering-plugin