Help Center Articles skill for Claude Code

#!/usr/bin/env python3
"""Lint end-user help center articles written in Markdown.

Usage:
    python3 check_article.py <file.md | directory> [--max-steps 12] [--max-words 30]

Checks per article:
  errors   - no H1 title; generic title start (Overview, Introduction to, Using the, About the,
             All about); missing summary paragraph right after the title; how-to article (title
             starts with a verb) without a numbered list; images without alt text;
             "click here" / "here" link text
  warnings - more than --max-steps numbered steps in one list; a step with several actions
             ("and then", "then"); bare URLs; device-specific verbs (click, tap, right-click)
             outside a platform-labeled section; reader-blaming words (simply, just, easy,
             obviously); sentences longer than --max-words words; title longer than 70 chars
Exits 1 if any article has errors, 2 if no Markdown files are found.
"""
import argparse
import os
import re
import sys

GENERIC = re.compile(r"^(overview|introduction to|intro to|using the|about the|all about|the .* feature)\b", re.I)
VERB_START = re.compile(r"^(add|change|connect|create|delete|disable|download|edit|enable|export|find|"
                        r"import|install|invite|manage|move|remove|rename|reset|restore|set up|"
                        r"share|sign|turn|update|upgrade|use|view|cancel|configure|transfer|merge|"
                        r"schedule|send|archive|recover|verify|switch|print|pay)\b", re.I)
BLAME = re.compile(r"\b(simply|just|easy|easily|obviously|of course)\b", re.I)
DEVICE = re.compile(r"\b(click|clicking|right-click|double-click|tap|tapping)\b", re.I)
PLATFORM_HEAD = re.compile(r"^#+\s.*\b(ios|android|mac|macos|windows|desktop|mobile|web|linux)\b", re.I)
IMG = re.compile(r"!\[([^\]]*)\]\([^)]+\)")
LINK = re.compile(r"(?<!!)\[([^\]]+)\]\([^)]+\)")
BARE_URL = re.compile(r"(?<![(<\[])\bhttps?://\S+")
STEP = re.compile(r"^\s*\d+[.)]\s+(.*)")
MULTI = re.compile(r"\b(and then|, then|then select|then choose|then enter)\b", re.I)


def check(path, max_steps, max_words):
    errors, warnings = [], []
    lines = open(path, encoding="utf-8").read().splitlines()
    in_code = False
    body = []
    for i, line in enumerate(lines, 1):
        if line.strip().startswith("```"):
            in_code = not in_code
            continue
        if not in_code:
            body.append((i, line))

    title_i = next(((i, l) for i, l in body if l.startswith("# ")), None)
    if not title_i:
        errors.append("no H1 title")
        title = ""
    else:
        title = title_i[1][2:].strip()
        if GENERIC.match(title):
            errors.append(f"generic title start: {title!r}; name the task or symptom")
        if len(title) > 70:
            warnings.append(f"title is {len(title)} chars; keep under 70")
        after = [l for i, l in body if i > title_i[0] and l.strip()]
        if not after or after[0].lstrip().startswith(("#", "1.", "-", "*", "!", "|")) and not after[0].startswith("**"):
            errors.append("missing one-sentence summary paragraph after the title")

    steps_runs, run = [], []
    platform_section = False
    for i, line in body:
        if line.startswith("#"):
            platform_section = bool(PLATFORM_HEAD.match(line))
        m = STEP.match(line)
        if m:
            run.append((i, m.group(1)))
            if MULTI.search(m.group(1)):
                warnings.append(f"line {i}: step may contain several actions; split it")
        elif line.strip() and run:
            steps_runs.append(run)
            run = []
        for alt in IMG.findall(line):
            if not alt.strip():
                errors.append(f"line {i}: image without alt text")
        for text in LINK.findall(line):
            if text.strip().lower() in ("here", "click here", "this link", "link"):
                errors.append(f"line {i}: non-descriptive link text {text!r}")
        if BARE_URL.search(line):
            warnings.append(f"line {i}: bare URL; use descriptive link text")
        if not platform_section and DEVICE.search(line):
            warnings.append(f"line {i}: device-specific verb {DEVICE.search(line).group(0)!r}; prefer 'select'")
        b = BLAME.search(line)
        if b:
            warnings.append(f"line {i}: reader-blaming word {b.group(0)!r}")
        if not line.lstrip().startswith(("|", "#")):
            for sent in re.split(r"(?<=[.!?])\s+", re.sub(r"[*`_]", "", line)):
                n = len(sent.split())
                if n > max_words:
                    warnings.append(f"line {i}: sentence of {n} words")
    if run:
        steps_runs.append(run)

    if title and VERB_START.match(title) and not steps_runs:
        errors.append("how-to title but no numbered steps")
    for r in steps_runs:
        if len(r) > max_steps:
            warnings.append(f"line {r[0][0]}: {len(r)} steps in one list; split into sub-tasks")
    return errors, warnings


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("target")
    ap.add_argument("--max-steps", type=int, default=12)
    ap.add_argument("--max-words", type=int, default=30)
    args = ap.parse_args()

    if os.path.isdir(args.target):
        files = sorted(os.path.join(dp, f) for dp, _, fs in os.walk(args.target) for f in fs if f.endswith((".md", ".mdx")))
    else:
        files = [args.target] if args.target.endswith((".md", ".mdx")) else []
    if not files:
        print("error: no Markdown files found", file=sys.stderr)
        sys.exit(2)

    failed = 0
    for f in files:
        errs, warns = check(f, args.max_steps, args.max_words)
        status = "FAIL" if errs else ("WARN" if warns else "OK")
        print(f"{status:4} {f}  ({len(errs)} errors, {len(warns)} warnings)")
        for e in errs:
            print(f"     error: {e}")
        for w in warns:
            print(f"     warn:  {w}")
        failed += bool(errs)
    print(f"\n{len(files)} article(s), {failed} with errors")
    sys.exit(1 if failed else 0)


if __name__ == "__main__":
    main()