Agent Skills Went Vendor-Neutral: Building a Writing-Quality Skill for Claude, Codex and Gemini

writing-quality/ ├── SKILL.md ├── references/ │ └── CHECKS.md └── scripts/ └── check_writing.py 

--- name: writing-quality description: Reviews and tightens prose drafts (blog posts, docs, newsletters, emails, essays) for clarity, rhythm and filler. Runs a local checker that measures sentence-length variety, readability, passive voice, filler phrases, overused AI-style wording and repeated openers, then fixes the flagged spots without changing meaning. Use when the user asks to proofread, polish, edit, tighten or improve the writing quality of a draft, or asks why a draft sounds robotic or generic. license: MIT compatibility: Requires Python 3.9+ (standard library only). No network access needed. metadata: author: mohab-abdelkarim version: "1.0.0" --- # Writing quality  Use this skill to review a prose draft and improve it with evidence, not guesswork. ## Workflow  1. Save the draft to a file if it only exists in the conversation (for example `draft.md`). 2. Run the checker that ships with this skill: `python3 <skill-folder>/scripts/check_writing.py draft.md`. The script path is relative to this SKILL.md file. Add `--json` for machine-readable output, or `--strict` to exit with code 1 when any check fails (useful in CI). 3. Read the report. Each check prints PASS or WARN with the exact sentences or phrases involved. 4. Fix only what the report flags: - Split or vary sentences listed under "Longest sentences" when the length check warns. - Rewrite sentences listed under "Passive voice" into active voice where the actor matters. - Delete or replace every phrase listed under "Filler phrases" and "Overused AI-style wording". - Reword repeated sentence openers so consecutive sentences start differently. 5. Re-run the checker on the edited draft and repeat until every check passes or the remaining warnings are deliberate. 6. Show the user a short summary: which checks failed before, what you changed, and the final report. ## Rules  - Never change facts, numbers, names, quotes or the author's claims. This skill edits style, not substance. - Keep the author's voice. Prefer the smallest edit that clears a warning. - Do not add new sections, headings or content the author didn't write. - If a warning is intentional (for example a long sentence in a legal clause), leave it and say why. ## Reference  See [references/CHECKS.md](references/CHECKS.md) for what each check measures, its threshold, and how to fix it. 

# Checks and thresholds  | Check | What it measures | Warns when | How to fix | |---|---|---|---| | Sentence variety | Standard deviation of sentence length (words) | Below 5 words | Mix short sentences with longer ones; split the longest sentences | | Long sentences | Sentences over 35 words | Any found | Split at a conjunction or move a clause into its own sentence | | Readability | Flesch Reading Ease (approximate syllable count) | Below 50 | Use shorter words and sentences | | Passive voice | "be" verb followed by a past participle (heuristic) | Over 15% of sentences | Name the actor and make it the subject | | Filler phrases | Phrases like "it is important to note that", "in order to" | Any found | Delete them or use the short form ("to") | | AI-style wording | Overused words and phrases common in generated text ("delve", "tapestry", "in today's fast-paced world") | Any found | Replace with a plain, specific word | | Repeated openers | The same first word in 3+ consecutive sentences | Any run found | Vary how the sentences start | | Em dashes | Count of em dashes | More than 2 per 500 words | Use commas, colons, parentheses or a new sentence | All checks are heuristics. They point at places worth a second look; they do not prove anything about who wrote the text. 

