diff --git a/README.md b/README.md
index bba641c..28c55a8 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,14 @@ npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade
 
 Migrate Rspress projects from v1 to v2. Use when a user asks to upgrade Rspress, follow the v1-to-v2 guide, update packages/configs/themes, or validate the upgrade.
 
+### rspress-custom-theme
+
+```bash
+npx skills add rstackjs/agent-skills --skill rspress-custom-theme
+```
+
+Customize Rspress themes using CSS variables, Layout slots, component wrapping, or component ejection. Use when a user wants to change the look and feel of an Rspress site, override theme components, add custom navigation/sidebar/footer content, inject global providers, or modify the default Rspress theme in any way.
+
 ### rspress-description-generator
 
 ```bash
diff --git a/scripts/dictionary.txt b/scripts/dictionary.txt
index bd3d004..5a15439 100644
--- a/scripts/dictionary.txt
+++ b/scripts/dictionary.txt
@@ -35,6 +35,7 @@ rstack
 rstackjs
 rstest
 shiki
+SVGSVG
 svgr
 samply
 tailwindcss
diff --git a/skills/rspress-custom-theme/SKILL.md b/skills/rspress-custom-theme/SKILL.md
index 4f550b2..2ee763c 100644
--- a/skills/rspress-custom-theme/SKILL.md
+++ b/skills/rspress-custom-theme/SKILL.md
@@ -24,6 +24,7 @@ Guide for customizing Rspress (v2) themes. Rspress offers four levels of customi
 | Add content around existing components (banners, footers, logos) | 3     | Layout slots (wrap)         |
 | Override MDX rendering (custom `<h1>`, `<code>`, etc.)           | 3     | `components` slot           |
 | Wrap the app in a provider (state, analytics, auth)              | 4     | Eject `Root`                |
+| Replace built-in icons (logo, GitHub, search, etc.)              | —     | Icon re-export              |
 | Completely replace a built-in component                          | 4     | Eject that component        |
 | Add a global floating component (back-to-top, chat widget)       | —     | `globalUIComponents` config |
 | Control page layout structure (hide sidebar, blank page)         | —     | Frontmatter `pageType`      |
@@ -139,6 +140,55 @@ export { DocFooter } from './components/DocFooter';
 
 ---
 
+## Custom Icons
+
+Rspress has 27 built-in icons used across the UI. You can replace any of them by re-exporting your own icon component with the same name — no ejection needed. This uses the same `theme/index.tsx` mechanism: your named export takes precedence over the wildcard re-export.
+
+**Icon type**: Each icon is a React component or a URL string:
+
+```ts
+import type { FC, SVGProps } from 'react';
+type Icon = FC<SVGProps<SVGSVGElement>> | string;
+```
+
+**Example 1** — Replace an icon with a custom SVG component:
+
+```tsx
+// theme/index.tsx
+export * from '@rspress/core/theme-original';
+
+// Named export overrides the wildcard — replaces the GitHub icon site-wide
+export const IconGithub = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}>
+    <path d="M12 2C6.477 2 2 6.484 2 12.017c0 ..." fill="currentColor" />
+  </svg>
+);
+```
+
+**Example 2** — Use an SVGR import:
+
+```tsx
+// theme/index.tsx
+export * from '@rspress/core/theme-original';
+
+import CustomGithubIcon from './icons/github.svg?react';
+export const IconGithub = CustomGithubIcon;
+```
+
+**Using `SvgWrapper` in MDX or custom components**:
+
+```mdx
+import { SvgWrapper, IconGithub } from '@rspress/core/theme';
+
+<SvgWrapper icon={IconGithub} width={24} height={24} />
+```
+
+**Available icons**: `IconArrowDown`, `IconArrowRight`, `IconClose`, `IconCopy`, `IconDeprecated`, `IconDown`, `IconEdit`, `IconEmpty`, `IconExperimental`, `IconExternalLink`, `IconFile`, `IconGithub`, `IconGitlab`, `IconHeader`, `IconJump`, `IconLink`, `IconLoading`, `IconMenu`, `IconMoon`, `IconScrollToTop`, `IconSearch`, `IconSmallMenu`, `IconSuccess`, `IconSun`, `IconTitle`, `IconWrap`, `IconWrapped`.
+
+> **Source**: See the [icons source](https://github.com/web-infra-dev/rspress/blob/main/packages/core/src/theme/icons.ts) for default implementations.
+
+---
+
 ## Global UI Components
 
 For components that should render on every page without theme overrides:
@@ -187,5 +237,6 @@ Fine-grained: set `navbar: false`, `sidebar: false`, `outline: false`, `footer:
 - Custom theme guide: <https://rspress.rs/guide/basic/custom-theme>
 - CSS variables: <https://rspress.rs/ui/vars>
 - Layout component: <https://rspress.rs/ui/layout-components/layout>
+- Built-in icons: <https://rspress.rs/ui/icons/>
 - Built-in hooks: <https://rspress.rs/ui/hooks/>
 - CLI commands (eject): <https://rspress.rs/api/commands>