feat(rspress): add rspress best practices skill (#57)

Author: SoonIter

README.md

@@ -125,6 +125,14 @@ Migrate tsc or tsup library projects to Rslib.
 
 ## Rspress Skills
 
+### rspress-best-practices
+
+```bash
+npx skills add rstackjs/agent-skills --skill rspress-best-practices
+```
+
+Rspress best practices for config, CLI workflow, content organization, frontmatter, MDX, themes, i18n, search, static assets, deployment, and debugging. Use when writing, reviewing, or troubleshooting Rspress documentation sites.
+
 ### rspress-v2-upgrade
 
 ```bash

skills/rspress-best-practices/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: rspress-best-practices
+description: Rspress best practices for config, CLI workflow, content organization, frontmatter, MDX, themes, i18n, search, static assets, deployment, and debugging. Use when writing, reviewing, or troubleshooting Rspress documentation sites.
+---
+
+# Rspress Best Practices
+
+Apply these rules when writing or reviewing Rspress (v2) sites.
+
+## Configuration
+
+- Use `rspress.config.ts` and `defineConfig` from `@rspress/core`
+- Set `root` explicitly when docs are not under the default `docs/` directory
+- Keep site-wide settings such as `title`, `description`, `icon`, `logo`, `base`, and `lang` in config instead of repeating them in page files
+- Prefer first-class Rspress options before custom theme code or low-level bundler overrides
+- Keep custom theme code in a top-level `theme/` directory and import original theme pieces from `@rspress/core/theme-original`
+
+## CLI
+
+- Use `rspress dev` for local development
+- Use `rspress build` for production output
+- Use `rspress preview` only for local preview of the built site
+- Use `rspress eject` only when CSS variables, class overrides, or layout wrapping cannot solve the customization
+
+## Docs Structure And Navigation
+
+- Keep docs content under one clear docs root and group pages by topic or workflow, not by team ownership
+- Use `_meta.json` or `_nav.json` to control sidebar and navigation labels/order instead of encoding order in filenames
+- Put reusable MDX snippets or shared components in shared files instead of duplicating them across pages
+- Keep landing pages concise and link to deeper task-oriented guides from them
+
+## Writing And Frontmatter
+
+- Add clear `title` and `description` frontmatter, and set `sidebar`, `outline`, `navbar`, or `footer` only when page defaults are not enough
+- Use `pageType: home`, `doc`, `doc-wide`, `custom`, or `blank` intentionally based on layout needs
+- Write task-first headings and short intros; avoid marketing-heavy copy in technical docs
+- Prefer one topic per page and split overly long pages by workflow or feature area
+- Keep code examples minimal, runnable, and version-accurate
+
+## MDX And Components
+
+- Use MDX for interactive docs and embedded components, but keep the main narrative understandable as plain markdown
+- Prefer documented Rspress theme/runtime APIs over importing from internal source paths
+- For app-wide UI or providers, use `globalUIComponents` or theme overrides instead of repeating imports in each page
+
+## Theme And Styling
+
+- Prefer CSS variables for brand colors, spacing, and surface styling
+- Prefer BEM class overrides or `Layout` slots before ejecting built-in components
+- In `theme/` files, keep `export * from '@rspress/core/theme-original'` unless intentionally replacing a named export
+- Avoid full component ejection unless config, CSS, and wrapping cannot meet the requirement
+
+## I18n, Search, And AI
+
+- For multilingual sites, organize locale content under per-language directories and keep navigation mirrored where practical
+- Keep descriptions and other frontmatter text in the same language as the page content
+- Configure search intentionally: use local search for small or medium sites, and hosted search when scale or cross-version indexing requires it
+- Enable `llms` or `ssgMd` only when the site benefits from machine-readable outputs, and keep descriptions accurate because those outputs surface page summaries
+
+## Assets And Public Files
+
+- Import source-managed images and components from docs/theme source when they belong to the content
+- Use `public/` only for assets that must keep stable URL paths, such as favicons, social images, or download files
+- Reference public assets by absolute site path and make sure they still work when `base` is set
+
+## Plugins And Integration
+
+- Prefer official Rspress plugins for search, preview, and API-doc scenarios before building custom solutions
+- For component or library docs, use `@rspress/plugin-preview` and `@rspress/plugin-api-docgen` when interactive demos or API tables are needed
+- Keep plugin usage explicit in config and remove unused plugins to reduce maintenance cost
+
+## Build, Deploy, And Debugging
+
+- Validate both `rspress dev` and `rspress build`; a page that works in dev can still fail during static generation
+- Verify broken links, missing assets, and wrong `base` handling before deployment
+- Keep generated output out of source control unless the hosting workflow explicitly requires committed artifacts
+- When debugging content issues, inspect the resolved docs root, frontmatter, and theme overrides before assuming a bundler problem
+
+## Documentation
+
+- For the latest Rspress docs, read https://rspress.rs/llms.txt
+- Use the config and API docs when checking exact option names or current behavior