From d5df0b08925d66cd2825855ba2f51739ed119da1 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 7 Oct 2026 16:04:40 +0800 Subject: [PATCH 1/4] docs: add page description writing guidance --- .agents/skills/rstack-docs-writer/SKILL.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.agents/skills/rstack-docs-writer/SKILL.md b/.agents/skills/rstack-docs-writer/SKILL.md index 3c01f95..eaf279b 100644 --- a/.agents/skills/rstack-docs-writer/SKILL.md +++ b/.agents/skills/rstack-docs-writer/SKILL.md @@ -16,6 +16,28 @@ Follow the project's existing documentation conventions. - Keep documentation in sync across locales when changing content. Use English as the default language unless the project specifies another. - Use sentence-case headings. +## Page descriptions + +Rspress reuses a page's frontmatter `description` in search metadata and `llms.txt`. Write it to help readers and agents choose the right page for a task. + +- Read the page's headings, relevant content, and limitations before summarizing it. Describe the page's scope, not just its first paragraph, one example, or an isolated warning. +- Name the concrete API, technology, or task and the topics that distinguish this page. Include version requirements, experimental status, or environment restrictions when they affect applicability. +- Distinguish related pages, such as build cache configuration versus the plugin cache API, or stats configuration versus the Stats object API. +- Use a concise, complete plain-text sentence. Avoid truncated text, marketing language, and generic templates such as "setup, configuration, integration details, and best practices." Do not add unsupported topics or filler to meet a character count. +- Match the page's language. Keep translated descriptions equivalent in scope while checking each locale's actual content. +- During description audits, revise existing misleading, generic, or truncated descriptions as well as filling gaps. Preserve descriptions that already identify the page clearly. +- If the underlying content is outdated or contradictory, flag or address that issue within the task's scope; do not invent current behavior in the description. + +Examples: + +| Page | Description | +| ---------------- | ------------------------------------------------------------------------------------------------- | +| JSON guide | Import JSON files using default imports, named imports where supported, and import attributes. | +| Stats hooks | Customize stats generation and text output with StatsFactory and StatsPrinter hooks. | +| Plugin cache API | Cache data across compilations in JavaScript plugins with getCache, cache identifiers, and etags. | + +Edit descriptions in page frontmatter rather than generated indexes. For `llms.txt` updates, inspect the generated index to confirm the revised descriptions appear correctly. Keep index restructuring separate unless it is part of the requested task. + ## Heading anchors - Prefer Rspress's default anchors for headings in the default locale; preserve intentional existing custom IDs. From ac93cc3017bdbe7ac22d4ee77ff010ea0c4c977a Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 8 Oct 2026 10:23:50 +0800 Subject: [PATCH 2/4] docs: simplify page description guidance --- .agents/skills/rstack-docs-writer/SKILL.md | 27 +++++++--------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/.agents/skills/rstack-docs-writer/SKILL.md b/.agents/skills/rstack-docs-writer/SKILL.md index eaf279b..9c10f4d 100644 --- a/.agents/skills/rstack-docs-writer/SKILL.md +++ b/.agents/skills/rstack-docs-writer/SKILL.md @@ -18,25 +18,14 @@ Follow the project's existing documentation conventions. ## Page descriptions -Rspress reuses a page's frontmatter `description` in search metadata and `llms.txt`. Write it to help readers and agents choose the right page for a task. - -- Read the page's headings, relevant content, and limitations before summarizing it. Describe the page's scope, not just its first paragraph, one example, or an isolated warning. -- Name the concrete API, technology, or task and the topics that distinguish this page. Include version requirements, experimental status, or environment restrictions when they affect applicability. -- Distinguish related pages, such as build cache configuration versus the plugin cache API, or stats configuration versus the Stats object API. -- Use a concise, complete plain-text sentence. Avoid truncated text, marketing language, and generic templates such as "setup, configuration, integration details, and best practices." Do not add unsupported topics or filler to meet a character count. -- Match the page's language. Keep translated descriptions equivalent in scope while checking each locale's actual content. -- During description audits, revise existing misleading, generic, or truncated descriptions as well as filling gaps. Preserve descriptions that already identify the page clearly. -- If the underlying content is outdated or contradictory, flag or address that issue within the task's scope; do not invent current behavior in the description. - -Examples: - -| Page | Description | -| ---------------- | ------------------------------------------------------------------------------------------------- | -| JSON guide | Import JSON files using default imports, named imports where supported, and import attributes. | -| Stats hooks | Customize stats generation and text output with StatsFactory and StatsPrinter hooks. | -| Plugin cache API | Cache data across compilations in JavaScript plugins with getCache, cache identifiers, and etags. | - -Edit descriptions in page frontmatter rather than generated indexes. For `llms.txt` updates, inspect the generated index to confirm the revised descriptions appear correctly. Keep index restructuring separate unless it is part of the requested task. +Page frontmatter `description` is reused in search metadata and `llms.txt`. + +- Summarize the page's actual scope using concrete APIs, tasks, and distinguishing topics, rather than one paragraph or example. +- Distinguish related configuration and API pages. Include version, stability, or environment constraints when they affect applicability. +- Use one complete plain-text sentence. Avoid generic templates, unsupported claims, truncation, and padding to meet a character count. +- Match the page's language and keep descriptions equivalent across locales. +- During audits, improve misleading or vague descriptions, preserve useful ones, and flag outdated source content. +- Edit frontmatter rather than generated indexes. For `llms.txt` updates, verify the descriptions in the generated output. ## Heading anchors From 56388b3ee4cbd75a262a17dd5ab79debc8ea189f Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 8 Oct 2026 10:35:08 +0800 Subject: [PATCH 3/4] docs: remove generated index verification guidance --- .agents/skills/rstack-docs-writer/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.agents/skills/rstack-docs-writer/SKILL.md b/.agents/skills/rstack-docs-writer/SKILL.md index 9c10f4d..ad5f92a 100644 --- a/.agents/skills/rstack-docs-writer/SKILL.md +++ b/.agents/skills/rstack-docs-writer/SKILL.md @@ -25,7 +25,6 @@ Page frontmatter `description` is reused in search metadata and `llms.txt`. - Use one complete plain-text sentence. Avoid generic templates, unsupported claims, truncation, and padding to meet a character count. - Match the page's language and keep descriptions equivalent across locales. - During audits, improve misleading or vague descriptions, preserve useful ones, and flag outdated source content. -- Edit frontmatter rather than generated indexes. For `llms.txt` updates, verify the descriptions in the generated output. ## Heading anchors From b4bf9bce9374c671cc2de1e0be5c0c19d769366f Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 8 Oct 2026 10:36:14 +0800 Subject: [PATCH 4/4] docs: remove description audit guidance --- .agents/skills/rstack-docs-writer/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.agents/skills/rstack-docs-writer/SKILL.md b/.agents/skills/rstack-docs-writer/SKILL.md index ad5f92a..b339cf8 100644 --- a/.agents/skills/rstack-docs-writer/SKILL.md +++ b/.agents/skills/rstack-docs-writer/SKILL.md @@ -24,7 +24,6 @@ Page frontmatter `description` is reused in search metadata and `llms.txt`. - Distinguish related configuration and API pages. Include version, stability, or environment constraints when they affect applicability. - Use one complete plain-text sentence. Avoid generic templates, unsupported claims, truncation, and padding to meet a character count. - Match the page's language and keep descriptions equivalent across locales. -- During audits, improve misleading or vague descriptions, preserve useful ones, and flag outdated source content. ## Heading anchors