docs: improve document content with ai

.agents/skills/document-writer/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: document-writer
+description: Use when writing blog posts or documentation markdown files - provides writing style guide (active voice, present tense), content structure patterns, and MDC component usage. Overrides brevity rules for proper grammar. Use nuxt-content for MDC syntax, nuxt-ui for component props.
+license: MIT
+---
+
+# Documentation Writer for Nuxt Ecosystem
+
+Writing guidance for blog posts and documentation following patterns from official Nuxt websites.
+
+## When to Use
+
+- Writing blog posts for Nuxt ecosystem projects
+- Creating or editing documentation pages
+- Ensuring consistent writing style across content
+
+## Writing Standard
+
+**Override**: When writing documentation, maintain proper grammar and complete sentences. The "sacrifice grammar for brevity" rule does NOT apply here.
+
+Documentation must be:
+
+- Grammatically correct
+- Clear and unambiguous
+- Properly punctuated
+- Complete sentences (not fragments)
+
+Brevity is still valued, but never at the cost of clarity or correctness.
+
+## Related Skills
+
+For component and syntax details, use these skills:
+
+| Skill            | Use For                                         |
+| ---------------- | ----------------------------------------------- |
+| **nuxt-content** | MDC syntax, prose components, code highlighting |
+| **nuxt-ui**      | Component props, theming, UI patterns           |
+
+## Available References
+
+| Reference                                                            | Purpose                                         |
+| -------------------------------------------------------------------- | ----------------------------------------------- |
+| **[references/writing-style.md](references/writing-style.md)**       | Voice, tone, sentence structure                 |
+| **[references/content-patterns.md](references/content-patterns.md)** | Blog frontmatter, structure, component patterns |
+
+**Load based on context:**
+
+- Writing prose → [references/writing-style.md](references/writing-style.md)
+- Blog structure and patterns → [references/content-patterns.md](references/content-patterns.md)
+
+## Quick Reference
+
+### Writing Patterns
+
+| Pattern       | Example                                            |
+| ------------- | -------------------------------------------------- |
+| Subject-first | "The `useFetch` composable handles data fetching." |
+| Imperative    | "Add the following to `nuxt.config.ts`."           |
+| Contextual    | "When using authentication, configure..."          |
+
+### Modal Verbs
+
+| Verb     | Meaning     |
+| -------- | ----------- |
+| `can`    | Optional    |
+| `should` | Recommended |
+| `must`   | Required    |
+
+### Component Patterns (WHEN to use)
+
+| Need              | Component                         |
+| ----------------- | --------------------------------- |
+| Info aside        | `::note`                          |
+| Suggestion        | `::tip`                           |
+| Caution           | `::warning`                       |
+| Required          | `::important`                     |
+| CTA               | `:u-button{to="..." label="..."}` |
+| Multi-source code | `::code-group`                    |
+
+> For component props: see **nuxt-ui** skill
+
+## Headings
+
+- **H1 (`#`)**: No backticks — they don't render properly
+- **H2-H4**: Backticks work fine
+
+## Checklist
+
+- [ ] Active voice (85%+)
+- [ ] Present tense
+- [ ] 2-4 sentences per paragraph
+- [ ] Explanation before code
+- [ ] File path labels on code blocks
+- [ ] Appropriate callout types
+- [ ] No backticks in H1 headings

.agents/skills/document-writer/references/content-patterns.md

