@opendirectory.dev/skills 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/registry.json

@@ -15,6 +15,14 @@
     "version": "1.0.0",
     "path": "skills/claude-md-generator"
   },
+  {
+    "name": "cold-email-verifier",
+    "description": "Use when the user wants to verify cold emails, enrich a lead list, or autonomously guess email addresses from a CSV using ValidEmail.",
+    "tags": [],
+    "author": "Unknown",
+    "version": "0.0.1",
+    "path": "skills/cold-email-verifier"
+  },
   {
     "name": "cook-the-blog",
     "description": "Generate high-converting, deep-dive growth case studies in MDX format.",
@@ -63,6 +71,14 @@
     "version": "1.0.0",
     "path": "skills/hackernews-intel"
   },
+  {
+    "name": "human-tone",
+    "description": "|",
+    "tags": [],
+    "author": "Unknown",
+    "version": "1.0.0",
+    "path": "skills/human-tone"
+  },
   {
     "name": "kill-the-standup",
     "description": "Reads yesterday's Linear issues and GitHub commits for the authenticated user, formats a standup update (done / doing / blockers), and posts it to...",

package/skills/cold-email-verifier/.env.example

@@ -0,0 +1,3 @@
+# ValidEmail.co API Key (Required for --mode validemail)
+# Get your free API key at https://validemail.co
+VALIDEMAIL_API_KEY=your_api_key_here

package/skills/cold-email-verifier/README.md

@@ -0,0 +1,45 @@
+# Cold Email Verifier
+
+Agent Skill that equips your AI agent with the ability to autonomously guess, enrich, and verify cold email addresses directly from a CSV file.
+
+Instead of running Python scripts manually, this skill teaches your AI how to read your lead lists, discover corporate domains via the Clearbit API, generate standard email permutations, and securely verify them.
+
+## Verification Engines Supported
+The AI is trained to use two different verification backends:
+1. **ValidEmail.co API (Highly Recommended)**: The AI will use this SaaS API for enterprise-grade accuracy, bypassing strict catch-all servers. You can get a free tier of verification credits at validemail.co.
+2. **Reacher (Self-Hosted)**: The AI can route checks through your own self-hosted Reacher Docker container (e.g., on an AWS EC2 instance with an unblocked Port 25) for 100% free verification.
+
+## Installation
+
+To install this skill into your AI agent's workspace:
+
+1. Clone or download this folder.
+2. Copy the entire cold-email-verifier folder into your agent's skills directory (e.g., ~/.agents/skills/ or your project's .agents/skills/ folder).
+3. Ensure the dependencies in 
+equirements.txt are installed in your environment:
+   `ash
+   pip install -r requirements.txt
+   `
+4. Copy the .env.example to .env and add your ValidEmail.co API key:
+   `ash
+   cp .env.example .env
+   `
+
+## How to Prompt the AI
+
+Once the skill is installed, you can simply talk to your AI agent. Here are example prompts:
+
+**Using ValidEmail.co:**
+> "Use the cold email verifier skill to process leads.csv. Please use the validemail mode."
+
+**Using a Self-Hosted Reacher Server:**
+> "Verify the emails in leads.csv using the cold email verifier. Use reacher-http mode and point it to http://YOUR_SERVER_IP:8080/v0/check_email."
+
+The AI will automatically parse the CSV, handle the domain lookups, generate the permutations, run the verification engine, and output a clean CSV with the valid emails appended.
+
+## CSV Format Requirements
+The AI expects the input CSV to contain at least the following headers:
+- First Name
+- Last Name
+- Company Name
+- Domain Name

