commit 3f033af5ea15fa2e63ace5af7ce762e3bb4d4da3
Author: Jeff Pegg <jeff.pegg@gmail.com>
Date:   Thu Feb 12 17:08:42 2026 -0600

    Add humanize-writing skill with npm packaging
    
    Skill that rewrites AI-generated content to sound human. Includes
    install/uninstall scripts that copy skill files to ~/.claude/skills/,
    ~/.cursor/skills/, and ~/.windsurf/skills/ for cross-agent support.
    
    Publishable via npm (@jpegg/humanize-writing) and skills.sh.
    
    Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7cf97fa
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+*.tgz
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..ed8d8e1
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jpeggdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8a9d2e6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# humanize-writing
+
+A Claude Code skill that rewrites AI-generated content to sound like a human wrote it.
+
+## What it does
+
+Detects and fixes common AI writing patterns:
+
+- **Formulaic structure** — every section following the same setup/explanation/takeaway template
+- **AI vocabulary** — "delve," "landscape," "leverage," "tapestry," and dozens more
+- **Robotic rhythm** — every sentence the same length, no short punchy ones, no fragments
+- **Chronic hedging** — "It's worth noting," "While there are certainly challenges..."
+- **Missing personality** — no opinions, asides, or informal register anywhere
+
+See [SKILL.md](SKILL.md) for the full editing process and [references/ai-tells.md](references/ai-tells.md) for the complete detection checklist.
+
+## Install
+
+### Via skills.sh (GitHub-based)
+
+```
+npx skills add jpeggdev/humanize-writing
+```
+
+### Via npm
+
+```
+npm install -g @jpegg/humanize-writing
+```
+
+The postinstall script copies the skill files to `~/.claude/skills/humanize-writing/` (and equivalent directories for Cursor and Windsurf).
+
+## Usage
+
+Once installed, the skill activates automatically in Claude Code when you say things like:
+
+- "humanize this"
+- "sounds like AI"
+- "make it sound human"
+- "too robotic"
+- "de-AI this"
+
+## Uninstall
+
+```
+npm uninstall -g @jpegg/humanize-writing
+```
+
+This removes the skill files from all agent skill directories.
+
+## License
+
+MIT
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..df3a530
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,182 @@
+---
+name: humanize-writing
+version: 1.0.0
+description: "When the user wants to make writing sound less AI-generated. Also use when the user mentions 'sounds like AI,' 'too robotic,' 'humanize this,' 'make it sound human,' 'de-AI this,' 'sounds like ChatGPT,' 'make it natural,' or 'doesn't sound like a person wrote it.' This skill rewrites content to eliminate common AI writing patterns while preserving meaning."
+---
+
+# Humanize Writing
+
+You are an expert editor who specializes in detecting and removing AI writing patterns. Your job is to take content that reads like it was generated by a language model and rewrite it so it sounds like a knowledgeable human wrote it on the first try.
+
+## Core Philosophy
+
+AI writing has a recognizable smell. It's not about any single word or trick. It's the combination: predictable structure, hedge-then-assert phrasing, relentless parallelism, and a tendency to wrap everything in a tidy bow. Human writing is messier, more opinionated, and varies in rhythm.
+
+**Your job is not to dumb the writing down.** It's to make it sound like it came from someone who actually knows what they're talking about and has opinions about it.
+
+---
+
+## The Editing Process
+
+### Pass 1: Kill the Structure Tells
+
+AI loves formulas. The same section shape repeated ten times. Every paragraph built identically. Fix this first because it's the most visible tell.
+
+**What to look for:**
+- Every section ending with a neat "takeaway" or "bottom line"
+- Repeated callout patterns ("What this means for you:", "The takeaway:", "Why it matters:")
+- Identical paragraph counts per section
+- Every list having exactly the same number of items
+- "Setup paragraph, explanation, conclusion" repeated verbatim across sections
+
+**How to fix it:**
+- Vary section lengths. Some sections get two paragraphs. Some get five.
+- Let some sections end abruptly. Not everything needs a bow on it.
+- Break the pattern. If three sections have lists, make the fourth a narrative paragraph.
+- Merge the "what this means" into the main text instead of calling it out separately.
+
+---
+
+### Pass 2: Replace AI Vocabulary
+
+Certain words and phrases are dead giveaways. See [references/ai-tells.md](references/ai-tells.md) for the full list.
+
+**The worst offenders:**
+- "Fundamental shift" / "paradigm shift" / "game-changer"
+- "Landscape" (as in "the 2026 landscape")
+- "Leverage" (when you mean "use")
+- "Harness" (when you mean "use")
+- "Delve" / "delve into"
+- "Tapestry" / "rich tapestry"
+- "Navigate" (when you mean "deal with" or "figure out")
+- "Realm" (when you mean "area" or "field")
+- "Embark on a journey"
+- "It's worth noting"
+- "In today's [X]"
+- "At its core"
+
+**The fix isn't always a synonym.** Often the sentence needs restructuring, not just a word swap. "The landscape has fundamentally shifted" becomes "Things changed fast this year."
+
+---
+
+### Pass 3: Fix Sentence Rhythm
+
+AI writes in a metronomic cadence. Medium sentence. Medium sentence. Medium sentence. Humans vary wildly.
+
+**What to look for:**
+- Every sentence roughly the same length (15-25 words)
+- No short punchy sentences (under 8 words)
+- No longer flowing sentences that build momentum
+- Every sentence starting with a noun or "The"
+
+**How to fix it:**
+- Throw in some short ones. "That's new." "It works." "Not anymore."
+- Let some sentences run a bit longer when the idea needs room to breathe.
+- Start some sentences with "But," "And," "So," or "Look,"
+- Use fragments occasionally. They're fine in non-academic writing.
+
+---
+
+### Pass 4: Cut the Hedging and Qualifiers
+
+AI hedges constantly because it's trained to be balanced. Humans with expertise are more direct.
+
+**What to look for:**
+- "It's important to note that..."
+- "It's worth mentioning..."
+- "While there are certainly challenges..."
+- "This is not without its drawbacks..."
+- "To be sure..." / "To be fair..."
+- Starting with "Certainly," or "Absolutely,"
+- "Not X, but Y" constructions used more than once
+
+**How to fix it:**
+- Just say the thing. "It's important to note that teams are struggling with churn" becomes "Teams are struggling with churn."
+- Pick a side when the writing has an obvious perspective. Don't both-sides everything.
+- One hedge per article is fine. Five is AI.
+
+---
+
+### Pass 5: Add Human Texture
+
+Real writers have opinions, make references, use casual asides, and occasionally break register.
+
+**Techniques:**
+- Add an aside that shows the writer has actually experienced what they're writing about: "used to be a science project," "that already sounds quaint"
+- Use slightly informal phrasing in places: "without waking anyone up," "you don't have to love them, but you need to know them"
+- Let the writer's personality show. A dry observation. A mild exaggeration. A colloquial verb.
+- Reference shared experiences: "If you've ever tried to..." "Anyone who's debugged a..."
+
+**What NOT to do:**
+- Don't overdo it. One or two casual asides per section, max.
+- Don't add slang or try to be hip. That reads as forced.
+- Don't insert "I" unless the piece is already first-person.
+- Don't add humor that doesn't serve the point.
+
+---
+
+### Pass 6: Fix the Connective Tissue
+
+AI uses the same transitions over and over. Humans vary them or skip them entirely.
+
+**AI's favorite transitions (overused):**
+- "Moreover" / "Furthermore" / "Additionally"
+- "In conclusion" / "To sum up"
+- "That said" / "That being said"
+- "With that in mind"
+- "Moving forward"
+- "When it comes to"
+
+**Better approaches:**
+- Often you don't need a transition at all. Just start the next thought.
+- Use the actual logical connection: "because," "so," "but," "and"
+- Reference the previous idea directly instead of using a generic connector.
+- Let paragraph breaks do the transitional work.
+
+---
+
+## The "Read It Out Loud" Test
+
+After all passes, read the piece out loud (or imagine reading it to a colleague). Flag anything that:
+- Sounds like a press release
+- No human would actually say in conversation
+- Makes you cringe slightly
+- Feels like it's trying too hard to sound smart
+- Could have been written about literally any topic by swapping a few nouns
+
+---
+
+## What to Preserve
+
+Not everything needs to change. Keep:
+- Technical accuracy and specific data points
+- Proper nouns, product names, and attributions
+- The core argument and structure (rearrange within sections, not between them)
+- Formatting choices (headers, lists, bold) unless they're part of the AI pattern
+
+---
+
+## Output Format
+
+When rewriting:
+1. Rewrite the full content with changes applied
+2. After the rewrite, provide a brief summary of what you changed and why (5-8 bullet points max)
+
+When reviewing without rewriting (if asked):
+1. Flag specific passages that read as AI-generated
+2. Explain which pattern each one triggers
+3. Suggest concrete alternatives
+
+---
+
+## References
+
+- [AI Writing Tells](references/ai-tells.md): Complete list of words, phrases, and patterns that signal AI-generated content
+
+---
+
+## Related Skills
+
+- **copy-editing**: For broader marketing copy quality (use after humanizing)
+- **copywriting**: For writing new copy from scratch
+- **seo-audit > ai-writing-detection**: For SEO-specific AI detection concerns
diff --git a/install-skill.js b/install-skill.js
new file mode 100644
index 0000000..5f1deda
--- /dev/null
+++ b/install-skill.js
@@ -0,0 +1,31 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const SKILL_NAME = "humanize-writing";
+const SKILL_DIRS = [
+  path.join(os.homedir(), ".claude", "skills", SKILL_NAME),
+  path.join(os.homedir(), ".cursor", "skills", SKILL_NAME),
+  path.join(os.homedir(), ".windsurf", "skills", SKILL_NAME),
+];
+
+const srcDir = __dirname;
+const filesToCopy = ["SKILL.md", path.join("references", "ai-tells.md")];
+
+for (const destDir of SKILL_DIRS) {
+  try {
+    for (const file of filesToCopy) {
+      const src = path.join(srcDir, file);
+      const dest = path.join(destDir, file);
+
+      if (!fs.existsSync(src)) continue;
+
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+    }
+    console.log(`Installed ${SKILL_NAME} skill to ${destDir}`);
+  } catch (err) {
+    // Non-fatal — some agent directories may not exist or be writable
+    console.warn(`Skipped ${destDir}: ${err.message}`);
+  }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..fa791c3
--- /dev/null
+++ b/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "@jpegg/humanize-writing",
+  "version": "1.0.0",
+  "description": "Claude Code skill that rewrites AI-generated content to sound human. Detects and fixes AI writing patterns including formulaic structure, overused vocabulary, hedging, and robotic rhythm.",
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "node install-skill.js",
+    "preuninstall": "node uninstall-skill.js"
+  },
+  "keywords": [
+    "claude",
+    "skill",
+    "agent",
+    "writing",
+    "humanize",
+    "ai-detection"
+  ],
+  "author": "jpeggdev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jpeggdev/humanize-writing"
+  },
+  "files": [
+    "SKILL.md",
+    "references/",
+    "install-skill.js",
+    "uninstall-skill.js"
+  ]
+}
diff --git a/references/ai-tells.md b/references/ai-tells.md
new file mode 100644
index 0000000..c04c3f1
--- /dev/null
+++ b/references/ai-tells.md
@@ -0,0 +1,178 @@
+# AI Writing Tells
+
+Patterns, words, and structures that signal AI-generated content. Organized by category.
+
+---
+
+## Vocabulary: Words AI Overuses
+
+### Tier 1: Immediate Red Flags
+
+These words almost never appear in natural human writing at the frequency AI uses them.
+
+| AI Word/Phrase | Human Alternative |
+|---|---|
+| Delve / delve into | Look at, dig into, explore |
+| Landscape (metaphorical) | Scene, world, space, field — or just drop it |
+| Tapestry / rich tapestry | (delete entirely) |
+| Paradigm shift | Big change, sea change |
+| Fundamental shift | Things changed, the ground moved |
+| Game-changer | (be specific about what changed) |
+| Leverage (verb) | Use |
+| Harness | Use, take advantage of |
+| Navigate (metaphorical) | Deal with, figure out, handle |
+| Realm | Area, field, world |
+| Embark on a journey | Start, begin |
+| Myriad | Many, a lot of |
+| Plethora | Many, plenty of |
+| Multifaceted | Complex, varied |
+| Groundbreaking | New, first-of-its-kind |
+| Revolutionize | Change, reshape, overhaul |
+| Synergy | (be specific about what's combining) |
+| Ecosystem (non-technical) | World, space, community |
+| Resonate | Connect, land, hit home |
+| Streamline | Simplify, speed up, cut steps from |
+
+### Tier 2: Suspicious in Clusters
+
+Fine alone, but AI uses these in combination. Three or more in one piece is a tell.
+
+| AI Word/Phrase | Human Alternative |
+|---|---|
+| Robust | Strong, solid, thorough |
+| Seamless | Smooth, easy |
+| Cutting-edge | New, modern, latest |
+| Innovative | New, clever, original |
+| Comprehensive | Full, complete, thorough |
+| Pivotal | Key, important, critical |
+| Nuanced | Subtle, complex |
+| Compelling | Strong, convincing, interesting |
+| Transformative | (be specific about the transformation) |
+| Bolster | Strengthen, support, boost |
+| Underscore | Highlight, show, emphasize |
+| Evolving | Changing |
+| Fostering | Building, encouraging, growing |
+| Imperative | Essential, necessary, urgent |
+| Intricate | Complex, detailed |
+| Overarching | Main, broad, overall |
+| Unprecedented | (be specific — new? first? biggest?) |
+
+---
+
+## Phrases: Sentence Starters and Filler
+
+### "It's worth..." Family
+
+- "It's worth noting that..." → Just state the thing.
+- "It's important to note..." → Just state the thing.
+- "It's crucial to understand..." → Just state the thing.
+- "It bears mentioning..." → Just state the thing.
+
+### "In today's..." Family
+
+- "In today's fast-paced world..." → (delete)
+- "In today's digital landscape..." → (delete)
+- "In today's competitive market..." → (delete)
+- "In an era of..." → (delete or be specific)
+
+### "At its core..." Family
+
+- "At its core..." → (delete or restructure)
+- "At the end of the day..." → (delete or replace with "ultimately" if you must)
+- "When all is said and done..." → (delete)
+
+### Hedging Starters
+
+- "While there are certainly..." → Pick a side.
+- "To be sure..." → (delete)
+- "That said..." → "But" (once per piece max)
+- "This is not without its challenges..." → Name the challenge directly.
+- "It remains to be seen..." → "We don't know yet" or (delete)
+
+### AI Closers
+
+- "The bottom line is..." → (just make your point)
+- "Only time will tell..." → (delete)
+- "The future is bright..." → (delete or be specific)
+- "Start your journey today" → (be specific about the action)
+
+---
+
+## Structure: Patterns That Reveal AI
+
+### The Formulaic Section
+
+Every section follows: Setup → Explanation → "What this means for you" / "The takeaway"
+
+**Fix:** Vary endings. Some sections end with a question. Some end mid-thought. Some end with a specific example. Some just stop.
+
+### The Parallel List
+
+AI makes every bullet point the same grammatical structure and similar length.
+
+**Fix:** Let some bullets be short. Let some be a full sentence. Break one into a sub-list if it needs it.
+
+### The "Not X, but Y" Construction
+
+"Not by writing more code, but by orchestrating agents that do."
+
+Fine once. AI uses it 5-10 times per piece.
+
+**Fix:** Use it once, max twice. Restructure the rest.
+
+### The Tricolon Close
+
+"Start building, start learning, start growing."
+
+**Fix:** Use a single direct statement instead. Or just two items.
+
+### The Balanced Conclusion
+
+"The gap between X and Y is widening. The good news: [positive]. The challenge: [negative]. [Inspiring closer.]"
+
+**Fix:** End with one strong statement, not a perfectly balanced assessment.
+
+### The Em-Dash Epidemic
+
+AI uses em dashes — like this — constantly, often multiple times per paragraph.
+
+**Fix:** Use periods. Use commas. Restructure the sentence. One em dash per 3-4 paragraphs is human frequency.
+
+---
+
+## Tone: The AI "Voice"
+
+### Too Balanced
+
+AI always presents both sides. Real writers with expertise pick a position and defend it. They acknowledge counter-arguments briefly, not at equal length.
+
+### Too Positive
+
+AI defaults to optimism. "Exciting developments," "tremendous opportunity," "bright future." Real writing is more measured and occasionally pessimistic.
+
+### Too Smooth
+
+AI never stumbles, pauses, or doubles back. Every transition is polished. Real writing has slight roughness — a parenthetical aside, a sentence that starts one way and pivots, a blunt statement after a complex one.
+
+### No Personality
+
+AI doesn't have opinions, pet peeves, or a sense of humor. Adding these (sparingly) makes writing feel authored by someone real.
+
+---
+
+## Detection Heuristic
+
+Score the piece on these dimensions. 5+ hits = likely AI-generated:
+
+- [ ] Uses 3+ Tier 1 vocabulary words
+- [ ] Uses 5+ Tier 2 vocabulary words
+- [ ] Has "It's worth noting" or similar filler phrases
+- [ ] Every section follows the same structure
+- [ ] "Not X, but Y" appears more than twice
+- [ ] Em dashes appear more than once per paragraph
+- [ ] No sentences under 8 words
+- [ ] No informal or colloquial language anywhere
+- [ ] Conclusion is perfectly balanced (good news/bad news/inspiring close)
+- [ ] Every list has the same number of items
+- [ ] No opinions, asides, or personality
+- [ ] Every claim is hedged with "certainly" or "to be sure"
diff --git a/uninstall-skill.js b/uninstall-skill.js
new file mode 100644
index 0000000..19aa2cf
--- /dev/null
+++ b/uninstall-skill.js
@@ -0,0 +1,21 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const SKILL_NAME = "humanize-writing";
+const SKILL_DIRS = [
+  path.join(os.homedir(), ".claude", "skills", SKILL_NAME),
+  path.join(os.homedir(), ".cursor", "skills", SKILL_NAME),
+  path.join(os.homedir(), ".windsurf", "skills", SKILL_NAME),
+];
+
+for (const dir of SKILL_DIRS) {
+  try {
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true });
+      console.log(`Removed ${SKILL_NAME} skill from ${dir}`);
+    }
+  } catch (err) {
+    console.warn(`Skipped ${dir}: ${err.message}`);
+  }
+}