a5c-ai/tech-writing-lint

Technical Writing Lint Skill

Automated technical writing style and quality enforcement.

Capabilities

• Vale linting with custom style rules
• Write-good suggestions for clarity
• Alex.js for inclusive language checking
• Proselint for style violations
• Readability scoring (Flesch-Kincaid, Gunning Fog)
• Terminology consistency checking
• Microsoft/Google style guide compliance
• Custom vocabulary/jargon management

Usage

Invoke this skill when you need to:

• Enforce writing style standards
• Check documentation quality
• Validate terminology consistency
• Analyze content readability
• Ensure inclusive language

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | inputPath | string | Yes | Path to documentation file or directory | | action | string | Yes | lint, readability, terminology, inclusive | | styleGuide | string | No | Style guide to apply (google, microsoft, custom) | | configPath | string | No | Path to Vale or custom config | | glossaryPath | string | No | Path to terminology glossary | | minReadability | number | No | Minimum readability score (0-100) |

Input Example

{
  "inputPath": "./docs",
  "action": "lint",
  "styleGuide": "google",
  "configPath": ".vale.ini",
  "minReadability": 60
}

Output Structure

Lint Output

{
  "files": 25,
  "errors": 8,
  "warnings": 34,
  "suggestions": 56,
  "issues": [
    {
      "file": "docs/api/authentication.md",
      "line": 42,
      "column": 15,
      "rule": "Google.Passive",
      "message": "In general, use active voice instead of passive voice.",
      "severity": "warning",
      "context": "The token is validated by the server."
    }
  ],
  "readabilityScores": {
    "fleschKincaid": 62.5,
    "gunningFog": 10.2,
    "avgSentenceLength": 18.3,
    "avgWordLength": 5.1
  }
}

Terminology Report

{
  "inconsistencies": [
    {
      "term": "backend",
      "variants": ["back-end", "back end", "Backend"],
      "preferred": "backend",
      "occurrences": [
        { "file": "docs/arch.md", "line": 15, "found": "back-end" },
        { "file": "docs/guide.md", "line": 42, "found": "Backend" }
      ]
    }
  ],
  "undefined": [
    {
      "term": "microservice",
      "occurrences": 12,
      "suggestion": "Add to glossary with definition"
    }
  ]
}

Vale Configuration

.vale.ini

StylesPath = .vale/styles

MinAlertLevel = suggestion

Packages = Google, Microsoft, write-good, alex

[*.md]
BasedOnStyles = Vale, Google, write-good

# Custom rules
Google.Passive = warning
Google.We = suggestion
Google.Will = warning
Google.Wordiness = warning

write-good.Passive = warning
write-good.Weasel = warning
write-good.TooWordy = suggestion

# Disable specific rules
Vale.Spelling = NO

[*.mdx]
BasedOnStyles = Vale, Google

[CHANGELOG.md]
BasedOnStyles = Vale

Custom Vale Rule

# .vale/styles/Custom/Terminology.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  back-end: backend
  front-end: frontend
  e-mail: email
  log-in: login
  set-up: setup
  on-premise: on-premises
  blacklist: blocklist
  whitelist: allowlist
  master: main
  slave: replica

Style Guide Rules

# .vale/styles/Custom/ActiveVoice.yml
extends: existence
message: "Avoid passive voice: '%s'"
level: warning
tokens:
  - 'is being'
  - 'was being'
  - 'has been'
  - 'have been'
  - 'had been'
  - 'will be'
  - 'is done'
  - 'was done'
  - 'are done'
  - 'were done'

Alex.js Integration

alex Configuration

{
  "allow": [
    "execute"
  ],
  "profanitySureness": 2,
  "noBinary": true
}

Inclusive Language Checks

<!-- Before -->
The user himself must configure the whitelist.
Click the master switch to enable.

<!-- After -->
The user must configure the allowlist.
Click the primary switch to enable.

Readability Analysis

Metrics Explained

| Metric | Range | Interpretation | |--------|-------|----------------| | Flesch-Kincaid | 0-100 | Higher = easier (60-70 ideal for docs) | | Gunning Fog | 0-20 | Lower = easier (8-12 ideal) | | SMOG Index | 0-20 | Years of education needed | | Coleman-Liau | 0-20 | Grade level |

Readability Report

{
  "file": "docs/quickstart.md",
  "metrics": {
    "fleschKincaid": 65.2,
    "gunningFog": 9.8,
    "smog": 10.1,
    "colemanLiau": 11.2,
    "automatedReadability": 10.5
  },
  "statistics": {
    "sentences": 45,
    "words": 823,
    "syllables": 1247,
    "complexWords": 89,
    "avgSentenceLength": 18.3,
    "avgWordLength": 4.8
  },
  "suggestions": [
    "Break up long sentences (3 sentences over 30 words)",
    "Simplify complex words: 'implementation' -> 'setup'",
    "Reduce jargon density in paragraphs 3-5"
  ]
}

Terminology Glossary

glossary.yml

terms:
  - term: API
    definition: Application Programming Interface
    usage: Always use uppercase API, not Api or api

  - term: backend
    definition: Server-side application code
    usage: One word, lowercase (not back-end or back end)

  - term: SDK
    definition: Software Development Kit
    usage: Always use uppercase SDK
    expansion_first_use: true

  - term: OAuth
    definition: Open Authorization standard
    usage: Capital O, lowercase auth

prohibited:
  - term: simple
    reason: Subjective; what's simple for one may not be for another

  - term: easy
    reason: Subjective; use specific guidance instead

  - term: just
    reason: Minimizing; implies task is trivial

  - term: obviously
    reason: May make readers feel inadequate

Workflow

1. Load configuration - Parse Vale and custom configs
2. Scan files - Find all documentation files
3. Run linters - Apply Vale, alex, write-good
4. Analyze readability - Calculate metrics
5. Check terminology - Validate against glossary
6. Generate report - Output findings and suggestions

Dependencies

{
  "devDependencies": {
    "vale": "^3.0.0",
    "alex": "^11.0.0",
    "write-good": "^1.0.0",
    "textstat": "^0.7.0",
    "proselint": "^0.13.0"
  }
}

CLI Commands

# Install Vale packages
vale sync

# Lint documentation
vale docs/

# Check inclusive language
npx alex docs/

# Write-good analysis
npx write-good docs/**/*.md

# Generate readability report
node scripts/readability.js docs/

Style Guide Comparison

| Rule | Google | Microsoft | Vale Default | |------|--------|-----------|--------------| | Passive Voice | Warning | Warning | Suggestion | | Future Tense | Warning | Off | Off | | First Person | Suggestion | Off | Off | | Contractions | Allowed | Discouraged | Off | | Oxford Comma | Required | Required | Off |

Best Practices Applied

• Use active voice
• Keep sentences under 25 words
• One idea per paragraph
• Define acronyms on first use
• Use consistent terminology
• Avoid jargon where possible
• Write for a global audience

References

• Vale: https://vale.sh/
• Alex: https://alexjs.com/
• Google Developer Docs Style Guide: https://developers.google.com/style
• Microsoft Style Guide: https://docs.microsoft.com/en-us/style-guide/
• write-good: https://github.com/btford/write-good

Target Processes

• style-guide-enforcement.js
• docs-testing.js
• docs-audit.js
• terminology-management.js