feat(skills): add vercel-react-best-practices skill by DeJeune · Pull Request #13424 · CherryHQ/cherry-studio

DeJeune · 2026-03-12T15:54:00Z

What this PR does

Before this PR:
No React/Next.js performance best practices skill available for AI coding agents.

After this PR:
Adds the vercel-react-best-practices skill from vercel-labs/agent-skills, providing 60+ React and Next.js performance optimization rules covering rendering, re-renders, bundling, async patterns, server components, and JS performance.

Why we need it and why it was done in this way

The following tradeoffs were made:

This skill includes ~8 Next.js server-specific rules (server-*, async-api-routes) that are not applicable to our Electron + React project. We chose to keep them rather than fork/trim the skill, since: (1) AI agents will naturally ignore irrelevant rules based on context, (2) keeping the full skill makes future upstream updates easier, and (3) the ~50 React/JS/rendering/bundle rules provide significant value for our codebase.

The following alternatives were considered:

Forking the skill and removing Next.js-specific rules — rejected to avoid maintenance burden and divergence from upstream.
Writing a custom React-only skill — rejected as the Vercel skill already covers the React patterns comprehensively.

Links to places where the discussion took place:

Source: https://github.com/vercel-labs/agent-skills

Breaking changes

None

Special notes for your reviewer

The skill is installed in .agents/skills/vercel-react-best-practices/ as the single source of truth.
.claude/skills/vercel-react-best-practices is a directory symlink pointing to .agents/skills/vercel-react-best-practices/, following the convention established in chore: migrate .claude/skills to directory symlinks #13486. This replaces the earlier approach of copying SKILL.md into a real directory.
public-skills.txt was updated and pnpm skills:sync was run to update .gitignore whitelists.
Windows compatibility: Windows developers need symlink support enabled (via git config core.symlinks true or Developer Mode). This is consistent with the project-wide symlink convention adopted in chore: migrate .claude/skills to directory symlinks #13486, and confirmed working by @GeorgeDong32 on Windows 11 — Claude Code CLI can load skills even when symlinks fall back to plaintext path files.
The skill contains 60+ markdown rule files covering categories: rendering, re-renders, bundle optimization, async patterns, server components, client patterns, and JS performance.

Rule applicability breakdown for our Electron + React project:

Category	Count	Applicable
`js-*` (JS perf)	13	Yes
`rerender-*` (React)	12	Yes
`rendering-*`	11	Mostly
`bundle-*`	5	Partially
`client-*`	4	Yes
`advanced-*`	3	Yes
`async-*`	4	Partially
`server-*` (Next.js)	8	No

Checklist

PR: The PR description is expressive enough and will help future contributors
Code: Write code that humans can understand and Keep it simple
Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
Upgrade: Impact of this change on upgrade flows was considered and addressed if required
Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

NONE

Add React and Next.js performance optimization guidelines from vercel-labs/agent-skills. Installed via `npx skills add` with multi-agent support (.agents, .claude, .agent, .augment, .factory). Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

Only .agents/ and .claude/ are used in this project. Remove .agent/, .augment/, .factory/, skills/, and skills-lock.json that were auto-installed by `npx skills add --yes`. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

…ompat The .claude/skills/ directory requires real directories with copied SKILL.md files, not symlinks, for Windows compatibility. Replace the symlink with a proper directory structure matching existing skills. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

EurFelux

MIT License, safe

EurFelux

This reveals a problem - skill synchronization only syncs skill.md and does not include other content in the skill directory

DeJeune · 2026-03-12T16:58:54Z

Note

This issue/comment/review was translated by Claude.

This reveals a problem — skill synchronization only syncs skill.md and does not include other content in the skill directory.

I suggest switching to a soft link, then merge.

Original Content

This reveals a problem - skill synchronization only syncs skill.md and does not include other content in the skill directory这揭示了一个问题——技能同步仅同步 skill.md 文件，而不包括技能目录中的其他内容。

我建议换成软链接，然后再merge 一下

EurFelux · 2026-03-12T17:32:10Z

Note

This issue/comment/review was translated by Claude.

Soft links are not enabled by default in Windows systems. When git pulls them down, they revert to text files containing path names, making them completely unusable. This was also the reason why soft links were not chosen for synchronization in the first place.

Original Content

软链接在windows系统中默认不开启，git拉下来会回退到包含路径名的文本文件，导致完全不可用。这也是当初没有选用软链接同步的理由。

EurFelux · 2026-03-12T17:33:30Z

Note

This issue/comment/review was translated by Claude.

However, perhaps soft-linking files other than SKILL.md might work, since agents primarily rely on SKILL.md metadata to identify skills. I can experiment with this tomorrow.

Original Content