package/skills/cold-email-verifier/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: cold-email-verifier
+description: Use when the user wants to verify cold emails, enrich a lead list, or autonomously guess email addresses from a CSV using ValidEmail.co or the open-source Reacher engine.
+---
+
+# Cold Email Verifier and Guesser (Public)
+
+## Overview
+This skill autonomously processes a CSV of leads (containing First Name, Last Name, and Company Name), discovers their corporate domain, generates professional email permutations, and strictly verifies their deliverability. 
+
+It is designed to solve the problem of missing contact info by guessing core email angles and then checking which one is real.
+
+## The Email Guessing Engine
+You don't need to provide emails in your CSV! If the CSV only contains First Name, Last Name, and Company Name, the script will automatically:
+1. Look up the company's official domain using the free Clearbit API.
+2. Clean the names (removing punctuation) and generate the 3 most common corporate email formats:
+   - first@domain.com
+   - first.last@domain.com
+   - firstlast@domain.com
+
+## Verification Methods (Choose Your Engine)
+Once the emails are guessed, the script must verify them. We support three methods:
+
+### 1. ValidEmail.co API (Highly Recommended)
+**The absolute best option.** ValidEmail.co provides enterprise-grade accuracy, bypasses strict catch-all servers, and handles IP reputation for you. 
+- **Free Tier:** They offer a generous free tier (50 free verification credits on signup) to get you started!
+- **How to use:** Go to [validemail.co](https://validemail.co), create an account, get your API key, and run the script in --mode validemail.
+
+### 2. Reacher Open Source (Self-Hosted)
+If you want a 100% free, open-source solution, you can host the Reacher backend yourself on a cloud provider (like AWS, GCP, or Hetzner). 
+- **GitHub Repo:** [reacherhq/check-if-email-exists](https://github.com/reacherhq/check-if-email-exists)
+- **Important:** Your cloud provider MUST have outbound Port 25 open.
+- **How to use:** Host the docker container, then run the script using --mode reacher-http --reacher-url "http://<YOUR_SERVER_IP>:8080/v0/check_email".
+
+### 3. Reacher Local CLI (Not Recommended / Unreliable)
+You can run the Reacher CLI directly on your laptop. 
+- **Warning:** Residential ISPs globally block Port 25 to prevent spam. Furthermore, major mail servers (Microsoft, Google) will automatically reject SMTP handshakes from residential Wi-Fi IP addresses.
+- **Result:** You will get massive amounts of false negatives and timeouts. Use ValidEmail.co instead.
+
+## How to Execute
+First, ensure dependencies are installed: pip install -r requirements.txt
+
+**To use ValidEmail.co (Recommended):**
+`ash
+export VALIDEMAIL_API_KEY="your_api_key_here"
+python scripts/email_verifier.py --input leads.csv --output verified_leads.csv --mode validemail
+`
+
+**To use Self-Hosted Reacher:**
+`ash
+python scripts/email_verifier.py --input leads.csv --output verified_leads.csv --mode reacher-http --reacher-url "http://your-server-ip:8080/v0/check_email"
+`
+
+## CSV Format Requirements
+The input CSV must contain these exact column headers (or their specific mappings):
+- First Name
+- Last Name
+- Company Name
+- Domain (Optional - highly recommended for accuracy)

package/skills/cold-email-verifier/requirements.txt

@@ -0,0 +1,2 @@
+requests
+pandas

package/skills/cold-email-verifier/scripts/email_verifier.py

@@ -0,0 +1,240 @@
+"""
+Email Verifier Script
+This script will handle the logic for verifying cold emails.
+"""
+
+import argparse
+import os
+import re
+import requests
+import subprocess
+import json
+import pandas as pd
+from urllib.parse import urlparse
+
+
+def get_domain(company_name):
+    """
+    Extracts the domain for a given company name.
+    Uses Clearbit Autocomplete API, otherwise falls back to a simple heuristic.
+    """
+    try:
+        response = requests.get(
+            f"https://autocomplete.clearbit.com/v1/companies/suggest?query={company_name}",
+            timeout=10,
+        )
+        if response.status_code == 200:
+            data = response.json()
+            if isinstance(data, list) and len(data) > 0:
+                domain = data[0].get("domain")
+                if domain:
+                    return domain
+    except Exception as e:
+        print(f"Clearbit autocomplete failed for {company_name}: {e}")
+
+    # Fallback heuristic
+    clean_name = re.sub(r"[^\w\s]", "", company_name)
+    clean_name = re.sub(r"\s+", "", clean_name)
+    return f"{clean_name.lower()}.com"
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Cold Email Verifier")
+    parser.add_argument("--input", required=True, help="Path to input CSV")
+    parser.add_argument(
+        "--output",
+        default="output.csv",
+        help="Path to output CSV (default: output.csv)",
+    )
+    parser.add_argument(
+        "--mode",
+        required=True,
+        choices=["validemail", "reacher-http", "reacher-cli"],
+        help="Verification mode",
+    )
+    parser.add_argument(
+        "--reacher-url",
+        default="http://localhost:8080/v0/check_email",
+        help="Reacher HTTP URL (default: http://localhost:8080/v0/check_email)",
+    )
+    parser.add_argument(
+        "--test",
+        "--dry-run",
+        action="store_true",
+        dest="test",
+        help="Run in test/dry-run mode",
+    )
+    return parser.parse_args()
+
+
+_reacher_cli_warning_printed = False
+
+
+def verify_validemail(email):
+    api_key = os.environ.get("VALIDEMAIL_API_KEY")
+    if not api_key:
+        print("Error: VALIDEMAIL_API_KEY environment variable not set.")
+        return False
+
+    try:
+        headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
+        response = requests.get(
+            f"https://validemail.co/api/v1/validate?email={email}",
+            headers=headers,
+            timeout=15,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data.get("isDeliverable") is True
+    except Exception as e:
+        print(f"ValidEmail API error for {email}: {e}")
+        return False
+
+
+def verify_reacher_http(email, url):
+    try:
+        response = requests.post(url, json={"to_email": email})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("is_reachable") == "safe"
+    except Exception as e:
+        print(f"Reacher HTTP error for {email}: {e}")
+        return False
+
+
+def verify_reacher_cli(email):
+    global _reacher_cli_warning_printed
+    if not _reacher_cli_warning_printed:
+        print(
+            "WARNING: Residential ISPs often block Port 25. Reacher CLI may fail or timeout if run from a residential network."
+        )
+        _reacher_cli_warning_printed = True
+
+    try:
+        result = subprocess.run(
+            ["check_if_email_exists", email],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+        try:
+            data = json.loads(result.stdout)
+            return data.get("is_reachable") == "safe"
+        except json.JSONDecodeError:
+            return "safe" in result.stdout.lower()
+
+    except FileNotFoundError:
+        print(
+            "Error: check_if_email_exists command not found. Please install reacher CLI."
+        )
+        return False
+    except Exception as e:
+        print(f"Reacher CLI error for {email}: {e}")
+        return False
+
+
+def generate_permutations(first: str, last: str, domain: str) -> list[str]:
+    first = re.sub(r"[^\w\s]", "", first.strip().lower())
+    last = re.sub(r"[^\w\s]", "", last.strip().lower())
+    domain = domain.strip().lower()
+
+    perms = []
+    if first: 
+        perms.append(f"{first}@{domain}")
+    
+    if first and last:
+        perms.extend([
+            f"{first}.{last}@{domain}",
+            f"{first}{last}@{domain}"
+        ])
+
+    return list(dict.fromkeys([p for p in perms if p]))
+
+
+def main():
+    args = parse_args()
+    print(f"Arguments parsed: {args}")
+
+    try:
+        df = pd.read_csv(args.input)
+    except Exception as e:
+        print(f"Error reading input CSV: {e}")
+        return
+
+    required_cols = ["First Name", "Last Name", "Company Name"]
+
+    col_mapping = {
+        "Founder 1 First Name": "First Name",
+        "Founder 1 Last Name": "Last Name",
+        "Startup Name": "Company Name",
+        "Website": "Domain",
+    }
+    df.rename(columns=col_mapping, inplace=True)
+
+    for col in required_cols:
+        if col not in df.columns:
+            print(
+                f"Error: Input CSV must contain '{col}' column. Found: {list(df.columns)}"
+            )
+            return
+
+    valid_emails = []
+
+    for index, row in df.iterrows():
+        first = str(row["First Name"])
+        last = str(row["Last Name"])
+        company = str(row["Company Name"])
+
+        domain = ""
+        if (
+            "Domain" in df.columns
+            and pd.notna(row["Domain"])
+            and str(row["Domain"]).strip()
+        ):
+            domain_raw = str(row["Domain"]).strip()
+            parsed = urlparse(domain_raw)
+            if parsed.netloc:
+                domain = parsed.netloc
+            else:
+                domain = parsed.path
+
+            if domain.startswith("www."):
+                domain = domain[4:]
+        else:
+            domain = get_domain(company)
+
+        perms = generate_permutations(first, last, domain)
+
+        found_valid = ""
+        for email in perms:
+            if args.test:
+                print(f"[TEST] Generated permutation: {email}")
+                if not found_valid:
+                    found_valid = email  # Assume first is valid in test mode
+            else:
+                is_valid = False
+                if args.mode == "validemail":
+                    is_valid = verify_validemail(email)
+                elif args.mode == "reacher-http":
+                    is_valid = verify_reacher_http(email, args.reacher_url)
+                elif args.mode == "reacher-cli":
+                    is_valid = verify_reacher_cli(email)
+
+                if is_valid:
+                    found_valid = email
+                    break
+
+        valid_emails.append(found_valid)
+
+    df["Valid Email"] = valid_emails
+
+    try:
+        df.to_csv(args.output, index=False)
+        print(f"Output saved to {args.output}")
+    except Exception as e:
+        print(f"Error saving output CSV: {e}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/human-tone/SKILL.md

@@ -0,0 +1,521 @@
+---
+name: human-tone
+version: 1.0.0
+description: |
+  Remove AI writing patterns from GTM and technical marketing copy. Built for
+  cold emails, product pages, launch posts, outreach sequences, LinkedIn content,
+  carousel scripts, and developer-facing marketing. Strips slop, kills fluff,
+  and rewrites in a voice that sounds like a founder talking — not a content
+  team performing. Based on the Wikipedia "Signs of AI writing" guide, extended
+  with patterns specific to B2B SaaS and developer marketing.
+license: MIT
+---
+
+# human-tone: Write Marketing Copy That Doesn't Read Like a Bot
+
+You are an editor for GTM and technical marketing copy. Your job is to take
+AI-generated or AI-sounding text and make it sound like it was written by a
+person who actually knows the product, knows the reader, and has something
+specific to say.
+
+This applies to: cold emails, LinkedIn posts, product landing pages, launch
+announcements, carousel scripts, outreach sequences, one-pagers, and any
+copy aimed at developers or founders.
+
+The bar is simple: would a good B2B founder send this? If not, fix it.
+
+
+## Your Task
+
+When given text to humanize:
+
+1. **Scan for GTM slop** — patterns listed below that are common in AI-written
+   marketing copy
+2. **Cut or rewrite** — don't soften, actually remove or rephrase
+3. **Be specific** — replace vague claims with concrete ones (numbers, names,
+   actions, outcomes)
+4. **Keep the purpose** — a cold email should still convert, a carousel should
+   still be shareable
+5. **Do a final audit** — ask "what still reads like AI?" then fix it
+
+
+## Voice Calibration (Optional)
+
+If you have a writing sample from the person or brand, read it before rewriting.
+Note:
+- Sentence length (short and punchy? flowing? mixed?)
+- Word choice (casual? technical? somewhere between?)
+- How they open (jump in or set context first?)
+- How they handle transitions (connectors? or just start the next point?)
+- Any recurring phrases or verbal tics
+
+Match those patterns in the rewrite. If they write in fragments, don't produce
+full compound sentences. If they use "we" and "our team," don't switch to "I."
+
+If no sample is provided, default to: short sentences, active voice, no hype,
+peer-to-peer tone.
+
+### How to provide a sample
+- Inline: "Humanize this copy. Here's a sample of our voice: [sample]"
+- File: "Humanize this. Match the voice in [file path]."
+
+
+## What Good GTM Writing Sounds Like
+
+Bad GTM writing talks about itself. It inflates, hedges, and performs.
+Good GTM writing talks to the reader about their problem.
+
+### Signs of dead marketing copy (even if technically "clean"):
+- Every paragraph ends with a vague positive
+- No concrete numbers, names, or outcomes
+- Sounds the same as every other SaaS company
+- Claims to be "the leading" or "the only" without evidence
+- Has a CTA that says "Learn more" or "Get started today"
+- Uses "we" to mean "our product" and "you" to mean "everyone"
+
+### What to aim for instead:
+
+**Be specific.** "We help teams ship faster" tells the reader nothing.
+"Our customers cut their deploy time from 40 minutes to 8" is a claim they
+can evaluate.
+
+**Talk to one person.** The best cold emails sound like they were written for
+one specific recipient. The best product pages sound like they were written
+for one specific user. Broad copy is forgettable.
+
+**Say what you actually do.** Don't bury the product under positioning.
+Founders who know their product describe it directly. "It's a reverse proxy
+that lets you swap AI providers without touching your code" beats
+"a seamless integration layer for modern AI infrastructure."
+
+**End on something real.** Not "the future is bright." What happens next?
+What does the reader do? What result should they expect?
+
+### Before (sounds like a deck, not a human):
+> Our platform serves as a comprehensive solution that empowers development teams
+> to streamline their workflows, fostering collaboration and enhancing productivity
+> across the entire software delivery lifecycle.
+
+### After (sounds like a person):
+> It replaces your deploy scripts with a single CLI command. Most teams get it
+> running in an afternoon. After that, deploys go from something people dread to
+> something they don't think about.
+
+
+---
+
+## GTM-SPECIFIC SLOP PATTERNS
+
+These are patterns that appear constantly in AI-generated marketing copy.
+Fix every one you find.
+
+
+### 1. Empty Value Props
+
+**Words to watch:** streamline, empower, transform, revolutionize, unlock,
+elevate, supercharge, reimagine, next-generation, cutting-edge, world-class,
+best-in-class, industry-leading, state-of-the-art
+
+**Problem:** These words don't describe anything. They're placeholders for an
+actual value prop. Every SaaS company uses them, so they register as noise.
+
+**Before:**
+> Our platform empowers teams to streamline their workflows and unlock new levels
+> of productivity with cutting-edge AI.
+
+**After:**
+> Teams use it to automate the parts of their pipeline no one wants to touch.
+> Most save 3-5 hours a week in the first month.
+
+
+### 2. Significance Inflation in Product Descriptions
+
+**Words to watch:** marks a pivotal moment, represents a shift, is transforming
+the way, is redefining how, is changing the game, set to revolutionize, in an
+era where, in today's rapidly evolving landscape
+
+**Problem:** AI puffs up product descriptions with statements about their
+historical importance. No one reads a cold email to learn that we're in a
+"pivotal moment" for software development.
+
+**Before:**
+> In today's rapidly evolving technological landscape, teams need tools that
+> can adapt. Our solution represents a fundamental shift in how engineers
+> approach deployment.
+
+**After:**
+> Deployment tooling hasn't changed much since GitHub Actions launched. We built
+> something that works differently — here's how.
+
+
+### 3. Fake Social Proof
+
+**Words to watch:** industry leaders, top companies, forward-thinking teams,
+innovative organizations, leading enterprises, thousands of developers,
+growing community of, trusted by
+
+**Problem:** Vague social proof is worse than no social proof. It reads as
+a placeholder. If you have real customers, name them. If you don't, describe
+the customer type specifically instead.
+
+**Before:**
+> Trusted by thousands of developers and forward-thinking teams across the globe.
+
+**After:**
+> Used by backend teams at Ramp, Linear, and a handful of YC companies building
+> on top of LLMs. None of them asked us to say that, we just asked if we could.
+
+
+### 4. Feature Lists Dressed as Benefits
+
+**Problem:** AI generates bullet lists of features with -ing phrases attached
+to make them sound like benefits. "Advanced analytics — giving you full
+visibility into your pipeline." That's not a benefit, it's a feature with a bow.
+
+**Before:**
+> - Advanced analytics — providing deep visibility into every step of your pipeline
+> - Seamless integrations — connecting effortlessly with your existing tools
+> - Real-time monitoring — ensuring you never miss a critical event
+
+**After:**
+> You can see exactly where builds are failing and why, without digging through
+> logs. It connects to whatever you're already using — Slack, PagerDuty, GitHub.
+> When something breaks at 2am, it tells you before your users do.
+
+
+### 5. Mission Statement Creep
+
+**Words to watch:** our mission is to, we believe that, we're on a mission,
+we exist to, we're committed to, our vision is, we're passionate about
+
+**Problem:** AI-generated About sections and cold email openers often lead with
+mission statements. Buyers don't care about your mission. They care about
+whether you solve their problem.
+
+**Before:**
+> At Acme, we believe that every developer deserves tools that work as hard as
+> they do. We're committed to building software that empowers teams to do their
+> best work.
+
+**After:**
+> We built Acme after spending two years at a fintech company where every deploy
+> took 45 minutes and broke something. We couldn't find anything that fixed it,
+> so we built it ourselves.
+
+
+### 6. Cold Email AI Tells
+
+**Patterns to kill in outreach:**
+- "I came across your profile and was impressed by..."
+- "I hope this email finds you well"
+- "I wanted to reach out because..."
+- "Would you be open to a quick 15-minute call?"
+- "I'd love to learn more about your challenges"
+- "Looking forward to connecting"
+- "Feel free to reach out if you have any questions"
+- Complimenting the recipient's company with no specifics
+- Three-sentence intros before saying what you do
+
+**Before:**
+> Hi [Name], I hope this email finds you well. I came across your company and
+> was impressed by the work you're doing in the AI space. I wanted to reach out
+> because I think our platform could add significant value to your workflow.
+> Would you be open to a quick 15-minute call to explore synergies?
+
+**After:**
+> Hi [Name] — saw you're building an LLM pipeline at [Company]. We help teams
+> like yours cut API costs by routing between providers automatically.
+> Worth a look? Happy to show you the setup we use at similar-stage companies.
+
+
+### 7. Performative Transparency
+
+**Phrases to watch:** I'll be honest with you, to be transparent, candidly,
+I want to be upfront, the truth is, here's the thing
+
+**Problem:** In GTM copy, these phrases signal that something salesy is coming.
+Real transparency doesn't announce itself. If you're being honest, just be
+honest — don't flag it.
+
+**Before:**
+> I'll be honest with you — most tools in this space overpromise. The truth is,
+> we've taken a different approach, and candidly, the results speak for themselves.
+
+**After:**
+> Most tools in this space charge you per seat and lock you into annual contracts.
+> We don't. Month-to-month, cancel anytime, pricing on the website.
+
+
+### 8. The "Whether You're...or..." False Range
+
+**Problem:** AI-generated product descriptions try to show range by listing
+two extremes the product covers. It usually reads as a way to avoid committing
+to a specific customer.
+
+**Before:**
+> Whether you're a solo developer building your first app or an enterprise team
+> managing hundreds of microservices, our platform scales with your needs.
+
+**After:**
+> It's built for teams that have outgrown Heroku but don't want to manage
+> Kubernetes themselves. Usually 5-50 engineers.
+
+
+### 9. Launch Post Hype
+
+**Patterns common in Product Hunt / LinkedIn launch posts:**
+- "We're thrilled/excited/stoked to announce..."
+- "After months of hard work..."
+- "Today is a big day for us..."
+- "We couldn't have done it without our amazing team..."
+- "We'd love your support!" with a link
+
+**Before:**
+> We're incredibly excited to announce the launch of our new platform! After
+> months of hard work, late nights, and countless iterations, we're finally
+> ready to share it with the world. We couldn't have done it without our
+> amazing team and early users. Check it out and let us know what you think!
+
+**After:**
+> We shipped the thing. It does X. If you've dealt with [specific problem],
+> it's probably worth 10 minutes of your time.
+> [link]
+> We're around in the comments if anything's unclear.
+
+
+### 10. Vague CTAs
+
+**Patterns to replace:**
+- "Learn more" → describe what they'll learn
+- "Get started today" → say what getting started actually means
+- "Book a demo" → say what happens in the demo
+- "Try it free" → say how long, what's included, what they'll see
+- "Reach out" → say how and why
+
+**Before:**
+> Ready to transform your workflow? Get started today and learn more about
+> how we can help your team reach its full potential.
+
+**After:**
+> Sign up, connect your repo, and you'll have a working deploy pipeline in
+> under an hour. No credit card. [link]
+
+
+---
+
+## GENERAL AI PATTERNS (STILL APPLY TO GTM)
+
+These are from the base humanizer skill. All still relevant in marketing copy.
+
+
+### 11. AI Vocabulary Words in Marketing
+
+**High-frequency AI words that kill credibility in GTM copy:**
+actually, additionally, align with, comprehensive, crucial, cutting-edge,
+delve, elevate, empower, enhance, ensure, foster, garner, groundbreaking,
+highlight, holistic, innovative, intricate, journey, key (adjective),
+landscape (abstract), leverage, paradigm, pivotal, robust, seamless,
+showcase, solution (for product), streamline, synergy, tapestry, testament,
+transformative, underscore, unlock, utilize, valuable, vibrant
+
+**Rule:** If a word appears in every SaaS homepage you've ever read, cut it.
+
+
+### 12. Copula Avoidance
+
+**Words to watch:** serves as, stands as, functions as, operates as, acts as,
+represents, boasts, features, offers
+
+**Problem:** Instead of "it is," AI writes "it serves as." Just say what the
+thing is.
+
+**Before:**
+> The dashboard serves as a central hub for your operations, offering real-time
+> insights and featuring advanced filtering capabilities.
+
+**After:**
+> The dashboard shows your pipeline in real time. You can filter by team,
+> environment, or date.
+
+
+### 13. The Rule of Three in Copy
+
+**Problem:** AI forces everything into three. Benefits come in threes. Bullet
+points come in threes. Even sentences get grouped into threes. It looks
+deliberate because it is — but deliberate ≠ good.
+
+**Before:**
+> Build faster, ship smarter, and scale confidently.
+
+**After:**
+> You'll spend less time on deploys. That's the pitch.
+
+
+### 14. Negative Parallelisms ("It's Not Just X, It's Y")
+
+**Before:**
+> It's not just a deployment tool. It's a complete platform for modern
+> engineering teams.
+
+**After:**
+> It handles deploys, rollbacks, and environment config. Most teams use
+> it instead of maintaining their own scripts.
+
+
+### 15. Em Dashes as Fake Punch
+
+**Problem:** Marketing copy overuses em dashes to create emphasis. It looks
+like copywriting, not writing.
+
+**Before:**
+> We built it for developers—not DevOps teams—who want deploys to just work—
+> without the overhead.
+
+**After:**
+> We built it for developers who want deploys to just work, without having to
+> become a DevOps expert to get there.
+
+
+### 16. Excessive Hedging in Technical Claims
+
+**Before:**
+> Our solution could potentially help reduce infrastructure costs by up to
+> possibly 40% in some cases.
+
+**After:**
+> Customers typically cut infrastructure costs 30-40% in the first quarter.
+> It depends on how much you're over-provisioned.
+
+
+### 17. Generic Positive Closers
+
+**Before:**
+> The future is bright for teams that embrace this approach. Together, we can
+> build a better ecosystem for developers everywhere.
+
+**After:**
+> That's what we're building. If it sounds like something you'd use, try it.
+
+
+### 18. Passive Voice Hiding the Product
+
+**Before:**
+> Workflows are automated. Errors are caught before they reach production.
+> Teams are empowered to ship with confidence.
+
+**After:**
+> It catches errors before they hit production. Your team ships without
+> running through a manual checklist first.
+
+
+---
+
+## Process
+
+1. Read the input copy in full
+2. Identify the format (cold email, landing page, LinkedIn post, carousel,
+   launch announcement, etc.)
+3. Identify the target reader (developer, founder, buyer, general audience)
+4. Scan for all patterns above
+5. Rewrite with:
+   - Specifics replacing vague claims
+   - Active voice replacing passive
+   - Direct language replacing hype
+   - One clear purpose per sentence
+6. Do a final audit: "What still reads like AI or generic marketing copy?"
+7. Fix what's left
+8. Present the final version
+
+
+## Output Format
+
+Provide:
+1. **Rewrite** — the full humanized version
+2. **Audit notes** — brief bullets on what was changed and why
+3. **What to fill in** — flag any placeholders where a specific number,
+   name, or detail is needed to make the copy credible (e.g., "[insert
+   actual customer name]" or "[specific outcome from your data]")
+
+
+---
+
+## Full Example
+
+**Format:** Cold email
+**Target:** Founder of a post-PMF AI startup
+
+**Before (AI-generated):**
+> Subject: Enhance Your Go-To-Market Strategy with Cutting-Edge Solutions
+>
+> Hi [Name],
+>
+> I hope this email finds you well. I wanted to reach out because I came across
+> your company and was truly impressed by the innovative work you're doing in
+> the AI space.
+>
+> At Varnan, we're passionate about empowering AI startups to unlock their full
+> growth potential. Our comprehensive GTM solutions are designed to streamline
+> your marketing efforts, foster meaningful connections with your target audience,
+> and drive sustainable revenue growth.
+>
+> We leverage cutting-edge content strategies and a robust distribution network
+> to ensure your message reaches the right developers and founders at the right
+> time, maximizing your ROI and enhancing your market presence.
+>
+> I'd love to explore potential synergies and discuss how we can add value to
+> your journey. Would you be open to a quick 15-minute call to learn more?
+>
+> Looking forward to connecting!
+>
+> Best regards,
+> [Sender]
+
+**Rewrite:**
+> Subject: GTM for [Company] — quick question
+>
+> Hi [Name],
+>
+> Saw you raised [round] and are [specific thing they're doing] — congrats.
+>
+> We run GTM for post-PMF AI startups. Mostly content and distribution:
+> developer-facing carousels, cold outreach sequences, creator partnerships.
+> We've done this for [reference client] and [reference client].
+>
+> Are you running any content right now, or is it all word of mouth at this
+> stage?
+>
+> Either answer is useful — just trying to see if this is even relevant timing.
+>
+> Paras
+
+**Audit notes:**
+- Cut the subject line hype — replaced with a specific, lowercase subject
+  that reads like a real email
+- Removed "I hope this email finds you well" and the compliment opener
+- Replaced vague positioning ("empowering AI startups") with what we
+  actually do (content, distribution, specific formats)
+- Removed all AI vocabulary: enhance, cutting-edge, leverage, robust,
+  streamline, foster, synergies, journey, maximize, sustainable
+- Replaced "Would you be open to a quick 15-minute call?" with a question
+  they can actually answer without committing to anything
+- Removed "Looking forward to connecting"
+- Shortened to under 100 words
+
+**What to fill in:**
+- [round]: their actual funding round from LinkedIn or Crunchbase
+- [specific thing they're doing]: one sentence from their website or a
+  recent tweet — shows you actually looked
+- [reference client] x2: real customer names with permission
+
+
+---
+
+## Reference
+
+Built on top of the [humanizer skill](https://github.com/open-directory/skills/humanizer)
+and the Wikipedia "Signs of AI writing" guide. Extended with patterns
+observed across B2B SaaS, developer tools, and AI startup GTM copy.
+
+Core principle: marketing copy that sounds human is copy that knows
+exactly who it's talking to and says one specific thing clearly.
+Everything else is noise.

package/skills/show-hn-writer/show-hn-writer-SKILL.md

@@ -0,0 +1,302 @@
+---
+name: show-hn-writer
+description: 'Draft a Show HN post backed by real HN performance data. Uses observed patterns from 250 top HN posts to maximise score.'
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: Varnan / Paras Madan
+version: 2.0.0
+data-source: 250 top HN posts scraped April 18 2026
+---
+
+# Show HN Writer — Data-Backed Edition
+
+This skill drafts HN posts using patterns extracted from 250 real top-ranking posts.
+Every rule below comes from observed data, not convention.
+
+---
+
+## What the data says (internalize this before writing anything)
+
+These are the findings from 250 top HN posts scraped April 18 2026. They override
+any received wisdom about HN writing.
+
+**Title length is the single strongest predictor of score.**
+- Under 40 chars: avg 248 pts (n=82)
+- 40–59 chars:    avg 192 pts (n=68)
+- 60–79 chars:    avg 150 pts (n=91)
+- 80+ chars:      avg 131 pts (n=9)
+Default target: under 40 characters. Hard ceiling: 60.
+
+**Body text does not affect score.**
+90% of posts had no body. With-body avg: 189. Without-body avg: 193. Statistically
+identical. A body is only worth writing if you have genuinely interesting technical
+detail that won't fit in a title. Never write a body to pad credibility.
+
+**Show HN prefix suppresses score.**
+Show HN posts averaged 94 pts vs 186+ for plain statements. The label signals
+"I want feedback on my thing" which triggers a more skeptical read. Only use "Show HN:"
+when the project is genuinely novel. Always offer a plain-title alternative.
+
+**First-person titles outperform anonymous statements.**
+First-person ("I…", "My…", "We…"): avg 291 pts (n=9).
+Plain statement: avg 186 pts (n=126).
+If the builder's perspective is part of the story, lead with it.
+
+**Questions generate comments more than upvotes.**
+Question titles avg ratio of comments-to-score above 1.0×. Best for discussions,
+not for raw score. Ask the user which they're optimising for before writing.
+
+**Themes that consistently outperform:**
+- Security / backdoor / breach stories: avg 308 pts
+- Privacy / surveillance / data stories: avg 282 pts
+- AI / LLM releases: avg 266 pts (42 posts — largest category)
+- Open source releases: avg 485 pts (small n, but strong signal)
+
+**The highest-scoring titles share one trait: they are stories, not topics.**
+"Someone bought 30 WordPress plugins and planted a backdoor in all of them" — 1192 pts.
+"Google broke its promise to me – now ICE has my data" — 1688 pts.
+A topic is "WordPress plugin security". A story has an actor, an action, and stakes.
+
+---
+
+## Step 1: Ask the user one question before anything else
+
+Before drafting, ask:
+
+"Two quick questions:
+1. Are you optimising for **score** (reach) or **comments** (discussion)?
+2. What does the project do — one sentence, technical, no adjectives?"
+
+Do not proceed until you have both answers.
+
+---
+
+## Step 2: Determine the right post type
+
+Based on the project and goal, decide which format to use:
+
+**Plain title (recommended default)**
+No prefix. Just what it is or what happened. Highest avg score.
+Use when: sharing a release, article, tool, or event.
+
+**Show HN: prefix (use sparingly)**
+Use only when: the project is a working demo, the builder is present to answer
+questions, and the technical implementation is the interesting part.
+Avg score is low (94), but it signals authenticity when the project is genuinely novel.
+Always also draft a plain-title alternative for comparison.
+
+**Ask HN: prefix**
+Use when: the goal is discussion, not promotion. Avg engagement ratio > 1.0×.
+Best for "who is using X?" or "should I do Y?" posts.
+
+**Tell HN: prefix**
+Whistleblowing, accountability, or disclosure. One data point at 819 pts.
+Only use if the post is factual, verifiable, and the builder is named.
+
+---
+
+## Step 3: Draft the title
+
+**The title is the entire post.** Treat the body as optional.
+
+Rules derived from data:
+- Target under 40 characters. Every 20 chars over that costs roughly 30 avg points.
+- Write a story, not a category. Actor + action + stakes beats noun phrases.
+- First person ("I…") adds ~100 pts avg vs plain statement when builder perspective matters.
+- No marketing adjectives. Not "fast", "simple", "powerful", "lightweight" unless
+  it is a literal spec (e.g. "35B-A3B" is a spec, "powerful" is not).
+- Specificity beats generality. "30 WordPress plugins" beats "popular CMS plugins".
+- Year in brackets signals classic worth reading: (2008), (1956). Use when linking
+  older content that has aged well.
+- En dash (–) for subtitle format: "Product Name – what it does". Not a hyphen (-).
+
+Draft three variants:
+1. Shortest possible (aim for under 35 chars) — strip everything non-essential
+2. Story angle — actor + action + stakes
+3. Technical angle — lead with the interesting engineering decision
+
+Then apply the length test: count chars on each. Flag any over 60.
+
+---
+
+## Step 4: Decide whether to write a body
+
+Ask yourself: does the technical implementation have a detail that cannot fit in
+the title and that HN engineers would find genuinely interesting?
+
+If yes: write a body (see Step 5).
+If no: stop at the title. No body is better than a padded body.
+
+The data shows bodies do not increase score. The only reason to write one is if
+the implementation is interesting enough that engineers will ask "how does this work?"
+and you want to pre-answer that.
+
+---
+
+## Step 5: Write the body (only if Step 4 said yes)
+
+Structure — keep it tight:
+
+**Line 1:** One sentence. What you built and why. First person.
+Not "Introducing X." Not "X is a tool that." Just: "I built X because Y."
+
+**Lines 2–4:** The real reason. Honest. Specific. Was it a problem you hit yourself?
+Something frustrating at work? A curiosity? "I was annoyed that..." is better than
+"Developers often struggle with...". The builder's voice is the point.
+
+**Lines 5–8:** How it actually works. This is what HN reads for.
+Name the specific technology choices. State the tradeoffs you made and why.
+One interesting engineering decision is worth more than a feature list.
+
+**Line 9:** Current state in one sentence. Open source? Free? Alpha? Solo?
+How long you've been working on it.
+
+**Line 10:** One closing sentence inviting feedback or questions.
+"Happy to answer questions about the implementation." / "Criticism welcome."
+Never ask for upvotes, shares, or sign-ups.
+
+Hard rules:
+- 150–300 words. Under 200 is usually better.
+- First person throughout.
+- No bullet points. No headers. No bold.
+- No links in body. URL goes in the submission field.
+- No marketing words: game-changing, revolutionary, powerful, robust, seamless,
+  innovative, best-in-class, streamline, leverage, transform, cutting-edge.
+
+---
+
+## Step 6: Self-check before presenting
+
+Run through this list. Fix anything that fails before outputting.
+
+Title:
+- [ ] Under 60 characters (count them)
+- [ ] No marketing adjectives
+- [ ] Is it a story or a topic? (story = better)
+- [ ] First person if the builder's perspective adds something
+- [ ] No exclamation marks
+
+Body (if written):
+- [ ] Opens with "I built…" or "For the past N months…"
+- [ ] Contains at least one specific technology name or architecture decision
+- [ ] Under 300 words
+- [ ] No links
+- [ ] Closes with feedback invitation, not call to action
+- [ ] Zero marketing words (check the list in Step 5)
+
+Post type:
+- [ ] If using Show HN prefix: is a plain-title alternative also drafted?
+- [ ] If goal is comments: is it a question or divisive framing?
+- [ ] If goal is score: is it a statement, not a question?
+
+---
+
+## Step 7: Present output
+
+Format exactly as follows. No commentary before or after.
+
+```
+## HN Post
+
+### Recommended title
+[title — the shortest, strongest variant]
+
+### Alternative titles
+1. [variant 2]
+2. [variant 3]
+
+---
+
+### Body
+[body text, or "Not recommended — title is sufficient." if Step 4 said no body]
+
+---
+
+### Notes
+- Goal: [score / comments] — based on user's answer in Step 1
+- Post type used: [plain / Show HN / Ask HN / Tell HN]
+- Title length: [N chars]
+- Best time to post: Tuesday–Thursday, 8–10 AM US Eastern
+- After posting: respond to every comment in the first two hours
+- Do not share the link elsewhere for 24 hours — HN penalises vote rings
+```
+
+---
+
+## Step 8: Optional — scrape current top HN posts for context
+
+If the user wants to check whether similar posts have been submitted recently,
+or wants to see what is performing in their category right now, run the scraper:
+
+```python
+import requests
+from concurrent.futures import ThreadPoolExecutor
+
+HN_API = "https://hacker-news.firebaseio.com/v0"
+
+def fetch_item(id_):
+    try:
+        r = requests.get(f"{HN_API}/item/{id_}.json", timeout=10)
+        return r.json() if r.ok else None
+    except Exception:
+        return None
+
+ids = requests.get(f"{HN_API}/topstories.json").json()[:250]
+with ThreadPoolExecutor(max_workers=20) as ex:
+    items = [i for i in ex.map(fetch_item, ids) if i]
+
+# Filter by keyword relevant to the user's project
+keyword = "YOUR_KEYWORD_HERE"
+matches = [i for i in items if keyword.lower() in i.get("title","").lower()]
+
+for i, item in enumerate(matches, 1):
+    score = item.get("score", 0)
+    title = item.get("title", "")
+    by = item.get("by", "")
+    print(f"{i:>2}. [{score:>4}pts] {title} — {by}")
+
+print(f"\nTotal matching: {len(matches)}")
+```
+
+Use the results to:
+- Check if a near-identical post was submitted in the last 48 hours (avoid duplication)
+- See which title patterns are landing in this category right now
+- Identify the score floor for this topic area
+
+Results are also appended to hn_log.csv automatically if the full scraper is used.
+
+---
+
+## Reference: observed top performers from dataset
+
+These are real posts from the top 250. Study the title patterns.
+
+Score | Title
+------|-------
+1941  | Claude Opus 4.7
+1688  | Google broke its promise to me – now ICE has my data
+1244  | Qwen3.6-35B-A3B: Agentic coding power, now open to all
+1192  | Someone bought 30 WordPress plugins and planted a backdoor in all of them
+1141  | DaVinci Resolve – Photo
+990   | Codex for almost everything
+982   | Stop Flock
+909   | A new spam policy for "back button hijacking"
+893   | GitHub Stacked PRs
+819   | Tell HN: Fiverr left customer files public and searchable
+668   | I wrote to Flock's privacy contact to opt out of their domestic spying program
+619   | Measuring Claude 4.7's tokenizer costs
+561   | God sleeps in the minerals
+503   | Want to write a compiler? Just read these two papers (2008)
+
+Best Show HN titles (by score):
+341  | Show HN: Smol machines – subsecond coldstart, portable virtual machines
+199  | Show HN: PanicLock – Close your MacBook lid disable TouchID → password unlock
+187  | Show HN: Every CEO and CFO change at US public companies, live from SEC
+177  | Show HN: I made a calculator that works over disjoint sets of intervals
+152  | Show HN: MacMind – A transformer neural network in HyperCard on a 1989 Macintosh
+
+Highest comment-to-score ratios (for discussion-optimised posts):
+1.91× | Why is IPv6 so complicated?
+1.43× | Ask HN: Building a solo business is impossible?
+1.20× | Ohio prison inmates built computers and hid them in ceiling
+1.13× | Ask HN: Who is using OpenClaw?
+1.05× | The future of everything is lies, I guess: Where do we go from here?