#!/usr/bin/env python3 """Writing-quality checker for the writing-quality Agent Skill. Standard library only. Usage: python3 check_writing.py draft.md [--json] [--strict] cat draft.md | python3 check_writing.py - [--json] """ import argparse import json import re import statistics import sys FILLER = [ "it is important to note that", "it's important to note that", "it is worth noting that", "it's worth noting that", "in order to", "the fact that", "at the end of the day", "needless to say", "for all intents and purposes", "due to the fact that", "in today's world", "when it comes to", "a wide range of", "a variety of", "it goes without saying", "plays a crucial role", "plays an essential role", "plays a vital role", ] AI_STYLE = [ "delve", "delves", "delving", "tapestry", "testament to", "in today's fast-paced", "in the ever-evolving", "ever-evolving landscape", "navigate the complexities", "unlock the potential", "unlock the power", "game-changer", "game changer", "seamlessly", "seamless", "leverage", "harness the power", "elevate your", "embark on", "a myriad of", "robust", "pivotal", "realm", "foster", "furthermore", "moreover", "in conclusion", "additionally", ] BE_VERBS = r"(?:am|is|are|was|were|be|been|being)" IRREGULAR_PP = ( "built|done|given|made|seen|shown|taken|written|known|found|kept|left|held|brought|bought|" "taught|thought|told|sold|sent|spent|paid|put|set|run|won|chosen|driven|eaten|fallen|forgotten|" "gotten|hidden|ridden|risen|spoken|stolen|sworn|torn|worn|broken|frozen" ) PASSIVE_RE = re.compile(rf"\b{BE_VERBS}\s+(?:\w+ly\s+)?(?:\w+ed|{IRREGULAR_PP})\b", re.I) def strip_markdown(text): text = re.sub(r"``` .*? ```", " ", text, flags=re.S) # code blocks text = re.sub(r"`[^`]*`", " ", text) # inline code text = re.sub(r"!\[[^\]]*\]\([^)]*\)", " ", text) # images text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text) # links -> text text = re.sub(r"^\s{0,3}#{1,6}\s+.*$", " ", text, flags=re.M) # headings text = re.sub(r"^\s*[-*+]\s+", "", text, flags=re.M) # bullets text = re.sub(r"[*_]{1,3}", "", text) # emphasis return text def split_sentences(text): text = re.sub(r"\s+", " ", text).strip() parts = re.split(r"(?<=[.!?])[\"')\]]*\s+(?=[A-Z0-9\"'(])", text) return [p.strip() for p in parts if len(p.split()) >= 3] def syllables(word): word = re.sub(r"[^a-z]", "", word.lower()) if not word: return 0 groups = re.findall(r"[aeiouy]+", word) count = len(groups) if word.endswith("e") and not word.endswith(("le", "ee")) and count > 1: count -= 1 return max(count, 1) def find_phrases(text, phrases): found = {} low = text.lower().replace("\u2019", "'") # curly apostrophe for p in phrases: n = len(re.findall(rf"\b{re.escape(p)}\b", low)) if n: found[p] = n return found def analyze(raw): text = strip_markdown(raw) sentences = split_sentences(text) words = re.findall(r"[A-Za-z0-9']+", text) if not sentences or not words: raise ValueError("No prose found. Pass a file with at least a few full sentences.") lengths = [len(s.split()) for s in sentences] syl = sum(syllables(w) for w in words) flesch = 206.835 - 1.015 * (len(words) / len(sentences)) - 84.6 * (syl / len(words)) passive = [s for s in sentences if PASSIVE_RE.search(s)] openers = [re.sub(r"[^a-z]", "", s.split()[0].lower()) for s in sentences] runs, i = [], 0 while i < len(openers): j = i while j + 1 < len(openers) and openers[j + 1] == openers[i] and openers[i]: j += 1 if j - i + 1 >= 3: runs.append({"word": openers[i], "count": j - i + 1}) i = j + 1 em = raw.count("\u2014") # em dash em_limit = max(2, round(2 * len(words) / 500)) stdev = statistics.pstdev(lengths) if len(lengths) > 1 else 0.0 long_sentences = [s for s, n in zip(sentences, lengths) if n > 35] filler = find_phrases(text, FILLER) ai_style = find_phrases(text, AI_STYLE) passive_share = len(passive) / len(sentences) checks = [ {"check": "Sentence variety", "value": round(stdev, 1), "pass": stdev >= 5, "detail": f"std dev {stdev:.1f} words (want 5+), average {statistics.mean(lengths):.1f} words"}, {"check": "Long sentences", "value": len(long_sentences), "pass": not long_sentences, "items": long_sentences[:5]}, {"check": "Readability", "value": round(flesch, 1), "pass": flesch >= 50, "detail": f"Flesch Reading Ease {flesch:.1f} (want 50+; higher is easier)"}, {"check": "Passive voice", "value": round(passive_share * 100), "pass": passive_share <= 0.15, "detail": f"{len(passive)} of {len(sentences)} sentences ({passive_share:.0%}, want 15% or less)", "items": passive[:5]}, {"check": "Filler phrases", "value": sum(filler.values()), "pass": not filler, "items": filler}, {"check": "AI-style wording", "value": sum(ai_style.values()), "pass": not ai_style, "items": ai_style}, {"check": "Repeated openers", "value": len(runs), "pass": not runs, "items": runs}, {"check": "Em dashes", "value": em, "pass": em <= em_limit, "detail": f"{em} found (limit {em_limit} for this length)"}, ] longest = sorted(zip(lengths, sentences), reverse=True)[:3] return { "words": len(words), "sentences": len(sentences), "passed": sum(c["pass"] for c in checks), "total": len(checks), "checks": checks, "longest_sentences": [{"words": n, "sentence": s} for n, s in longest], } def shorten(text, limit): if len(text) <= limit: return text return text[:limit].rsplit(" ", 1)[0] + " ..." def print_report(r): print(f"Writing-quality report: {r['words']} words, {r['sentences']} sentences") print(f"Passed {r['passed']} of {r['total']} checks\n") for c in r["checks"]: status = "PASS" if c["pass"] else "WARN" line = f"[{status}] {c['check']}" if c.get("detail"): line += f": {c['detail']}" elif not c["pass"]: line += f": {c['value']} found" print(line) if not c["pass"] and c.get("items"): items = c["items"] if isinstance(items, dict): for k, v in items.items(): print(f" - \"{k}\" x{v}") else: for it in items: text = it if isinstance(it, str) else f"{it['count']} sentences in a row start with \"{it['word']}\"" print(f" - {shorten(text, 160)}") print("\nLongest sentences:") for s in r["longest_sentences"]: print(f" ({s['words']} words) {shorten(s['sentence'], 140)}") def main(): ap = argparse.ArgumentParser(description="Check a prose draft for clarity, rhythm and filler.") ap.add_argument("path", help="Markdown or text file, or - for stdin") ap.add_argument("--json", action="store_true", help="print JSON instead of a text report") ap.add_argument("--strict", action="store_true", help="exit 1 if any check fails") a = ap.parse_args() try: raw = sys.stdin.read() if a.path == "-" else open(a.path, encoding="utf-8").read() report =Source：https://dev.to/mohab_karim/agent-skills-went-vendor-neutral-building-a-writing-quality-skill-for-claude-codex-and-gemini-31ie
My favorites