home / skills / onmax / nuxt-skills / document-writer

document-writer skill

safe

This skill helps you write clear Nuxt documentation and blog posts with proper grammar, structure, and MDC/nuxt-ui guidance.

npx playbooks add skill onmax/nuxt-skills --skill document-writer

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

3.5 KB

---
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

Overview

This skill helps authors write blog posts and documentation for the Nuxt ecosystem. It enforces an active, present-tense writing style, clear structure patterns, and recommended MDC component usage. It integrates guidance for nuxt-content prose and nuxt-ui component props.

How this skill works

The skill inspects draft text and recommends edits for voice, tense, grammar, and paragraph length. It suggests page structure patterns, frontmatter fields, and when to apply MDC callouts and components. It flags H1 usage rules, code block labels, and explains component choices with nuxt-ui prop examples when relevant.

When to use it

Writing or editing Nuxt blog posts
Creating or updating documentation pages
Converting notes into structured MDC markdown
Ensuring consistent style across a docs site
Preparing examples that use nuxt-content or nuxt-ui patterns

Best practices

Prefer active voice and present tense across at least 85% of sentences
Write complete sentences and prioritize clarity over extreme brevity
Limit paragraphs to 2–4 sentences with an explanation before code examples
Label code blocks with file paths and use ::code-group for multi-source code
Use MDC callouts for intent: ::note, ::tip, ::warning, ::important, and u-button for CTAs

Example use cases

Create a Nuxt composable guide that explains behavior, shows code, and uses ::note for caveats
Draft a migration doc that lists steps, links components, and uses :u-button for upgrade CTA
Write a blog post with frontmatter, structured headings, and code blocks labeled with file paths
Build a component reference page that shows props via nuxt-ui patterns and examples using ::code-group

FAQ

Does the skill force brevity over grammar?

No. It preserves proper grammar and complete sentences; brevity never compromises clarity.

When should I avoid backticks in headings?

Avoid backticks in H1 headings because they do not render properly; H2–H4 may include inline code.