不过或许软链接SKILL.md以外的文件是可行的，因为agent主要依赖SKILL.md的元信息来识别skill。明天可以实验一下

…ls dir SKILL.md remains a real file for Windows cross-platform compatibility, while other skill assets (AGENTS.md, README.md, rules/, agents/) are now relative symlinks pointing back to .agents/skills/. This avoids duplicating content while keeping all skill files accessible to Claude. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: icarus <[email protected]>

EurFelux · 2026-03-13T04:33:03Z

Note

This issue/comment/review was translated by Claude.

I've modified sync and check. Now it will automatically sync files other than SKILL.md as symbolic links to .claude, and ensure that files other than SKILL.md are symbolic links.

Need to test whether the behavior works correctly on Windows systems.

Original Content

已修改sync和check，现在会自动将除SKILL.md以外的其他文件以符号连接的形式同步到.claude中，并且确保除了SKILL.md以外的文件均为符号连接。

需要测试在Windows系统上的行为是否正常。

cherry-ai-bot

Thanks for packaging the new skill and wiring it into the sync/check flow. I found one blocking issue before merge: the implementation now creates symlinks for non-SKILL entries under .claude/skills/<skill>/, but the PR description explicitly says this area should be a real directory layout for Windows compatibility. That mismatch is not just a doc issue — it means the published structure still depends on symlink support for README / AGENTS / rules, which is exactly the portability constraint this PR says it is avoiding.

cherry-ai-bot · 2026-03-13T04:42:15Z

Follow-up: I checked the PR discussion and want to correct my earlier framing. The current implementation is not simply ignoring the sync gap — it intentionally moved to "copy SKILL.md, symlink the other entries", and the open question is whether that mixed approach behaves correctly on Windows. So the real blocking concern here is missing compatibility validation, not just a mismatch against the original PR description. If this has already been tested on Windows (clone / checkout / skills:check / actual agent consumption), please add that result to the PR and this concern would likely be resolved.

GeorgeDong32

Review Summary

Tested this PR on Windows 11. Found a critical compatibility issue with the symlink approach:

Issue

The mixed approach (copy SKILL.md + symlink other files) doesn't work on Windows with default Git configuration. Symbolic links are checked out as regular text files, causing skills:check to fail.

Verified Behavior

$ pnpm skills:check
skills:check failed
- .claude/skills/gh-create-pr/agents must be a symlink, not a regular file/directory
- .claude/skills/gh-pr-review/agents must be a symlink...

Files Affected

All non-SKILL.md entries in .claude/skills/<skill>/ directories.

Recommendation

Consider using recursive file copy (fs.cpSync) instead of symlinks for full Windows compatibility, or implement a fallback mechanism that copies files when symlink creation fails.

The skill content itself is valuable - 62 React/Next.js performance rules from Vercel. Once the Windows compatibility issue is resolved, this should be good to merge.

Reviewed by kimi-k2.5

GeorgeDong32 · 2026-03-13T06:10:40Z

+
+    fs.symlinkSync(relativeTarget, claudeEntry)
+    changed.push(`.claude/skills/${skillName}/${entry}`)
+  }


Windows Compatibility Issue

The fs.symlinkSync() call fails on Windows in default configurations. Tested on Windows 11:

Git checks out symlinks as regular text files containing the path

pnpm skills:check fails with: "must be a symlink, not a regular file/directory"

This blocks Windows developers from using the skill system

Suggestion: Replace symlinks with recursive file copying for cross-platform compatibility:

// Instead of fs.symlinkSync() fs.cpSync(src, dest, { recursive: true, force: true })

Reviewed by kimi-k2.5

EurFelux · 2026-03-15T12:16:39Z

Note

This comment was translated by Claude.

@GeorgeDong32 Can these skills be used normally in the CLI? If so, we can relax the CI checks: only check symlinks on Linux and remove skills-check-windows. This would both prevent non-symlink commits to the repository and ensure out-of-the-box functionality for Windows developers.

Original Content

@GeorgeDong32 在 CLI 能正常使用这些 skills 吗？如果这样也能用，那我们可以放宽 CI 检查：只在 linux 检查 symlink，去除skills-check-windows. 这样既能防止非symlink 提交到仓库，也能保证 windows 开发者开箱即用。

GeorgeDong32 · 2026-03-15T14:54:51Z

Note

This comment was translated by Claude.

On Windows, slash commands work with just Skill.md. The current version 2.1.76 can load skills normally; although errors occur, the model follows the symbolic link plaintext to locate files @EurFelux

Original Content

Windows上有Skill.md就能用斜杠命令，目前2.1.76版本能正常加载Skill，虽然会报错，但模型会顺着符号链接的纯文本去找文件 @EurFelux

EurFelux · 2026-03-15T15:35:17Z

