#315
fix: rename skill dirs to match frontmatter, surface React Compiler caveat, fix listener/guidelines examples
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, andreact-view-transitionsdon't match theirSKILL.mdfrontmattername:(agentskills.io spec requires directory name == frontmatter name). The frontmatter names are already the canonical cross-reference ID used throughoutvercel-optimize's docs/tests/scanner andskills.sh.json, so the 4 directories are renamed to match (not the reverse). Also fixespackages/react-best-practices-build's config/scripts, the CI workflow's path filters, a stale directory-name reference invercel-react-view-transitions/README.md, and the top-levelREADME.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 inSKILL.mdplus a prominent "Skip if" callout on the 3 rules it actually affects (the other 12rerender-*rules are unrelated to React Compiler and untouched). - #68 —
client-event-listeners.md's example misuseduseSWRSubscription()(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-guidelinesfetched its instructions from a GitHub raw URL on every invocation — an unpinned supply-chain/reproducibility risk. Vendored the current upstream content asreferences/guidelines.md, pinned to a specific commit, with a documented refresh procedure.
Notes
- The two pre-built
.ziparchives underskills/(react-best-practices.zip,react-view-transitions.zip) will reference stale paths after the rename, andweb-design-guidelines.zipwill 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
callbackidentity, 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 inadvanced-event-handler-refs.md.
Test plan
-
pnpm build && pnpm validatepasses (frompackages/react-best-practices-build/) - Repo-wide grep confirms no remaining reference to the 4 old bare directory names outside the
.ziparchives - 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.
Someone is attempting to deploy a commit to the Vercel Team on Vercel.
A member of the Team first needs to authorize it.