@opendirectory.dev/skills 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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...",
@@ -177,10 +193,10 @@
   },
   {
     "name": "show-hn-writer",
-    "description": "<img width=\"1280\" height=\"640\" alt=\"show-hn-writer\" src=\"https://github.",
+    "description": "Draft a Show HN post backed by real HN performance data. Uses observed patterns from 250 top HN posts to maximise score.",
     "tags": [],
-    "author": "Unknown",
-    "version": "0.0.1",
+    "author": "Varnan / Paras Madan",
+    "version": "2.0.0",
     "path": "skills/show-hn-writer"
   },
   {

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()