I am considering a full migration to symlinks, requiring Windows developers to enable symlink support as documented. The reasons are as follows:

The existing AGENTS.md is already a symlink, and traditionally, compatibility with the Windows development environment has not been a concern;
Using symlinks adheres to the Single Source of Truth (SSoT) principle, effectively reducing maintenance complexity;
The developer community should possess sufficient technical capability to configure their environments; there is no need to pursue an out-of-the-box user experience tailored for end users.

…ude skills dir" This reverts commit f631278.

cherry-ai-bot

Re-reviewed the latest revision. The previous blocking implementation issue is resolved: the mixed "copy SKILL.md + symlink everything else" approach has been reverted, and the sync/check scripts now consistently expect .claude/skills/ to be a directory symlink to .agents/skills/. I’m leaving this follow-up comment because the PR description and reviewer notes still describe the old copied-SKILL.md / Windows-compat layout, which no longer matches the actual implementation. Please update the PR description so future reviewers are evaluating the final design rather than the earlier intermediate approach.

cherry-ai-bot · 2026-03-16T03:31:18Z

 create-skill
 gh-create-issue
 gh-pr-review
+vercel-react-best-practices


Note: the current implementation no longer matches the PR description's "copied SKILL.md / real directory for Windows compatibility" explanation. After the revert + resync commits, both skills:sync and skills:check now require .claude/skills/<name> itself to be a directory symlink into .agents/skills/<name>. Please update the PR description so future reviewers are evaluating the actual final design, not the earlier intermediate approach.

bot is down

DeJeune and others added 3 commits March 12, 2026 23:47

EurFelux approved these changes Mar 12, 2026

View reviewed changes

EurFelux requested changes Mar 12, 2026

View reviewed changes

EurFelux requested a review from GeorgeDong32 March 13, 2026 04:31

cherry-ai-bot bot previously requested changes Mar 13, 2026

View reviewed changes

Comment thread scripts/skills-sync.ts

GeorgeDong32 reviewed Mar 13, 2026

View reviewed changes

EurFelux added 2 commits March 16, 2026 10:26

Revert "feat(skills): symlink non-SKILL.md files from .agents to .cla…

6443108

…ude skills dir" This reverts commit f631278.

Merge remote-tracking branch 'origin/main' into DeJeune/add-react-skills

0d1ab3d

EurFelux force-pushed the DeJeune/add-react-skills branch from e2e11e2 to ab5b61a Compare March 16, 2026 02:27

fix: sync skills

87b4d44

EurFelux force-pushed the DeJeune/add-react-skills branch from ab5b61a to 87b4d44 Compare March 16, 2026 02:28

EurFelux requested review from EurFelux and GeorgeDong32 March 16, 2026 02:30

EurFelux approved these changes Mar 16, 2026

View reviewed changes

GeorgeDong32 approved these changes Mar 16, 2026

View reviewed changes

cherry-ai-bot bot reviewed Mar 16, 2026

View reviewed changes

DeJeune merged commit 6eb461d into main Mar 16, 2026
17 checks passed

DeJeune deleted the DeJeune/add-react-skills branch March 16, 2026 03:57

Conversation

DeJeune commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Why we need it and why it was done in this way

Breaking changes

Special notes for your reviewer

Checklist

Release note

Uh oh!

EurFelux left a comment

Choose a reason for hiding this comment

Uh oh!

EurFelux left a comment • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DeJeune commented Mar 12, 2026 • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EurFelux commented Mar 12, 2026 • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EurFelux commented Mar 12, 2026 • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EurFelux commented Mar 13, 2026 • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cherry-ai-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cherry-ai-bot bot commented Mar 13, 2026

Uh oh!

GeorgeDong32 left a comment

Choose a reason for hiding this comment

Review Summary

Issue

Verified Behavior

Files Affected

Recommendation

Uh oh!

GeorgeDong32 Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

EurFelux commented Mar 15, 2026 • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GeorgeDong32 commented Mar 15, 2026 • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EurFelux commented Mar 15, 2026

Uh oh!

cherry-ai-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

cherry-ai-bot bot Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DeJeune commented Mar 12, 2026 •

edited

Loading

EurFelux left a comment •

edited by kangfenmao

Loading

DeJeune commented Mar 12, 2026 •

edited by kangfenmao

Loading

EurFelux commented Mar 12, 2026 •

edited by kangfenmao

Loading

EurFelux commented Mar 12, 2026 •

edited by kangfenmao

Loading

EurFelux commented Mar 13, 2026 •

edited by kangfenmao

Loading

EurFelux commented Mar 15, 2026 •

edited by kangfenmao

Loading

GeorgeDong32 commented Mar 15, 2026 •

edited by kangfenmao

Loading