#315

fix: rename skill dirs to match frontmatter, surface React Compiler caveat, fix listener/guidelines examples

OpenSomSamantraywants to merge intofrom

Summary

Four independently-verified, still-open bugs, bundled since each is small and none depend on the others except through the directory rename:

  • #80 — skills/react-best-practices, composition-patterns, react-native-skills, and react-view-transitions don't match their SKILL.md frontmatter name: (agentskills.io spec requires directory name == frontmatter name). The frontmatter names are already the canonical cross-reference ID used throughout vercel-optimize's docs/tests/scanner and skills.sh.json, so the 4 directories are renamed to match (not the reverse). Also fixes packages/react-best-practices-build's config/scripts, the CI workflow's path filters, a stale directory-name reference in vercel-react-view-transitions/README.md, and the top-level README.md's skill-listing headers.
  • #87 — The React Compiler caveat ("manual memo()/useMemo() isn't necessary when React Compiler is enabled") was buried in a trailing note on one rule file. Promoted to a "Pre-flight Checks" section in SKILL.md plus a prominent "Skip if" callout on the 3 rules it actually affects (the other 12 rerender-* rules are unrelated to React Compiler and untouched).
  • #68 — client-event-listeners.md's example misused useSWRSubscription() (a data-subscription hook) for a DOM side-effect (a keyboard listener). Replaced with a plain module-level singleton: attaches once on first consumer, detaches once the last consumer's key is removed.
  • #30 (and its sibling #91) — web-design-guidelines fetched its instructions from a GitHub raw URL on every invocation — an unpinned supply-chain/reproducibility risk. Vendored the current upstream content as references/guidelines.md, pinned to a specific commit, with a documented refresh procedure.

Notes

  • The two pre-built .zip archives under skills/ (react-best-practices.zip, react-view-transitions.zip) will reference stale paths after the rename, and web-design-guidelines.zip will ship the old live-fetch behavior, until whatever external process (not visible in this repo) regenerates them.
  • Code review caught and fixed a subtle bug in the rewritten singleton-listener example: the effect depended on callback identity, so an inline arrow (new identity every render) would tear down/re-attach the real DOM listener on every render — exactly the churn the pattern teaches how to avoid. Fixed by stabilizing the callback via a ref, mirroring the existing pattern in advanced-event-handler-refs.md.

Test plan

  • pnpm build && pnpm validate passes (from packages/react-best-practices-build/)
  • Repo-wide grep confirms no remaining reference to the 4 old bare directory names outside the .zip archives
  • Scratch-tested the singleton listener's attach/detach lifecycle (multi-consumer, same-key, re-mount-after-teardown, and re-render-with-inline-callback cases)
  • Multi-persona code review (correctness, project-standards, agent-native) — 4 findings surfaced and fixed

Fixes #80, #87, #68, #30.