@@ -0,0 +1,167 @@
+# Content Patterns
+
+Blog post structure, frontmatter, and component patterns for Nuxt ecosystem documentation.
+
+## Blog Post Frontmatter
+
+```yaml
+---
+title: Post Title
+description: Brief description for SEO and previews (under 160 chars)
+navigation: false
+image: /assets/blog/slug.png
+authors:
+  - name: Author Name
+    avatar:
+      src: https://github.com/username.png
+    to: https://x.com/username
+date: 2025-11-05T10:00:00.000Z
+category: Release
+---
+```
+
+**Categories**: `Release` (version announcements), `Article` (tutorials, guides)
+
+**Author links**: GitHub, X/Twitter, Bluesky (`https://bsky.app/profile/...`)
+
+## Blog Post Structure
+
+1. **Opening** (1-2 paragraphs) - Announce what's new, why it matters
+2. **Key callout** - `::note` or `::callout` with requirements/prerequisites
+3. **Feature sections** - `## Emoji Feature Name` headers
+4. **Code examples** - With file path labels
+5. **Breaking changes** - If release post
+6. **Thank you** - Credit contributors
+7. **Resources** - Links to docs, repo
+8. **Release link** - `::read-more` to full changelog
+
+## Recommended Modules
+
+For enhanced documentation features:
+
+| Module                                                                    | Purpose                                                                 |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [`nuxt-content-twoslash`](https://github.com/antfu/nuxt-content-twoslash) | TwoSlash for Nuxt Content - inline TypeScript type hints in code blocks |
+
+### Installation
+
+```bash
+pnpm add -D nuxt-content-twoslash
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+	modules: ['nuxt-content-twoslash', '@nuxt/content'] // twoslash before content
+})
+```
+
+## Component Patterns
+
+Use the right component for the right purpose:
+
+| Need             | Component                         | When                       |
+| ---------------- | --------------------------------- | -------------------------- |
+| Background info  | `::note`                          | Supplementary context      |
+| Best practice    | `::tip`                           | Recommendations            |
+| Potential issue  | `::warning`                       | Things that could go wrong |
+| Must-know        | `::important`                     | Required actions           |
+| Danger           | `::caution`                       | Destructive operations     |
+| CTA button       | `:u-button{to="..." label="..."}` | Downloads, external links  |
+| Package managers | `::code-group{sync="pm"}`         | pnpm/npm/yarn variants     |
+| Expandable       | `::collapsible{title="..."}`      | Advanced details           |
+| Images           | `::carousel{items: [...]}`        | Multiple screenshots       |
+| Sequential steps | `::steps`                         | Multi-step instructions    |
+
+> For component props/details: see **nuxt-ui** skill
+
+## Steps Component
+
+The `::steps` component auto-renders step numbers. **Do NOT include numbers in step titles** — they'll be duplicated.
+
+```md
+<!-- ✅ Correct -->
+::steps
+### Install the module
+### Configure nuxt.config.ts
+### Restart dev server
+::
+
+<!-- ❌ Wrong (numbers will duplicate) -->
+::steps
+### 1. Install the module
+### 2) Configure nuxt.config.ts
+### Step 3: Restart dev server
+::
+```
+
+## Code Block Labels
+
+Always include file path:
+
+````md
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxt/content']
+})
+```
+
+```vue [app/pages/index.vue]
+<template>
+  <div>Hello</div>
+</template>
+```
+
+```bash
+pnpm add @nuxt/content
+```
+````
+
+## YAML Props Format
+
+For components with multiple props, use YAML frontmatter:
+
+```md
+::read-more
+---
+icon: i-simple-icons-github
+target: _blank
+to: https://github.com/nuxt/nuxt/releases/tag/v4.0.0
+---
+Read the full release notes.
+::
+```
+
+```md
+::carousel
+---
+items:
+  - /assets/blog/image-1.png
+  - /assets/blog/image-2.png
+---
+::
+```
+
+## Cross-References
+
+Link to related content:
+
+```md
+<!-- Inline link -->
+See the [configuration guide](/docs/getting-started/configuration).
+
+<!-- Read-more block -->
+::read-more{to="/docs/api/composables/use-fetch"}
+::
+
+<!-- With custom text and icon -->
+::read-more
+---
+icon: i-simple-icons-github
+to: https://github.com/nuxt/nuxt
+target: _blank
+---
+View the source code.
+::
+```
+
+> For MDC syntax details: see **nuxt-content** skill (rendering.md)