Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Technical Writing Lint Skill · a5c-ai | DecimalAI

a5c-ai/tech-writing-lint

SkillScore68Maintained

Automated technical writing style and quality enforcement. Lint documentation with Vale, check for inclusive language, enforce style guides, and analyze readability metrics.

Documentationby a5c-ai

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Doc Ops pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/a5c-ai-tech-writing-lint/SKILL.md

decimalai skills pull a5c-ai-tech-writing-lint --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/a5c-ai-tech-writing-lint/SKILL.md https://app.decimal.ai/s/a5c-ai-tech-writing-lint/SKILL.md

Raw file: /s/a5c-ai-tech-writing-lint/SKILL.md ↗ · machine-readable summary at /s/a5c-ai-tech-writing-lint.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 17d ago

Yes — +45% lift · at higher cost+82% tokens0% turns68% of whole cases pass with skill (15/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	41%	0%
case-09	✗→✓	▲ Improved	164%	0%
case-10	✗→✓	▲ Improved	93%	0%
case-11	✗→✓	▲ Improved	63%	0%
case-13	✗→✓	▲ Improved	11%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v5 — 8/17/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

a5c-ai / babysitter

library/specializations/technical-documentation/skills/tech-writing-lint/SKILL.md

View on GitHub ↗

License MITImported 8/17/2026Version v1

Skill contents

SKILL.md

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

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

Output Structure

Lint Output

json
{
  "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

json
{
  "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

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

yaml
# .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

yaml
# .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

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

Inclusive Language Checks

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

json
{
  "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

yaml
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

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

Dependencies

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

CLI Commands

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

Illustrative Want to see what a5c-ai/tech-writing-lint would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

9/8/2026, 13:56 UTC · 22 cases

Lift

+45%

68% vs 23%

Agent turns

1.0 vs 1.0

Tokens

+82%

3,810.09 vs 2,098.73

fail → pass · 10pass → pass · 5fail → fail · 7

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 Please evaluate our documentation directory at `./docs` for writing style compliance and text clarity. I need a JSON report summarizing the scanned files, total count of errors, warnings, and suggestions, along with an array of specific flagged issues specifying the file path, line, column, rule name, and context. Also include readability scores like Flesch-Kincaid and Gunning Fog for the content.	fail→pass	20,650	18,288	-11%	1	1	0%	3,445	4,858	+41%	0	0	—
case-02 Run a terminology check across the files in `./docs/api` using our glossary at `./docs/glossary.yml`. Generate a structured breakdown listing any term inconsistencies—including the variant spellings found, preferred standard forms, and file locations—as well as any key terms that appear frequently but lack formal definitions in the glossary.	fail→fail	31,549	13,520	-57%	1	1	0%	2,913	4,015	+38%	0	0	—
case-03 Audit our user guide located at `./docs/guide.md` specifically for inclusive language and non-discriminatory phrasing. I want an output detailing all detected issues, including the severity level, the line and column position, the original text snippet, and the recommended alternative terms to replace non-inclusive language.	fail→fail	13,372	22,010	+65%	1	1	0%	1,420	5,672	+299%	0	0	—
case-04 We need to publish our Markdown documentation from `./docs` into a static site generator. Convert `docs/index.md` into HTML using Pandoc CLI flags for standalone document creation.	pass→pass	11,436	10,648	-7%	1	1	0%	1,011	3,323	+229%	0	0	—
case-05 Write an OpenAPI 3.0 specification in YAML format for a REST endpoint POST /users that accepts a JSON body with username and email.	pass→pass	11,113	16,009	+44%	1	1	0%	1,121	4,400	+293%	0	0	—
case-06 Configure a GitHub Actions workflow in `.github/workflows/deploy.yml` to deploy static HTML assets to an Amazon S3 bucket using the AWS CLI.	pass→pass	15,013	15,270	+2%	1	1	0%	2,091	4,359	+108%	0	0	—
case-07 Configure a custom Vale rule file at `.vale/styles/Custom/Terminology.yml` to automatically swap non-standard software terminology like e-mail, back-end, and on-premise with their standardized document forms.	pass→pass	12,738	9,398	-26%	1	1	0%	1,403	3,075	+119%	0	0	—
case-08 Define a custom Vale rule file at `.vale/styles/Custom/ActiveVoice.yml` that flags passive auxiliary verb phrases like 'is being', 'has been', or 'will be' as warnings.	pass→pass	13,046	8,760	-33%	1	1	0%	1,612	2,908	+80%	0	0	—
case-09 Set up a `.vale.ini` configuration file for markdown docs that applies Google and write-good styles, sets the global minimum alert level to suggestion, and turns off standard Vale spell checking.	fail→pass	11,500	9,516	-17%	1	1	0%	1,158	3,062	+164%	0	0	—
case-10 Specify the required devDependencies entry in package.json to assemble an automated documentation linting and prose quality toolchain.	fail→pass	14,780	10,000	-32%	1	1	0%	1,602	3,089	+93%	0	0	—
case-11 Construct a glossary structure in YAML for documentation governance that defines how subjective or patronizing terms like simple, easy, just, and obviously should be cataloged.	fail→pass	20,799	20,222	-3%	1	1	0%	3,103	5,051	+63%	0	0	—
case-12 What are the recommended numerical target ranges for Flesch-Kincaid ease and Gunning Fog index when evaluating technical documentation clarity?	fail→fail	29,458	8,671	-71%	1	1	0%	2,301	3,706	+61%	0	0	—
case-13 Write a configuration file for an inclusive language linter that explicitly permits the word execute while strictly enforcing non-binary gender language checks.	fail→pass	27,535	15,076	-45%	1	1	0%	3,482	3,849	+11%	0	0	—
case-14 Create a glossary definition in YAML for the acronym SDK and the term backend, specifying expansion behavior and spelling conventions.	fail→pass	14,967	10,282	-31%	1	1	0%	2,009	3,225	+61%	0	0	—
case-15 Compare how the Google Developer Docs Style Guide and Microsoft Writing Style Guide handle Passive Voice and Future Tense violations.	fail→fail	21,410	22,843	+7%	1	1	0%	2,942	5,448	+85%	0	0	—
case-16 Generate a complete JSON readability analysis report for `docs/quickstart.md` detailing readability indices, sentence metrics, and improvement recommendations.	fail→pass	24,278	15,401	-37%	1	1	0%	4,282	4,423	+3%	0	0	—
case-17 List the shell commands needed to synchronize external style packages, run inclusive language checks on `./docs`, and evaluate Markdown files with write-good.	fail→fail	12,869	7,410	-42%	1	1	0%	1,267	2,618	+107%	0	0	—
case-18 Show how `.vale.ini` should configure style inheritance differently for standard `.mdx` files versus `CHANGELOG.md` files.	fail→fail	16,933	15,059	-11%	1	1	0%	1,882	3,818	+103%	0	0	—
case-19 In custom Vale overrides for Google style rules, what severity levels should be assigned to Google.Passive, Google.We, Google.Will, and Google.Wordiness?	fail→pass	19,126	7,426	-61%	1	1	0%	2,308	2,638	+14%	0	0	—
case-20 Construct the input JSON payload required to run a full lint action on `./docs` using the Google style guide and `.vale.ini` config file.	fail→pass	11,677	8,135	-30%	1	1	0%	1,088	2,789	+156%	0	0	—
case-21 Define the glossary casing and usage guidelines for the terms API and OAuth in YAML format.	fail→pass	12,316	11,247	-9%	1	1	0%	1,144	3,257	+185%	0	0	—
case-22 Outline the full 6-step sequential pipeline for automated documentation quality enforcement from initialization to final output.	fail→fail	20,468	17,899	-13%	1	1	0%	2,588	4,239	+64%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +45 percentage points is the difference between those two pass rates over the 22 comparable cases. 1 case got worse with the skill loaded, and it is included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 22.7%
Pass rate with the skill: 68.2%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 1
Skill version measured: v1
Run completed: 9/8/2026, 13:56 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

Please evaluate our documentation directory at `./docs` for writing style compliance and text clarity. I need a JSON report summarizing the scanned files, total count of errors, warnings, and suggestions, along with an array of specific flagged issues specifying the file path, line, column, rule name, and context. Also include readability scores like Flesch-Kincaid and Gunning Fog for the content.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run68

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+150% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 17 days ago

Other measured skills in the registry, with their headline benchmark lift.