Content Author Skill

This skill ensures all written content meets quality standards for spelling, grammar, and style.

Spelling Awareness

This project uses cspell for spell checking with a custom dictionary.

Known Project Terms

These terms are in project-words.txt and won't trigger spell errors:

Technical:

XHTML, WCAG, htmlhint, pa11y, cspell, textlint, linkinator

Custom Elements:

product-card, icon-element, user-avatar, status-badge, data-table, nav-menu

HTML Terms:

doctype, tbody, thead, fieldset, hgroup, blockquote

Check project-words.txt for the full list.

Adding New Terms

When using a new product name or technical term:

Use slash command: /add-word TermName
Or edit directly: Add to project-words.txt (one word per line)

Style Guidelines

Avoid Passive Voice

<!-- Passive (avoid) -->
The form was submitted by the user.
Errors were found in the document.

<!-- Active (prefer) -->
The user submitted the form.
The validator found errors in the document.

Avoid Weasel Words

Remove vague qualifiers:

Avoid	Use Instead
various	(be specific)
many	(give number)
very	(remove or be specific)
somewhat	(remove)
fairly	(remove)
quite	(remove)

Link Text

Use descriptive link text:

<!-- Bad -->
<a href="/docs">Click here</a>
<a href="/pricing">Learn more</a>
<a href="/features">Read more</a>

<!-- Good -->
<a href="/docs">Read the documentation</a>
<a href="/pricing">View pricing plans</a>
<a href="/features">Explore all features</a>

Headings

Follow logical hierarchy:

<h1>Page Title</h1>           <!-- One per page -->
  <h2>Major Section</h2>
    <h3>Subsection</h3>
      <h4>Detail</h4>
  <h2>Another Section</h2>

Reading Level Guidelines

This project enforces reading level thresholds using Flesch-Kincaid scoring.

Grade Level Thresholds

Content Type	Max Grade Level	Audience
General	8	General public
Technical	12	Technical audience

Marking Content Style

For technical documentation, add one of these:

<!-- In <head> -->
<meta name="content-style" content="technical"/>

<!-- Or on html/body -->
<html lang="en" data-content-style="technical">
<body data-content-style="technical">

Available content styles:

technical - Technical documentation, API references (threshold: grade 12)
Default (no attribute) - General content (threshold: grade 8)

Writing for Readability

Use shorter sentences:

<!-- Hard to read (grade 12+) -->
The implementation of the aforementioned functionality requires
consideration of various architectural constraints that may
impact the overall system performance.

<!-- Easier to read (grade 8) -->
This feature needs careful planning. We must consider how it
affects system speed.

Use simpler words:

Complex Word	Simpler Alternative
utilize	use
implement	build, create
functionality	feature
subsequently	then, later
facilitate	help, enable
approximately	about
demonstrate	show
modification	change

Break up long paragraphs: Aim for 3-4 sentences per paragraph.

Use lists: Convert complex sentences into bullet points when possible.

Checking Reading Level

# Check readability
npm run lint:readability

# Check all content quality
npm run lint:content

Content Checklist

Before finalizing content:

Spelling checked (run npm run lint:spelling)
No weasel words or vague language
Links have descriptive text
Headings follow hierarchy
Alt text provided for images
Proper capitalization for product names
Reading level within threshold (run npm run lint:readability)

Running Quality Checks

# Check spelling
npm run lint:spelling

# Check grammar/style (advisory)
npm run lint:grammar

# Check reading level
npm run lint:readability

# Run all content checks
npm run lint:content

Special Content

Code Examples

Wrap code in appropriate elements:

<code>const x = 1</code>           <!-- Inline code -->
<pre><code>                        <!-- Code block -->
function example() {
  return true;
}
</code></pre>
<kbd>Ctrl+S</kbd>                  <!-- Keyboard input -->
<samp>Output text</samp>           <!-- Sample output -->

Abbreviations

Define abbreviations on first use:

<abbr title="HyperText Markup Language">HTML</abbr>
<abbr title="Web Content Accessibility Guidelines">WCAG</abbr>

Dates and Times

Use semantic time element:

<time datetime="2024-01-15">January 15, 2024</time>
<time datetime="14:30">2:30 PM</time>

Related Skills

xhtml-author - Write valid XHTML-strict HTML5 markup
fake-content - Generate realistic fake content for HTML prototypes
accessibility-checker - Ensure WCAG2AA accessibility compliance
markdown-author - Write quality markdown content

content-author