feat: add rspress-custom-theme skill

[SoonIter]

Summary

• Add rspress-custom-theme skill for customizing Rspress v2 themes
• Covers 4 levels of customization: CSS variables, BEM class overrides, Layout slots (wrap), and component ejection
• Includes decision flow to guide users toward the lightest approach that meets their needs

Benchmark Results

Metric	With Skill	Without Skill	Delta
Pass Rate	100%	58%	+42%
Avg Time	45.1s	47.5s	-2.4s
Avg Tokens	14,313	10,884	+3,429

Per-Eval Breakdown

Eval	With Skill	Without Skill	Key Difference
CSS variable brand color	100% (4/4)	75% (3/4)	Baseline uses v1 import paths (rspress/theme)
Layout slots logo+footer	100% (4/4)	75% (3/4)	Baseline uses v1 import paths (rspress/theme)
Eject home hero	100% (4/4)	25% (1/4)	Baseline doesn't know rspress eject command, uses CSS hacks

Key Findings

• All without-skill runs use v1 import paths (rspress/theme) instead of v2 (@rspress/core/theme-original) — a consistent and breaking error
• Biggest skill value is in eject scenario: without the skill, Claude doesn't know the rspress eject CLI command exists and resorts to manual HomeLayout wrapping with CSS display:none hacks
• Time/token usage is comparable — skill doesn't add significant overhead

Test plan

• Eval 1: CSS variable customization (change brand color)
• Eval 2: Layout slots (add logo + footer without replacing layout)
• Eval 3: Component ejection (fully replace hero section)

[Copilot]

Pull request overview

This PR adds a new rspress-custom-theme skill that guides users through four levels of Rspress v2 theme customization: CSS variable overrides, BEM class overrides, Layout slots (wrap), and component ejection. The skill addresses a real gap—without it, the model consistently uses outdated v1 import paths and misses the rspress eject CLI command.

Changes:

• New SKILL.md defining the skill with decision-flow guidance across four customization levels
• New evals/evals.json with three evaluation scenarios covering each key customization path
• Benchmark workspace (iteration-1/) with eval outputs, grading, timing, and summary files

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
skills/rspress-custom-theme/SKILL.md	Core skill content with four-level customization guide
skills/rspress-custom-theme/evals/evals.json	Three eval scenarios testing CSS, slots, and eject flows
rspress-custom-theme-workspace/iteration-1/benchmark.json	Benchmark run results and aggregated statistics
rspress-custom-theme-workspace/iteration-1/benchmark.md	Benchmark summary in Markdown (template values unfilled)
rspress-custom-theme-workspace/iteration-1/eval-*/	Per-eval metadata, grading, timing, and output files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new rspress-custom-theme skill to streamline and improve the process of customizing Rspress v2 documentation sites. It provides a tiered approach to theme modifications, guiding users from simple style adjustments to complex component replacements. The addition significantly enhances the ability to implement custom designs and layouts correctly, as evidenced by improved benchmark performance, without introducing notable performance overhead.

Highlights

• New Rspress Custom Theme Skill: Introduced a new skill, rspress-custom-theme, designed to assist users in customizing Rspress v2 themes effectively.
• Comprehensive Customization Levels: The skill covers four distinct levels of theme customization: CSS variables, BEM class overrides, Layout slots (wrap pattern), and full component ejection, providing a structured decision flow.
• Improved Customization Success Rate: Benchmark results demonstrate a significant increase in pass rate, achieving 100% with the skill compared to 58% without, particularly in complex scenarios like component ejection and correct import path usage.
• Correct Rspress v2 Import Paths: The skill addresses a common issue where users incorrectly use Rspress v1 import paths (rspress/theme) instead of the correct v2 paths (@rspress/core/theme-original).
• Guidance on Component Ejection: The skill provides clear instructions and warnings for component ejection, including the rspress eject CLI command, which was previously unknown in 'without skill' scenarios.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• rspress-custom-theme-workspace/iteration-1/benchmark.json
  • Added detailed benchmark results for the rspress-custom-theme skill, comparing 'with skill' and 'without skill' configurations across various evaluation scenarios.
• rspress-custom-theme-workspace/iteration-1/benchmark.md
  • Added a Markdown template for summarizing skill benchmark results.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/eval_metadata.json
  • Added evaluation metadata for the CSS variable customization scenario, including the prompt and assertions.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/with_skill/grading.json
  • Added grading results for the CSS variable customization evaluation when the skill was utilized.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/with_skill/outputs/response.md
  • Added the detailed response generated 'with skill' for the CSS variable customization prompt.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/with_skill/timing.json
  • Added timing and token usage data for the CSS variable customization evaluation 'with skill'.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/without_skill/grading.json
  • Added grading results for the CSS variable customization evaluation when the skill was not utilized.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/without_skill/outputs/response.md
  • Added the detailed response generated 'without skill' for the CSS variable customization prompt.
• rspress-custom-theme-workspace/iteration-1/eval-1-css-variables/without_skill/timing.json
  • Added timing and token usage data for the CSS variable customization evaluation 'without skill'.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/eval_metadata.json
  • Added evaluation metadata for the layout slots customization scenario, including the prompt and assertions.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/with_skill/grading.json
  • Added grading results for the layout slots customization evaluation when the skill was utilized.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/with_skill/outputs/response.md
  • Added the detailed response generated 'with skill' for the layout slots customization prompt.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/with_skill/timing.json
  • Added timing and token usage data for the layout slots customization evaluation 'with skill'.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/without_skill/grading.json
  • Added grading results for the layout slots customization evaluation when the skill was not utilized.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/without_skill/outputs/response.md
  • Added the detailed response generated 'without skill' for the layout slots customization prompt.
• rspress-custom-theme-workspace/iteration-1/eval-2-layout-slots/without_skill/timing.json
  • Added timing and token usage data for the layout slots customization evaluation 'without skill'.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/eval_metadata.json
  • Added evaluation metadata for the component ejection scenario, including the prompt and assertions.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/with_skill/grading.json
  • Added grading results for the component ejection evaluation when the skill was utilized.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/with_skill/outputs/response.md
  • Added the detailed response generated 'with skill' for the component ejection prompt.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/with_skill/timing.json
  • Added timing and token usage data for the component ejection evaluation 'with skill'.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/without_skill/grading.json
  • Added grading results for the component ejection evaluation when the skill was not utilized.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/without_skill/outputs/response.md
  • Added the detailed response generated 'without skill' for the component ejection prompt.
• rspress-custom-theme-workspace/iteration-1/eval-3-eject-hero/without_skill/timing.json
  • Added timing and token usage data for the component ejection evaluation 'without skill'.
• skills/rspress-custom-theme/SKILL.md
  • Added the main documentation for the rspress-custom-theme skill, detailing its four levels of customization and usage guidelines.
• skills/rspress-custom-theme/evals/evals.json
  • Added evaluation definitions for the rspress-custom-theme skill, outlining prompts and expected outputs for various customization scenarios.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds the rspress-custom-theme skill. However, it misses a crucial step required by the repository's style guide. As a high-severity issue, the root README.md file must be updated to include a new section for this skill, including its name, install command (npx skills add rstackjs/agent-skills --skill rspress-custom-theme), and a description. Please add this update. Additionally, I've found several medium-severity issues in the new benchmark and evaluation files, including a hardcoded absolute path, future dates, and placeholder content. Please see the detailed comments.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[SoonIter]

looks nice

[Timeless0911]

Add this skill to related documents in Rspress website later.