@opendirectory.dev/skills 0.1.42 → 0.1.44

package/skills/competitor-pr-finder/scripts/research.py

@@ -0,0 +1,292 @@
+"""
+research.py -- two-phase Tavily data collector for competitor-pr-finder.
+
+Phase 1 (discover): finds competitor candidates from product analysis context.
+Phase 2 (pr-research): runs three-track PR search per confirmed competitor.
+
+Usage:
+  # Phase 1
+  python3 scripts/research.py \
+      --phase discover \
+      --product-analysis /tmp/cprf-product-analysis.json \
+      --tavily-key "$TAVILY_API_KEY" \
+      --output /tmp/cprf-competitors-raw.json
+
+  # Phase 2
+  python3 scripts/research.py \
+      --phase pr-research \
+      --competitors /tmp/cprf-competitors-confirmed.json \
+      --product-analysis /tmp/cprf-product-analysis.json \
+      --tavily-key "$TAVILY_API_KEY" \
+      --output /tmp/cprf-pr-raw.json
+"""
+
+import argparse
+import json
+import os
+import ssl
+import sys
+import urllib.request
+from datetime import date
+
+_ssl_ctx = ssl._create_unverified_context()
+
+quiet = False
+
+
+def log(msg):
+    if not quiet:
+        print(msg, file=sys.stderr)
+
+
+def fetch_json(url, payload, timeout=25):
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "User-Agent": "competitor-pr-finder/1.0",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=timeout, context=_ssl_ctx) as resp:
+        return json.loads(resp.read())
+
+
+def tavily_search(query, key, depth="advanced", max_results=7):
+    log(f"  Tavily [{depth}] {query[:80]}")
+    try:
+        result = fetch_json(
+            "https://api.tavily.com/search",
+            {
+                "api_key": key,
+                "query": query,
+                "search_depth": depth,
+                "max_results": max_results,
+            },
+        )
+        return {
+            "answer": result.get("answer", ""),
+            "results": result.get("results", []),
+        }
+    except Exception as e:
+        log(f"  ERROR: {e}")
+        return {"answer": "", "results": [], "error": str(e)}
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: competitor discovery
+# ---------------------------------------------------------------------------
+
+def run_discover(product_analysis, tavily_key):
+    name = product_analysis.get("product_name", "")
+    l2 = product_analysis.get("industry_taxonomy", {}).get("l2", "")
+    l3 = product_analysis.get("industry_taxonomy", {}).get("l3", "")
+
+    log(f"\nPhase 1: competitor discovery for '{name}'")
+    log(f"  taxonomy: {l2} > {l3}")
+
+    queries = [
+        f'"{name}" competitors alternatives {l3}',
+        f"{l2} {l3} startups companies funded 2022 2023 2024",
+    ]
+
+    competitor_searches = []
+    for q in queries:
+        result = tavily_search(q, tavily_key, depth="advanced", max_results=8)
+        competitor_searches.append(
+            {
+                "query": q,
+                "answer": result.get("answer", ""),
+                "results": [
+                    {
+                        "title": r.get("title", ""),
+                        "url": r.get("url", ""),
+                        "content": r.get("content", "")[:500],
+                    }
+                    for r in result.get("results", [])
+                ],
+            }
+        )
+        log(f"    {len(result.get('results', []))} results")
+
+    log("Phase 1 complete.")
+    return {
+        "date": str(date.today()),
+        "product_name": name,
+        "competitor_searches": competitor_searches,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Phase 2: three-track PR research
+# ---------------------------------------------------------------------------
+
+TRACK_QUERIES = {
+    "editorial": '"{competitor}" featured press coverage TechCrunch Forbes Wired article interview',
+    "podcast": '"{competitor}" founder CEO podcast interview appeared on episode',
+    "community": '"{competitor}" site:reddit.com OR site:news.ycombinator.com OR site:producthunt.com',
+}
+
+FALLBACK_QUERY = '"{competitor}" review coverage press news'
+
+
+def run_pr_research(confirmed_competitors, product_analysis, tavily_key):
+    log(f"\nPhase 2: PR research for {len(confirmed_competitors)} competitors")
+
+    results = []
+    for comp in confirmed_competitors:
+        name = comp.get("name", "")
+        url = comp.get("url", "")
+        log(f"\n  [{name}]")
+
+        comp_result = {
+            "competitor": name,
+            "url": url,
+            "tracks": {},
+        }
+
+        total_results = 0
+        for track, query_template in TRACK_QUERIES.items():
+            query = query_template.replace("{competitor}", name)
+            data = tavily_search(query, tavily_key, depth="advanced", max_results=7)
+            track_results = [
+                {
+                    "title": r.get("title", ""),
+                    "url": r.get("url", ""),
+                    "content": r.get("content", "")[:500],
+                }
+                for r in data.get("results", [])
+            ]
+            comp_result["tracks"][track] = {
+                "query": query,
+                "answer": data.get("answer", ""),
+                "results": track_results,
+            }
+            count = len(track_results)
+            total_results += count
+            log(f"    {track}: {count} results")
+
+        # Fallback if all 3 tracks returned nothing
+        if total_results == 0:
+            log(f"    WARNING: 0 results across all tracks. Running fallback search.")
+            fallback_query = FALLBACK_QUERY.replace("{competitor}", name)
+            fallback_data = tavily_search(
+                fallback_query, tavily_key, depth="advanced", max_results=7
+            )
+            comp_result["tracks"]["fallback"] = {
+                "query": fallback_query,
+                "answer": fallback_data.get("answer", ""),
+                "results": [
+                    {
+                        "title": r.get("title", ""),
+                        "url": r.get("url", ""),
+                        "content": r.get("content", "")[:500],
+                    }
+                    for r in fallback_data.get("results", [])
+                ],
+            }
+            comp_result["data_quality_flag"] = "All 3 tracks returned 0 results. Fallback search used."
+            log(f"    fallback: {len(fallback_data.get('results', []))} results")
+
+        results.append(comp_result)
+
+    log("\nPhase 2 complete.")
+    return {
+        "date": str(date.today()),
+        "competitors_researched": len(confirmed_competitors),
+        "results": results,
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    global quiet
+
+    parser = argparse.ArgumentParser(description="competitor-pr-finder research script")
+    parser.add_argument(
+        "--phase",
+        required=True,
+        choices=["discover", "pr-research"],
+        help="Which phase to run",
+    )
+    parser.add_argument(
+        "--product-analysis",
+        required=True,
+        help="Path to cprf-product-analysis.json",
+    )
+    parser.add_argument(
+        "--competitors",
+        default="",
+        help="Path to cprf-competitors-confirmed.json (Phase 2 only)",
+    )
+    parser.add_argument(
+        "--tavily-key",
+        default=os.environ.get("TAVILY_API_KEY", ""),
+        help="Tavily API key (or set TAVILY_API_KEY env var)",
+    )
+    parser.add_argument(
+        "--output",
+        required=True,
+        help="Path to write JSON output",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress progress output to stderr",
+    )
+    args = parser.parse_args()
+
+    quiet = args.quiet
+
+    if not args.tavily_key:
+        print("ERROR: Tavily API key required. Pass --tavily-key or set TAVILY_API_KEY.", file=sys.stderr)
+        sys.exit(1)
+
+    if not os.path.exists(args.product_analysis):
+        print(f"ERROR: {args.product_analysis} not found", file=sys.stderr)
+        sys.exit(1)
+
+    with open(args.product_analysis) as f:
+        product_analysis = json.load(f)
+
+    if args.phase == "discover":
+        output = run_discover(product_analysis, args.tavily_key)
+
+    elif args.phase == "pr-research":
+        if not args.competitors:
+            print("ERROR: --competitors required for pr-research phase", file=sys.stderr)
+            sys.exit(1)
+        if not os.path.exists(args.competitors):
+            print(f"ERROR: {args.competitors} not found", file=sys.stderr)
+            sys.exit(1)
+        with open(args.competitors) as f:
+            competitors_data = json.load(f)
+        confirmed = competitors_data.get("confirmed_competitors", [])
+        if not confirmed:
+            print("ERROR: no confirmed_competitors in input file", file=sys.stderr)
+            sys.exit(1)
+        output = run_pr_research(confirmed, product_analysis, args.tavily_key)
+
+    with open(args.output, "w") as f:
+        json.dump(output, f, indent=2)
+
+    log(f"\nOutput written to {args.output}")
+
+    # Print summary for SKILL.md to parse
+    if args.phase == "discover":
+        total = sum(len(s["results"]) for s in output["competitor_searches"])
+        print(f"Discover complete: {len(output['competitor_searches'])} queries, {total} total results")
+    else:
+        print(f"PR research complete: {output['competitors_researched']} competitors researched")
+        for r in output.get("results", []):
+            track_counts = {t: len(v["results"]) for t, v in r["tracks"].items()}
+            print(f"  {r['competitor']}: {track_counts}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/pricing-finder/.env.example

@@ -0,0 +1,15 @@
+# pricing-finder -- environment variables
+# All keys are OPTIONAL. The skill runs for free without any keys.
+# Install free dependencies first: pip install -r requirements.txt
+
+# Optional: Tavily API key
+# Upgrades web search quality over DuckDuckGo.
+# Get it at: https://app.tavily.com
+# Free tier: 1000 credits/month
+# TAVILY_API_KEY=your_tavily_api_key_here
+
+# Optional: Firecrawl API key
+# Upgrades pricing page fetching for JS-heavy sites.
+# Get it at: https://firecrawl.dev
+# Free tier: 500 credits/month
+# FIRECRAWL_API_KEY=your_firecrawl_api_key_here

package/skills/pricing-finder/README.md

@@ -0,0 +1,142 @@
+# pricing-finder
+
+Tell it what your product is (URL or description). It finds 5 competitors globally, fetches their actual pricing pages, and returns a complete pricing intelligence report: the dominant pricing model in your space, a benchmark price table, feature gate analysis, a competitive positioning map, and a concrete recommended pricing strategy for your product.
+
+**Zero API keys required.** Runs entirely on free pip dependencies.
+
+## Install
+
+```bash
+npx "@opendirectory.dev/skills" install pricing-finder --target claude
+```
+
+### Video Tutorial
+Watch this quick video to see how it's done:
+
+https://github.com/user-attachments/assets/ee98a1b5-ebc4-452f-bbfb-c434f2935067
+
+### Step 1: Download the skill from GitHub
+1. Copy the URL of this specific skill folder from your browser's address bar.
+2. Go to [download-directory.github.io](https://download-directory.github.io/).
+3. Paste the URL and click **Enter** to download.
+
+### Step 2: Install the Skill in Claude
+1. Open your **Claude desktop app**.
+2. Go to the sidebar on the left side and click on the **Customize** section.
+3. Click on the **Skills** tab, then click on the **+** (plus) icon button to create a new skill.
+4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
+
+> **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## Setup
+
+```bash
+# Install free Python dependencies (required)
+pip install ddgs requests beautifulsoup4 html2text
+```
+
+No API keys needed. Optionally add keys to `.env` for better quality:
+
+```bash
+cp .env.example .env
+# Uncomment TAVILY_API_KEY or FIRECRAWL_API_KEY if you have them
+```
+
+## Usage
+
+```
+Find pricing benchmarks for my startup: https://yourstartup.com
+```
+
+Or paste a description if you don't have a live URL:
+
+```
+Find pricing benchmarks. We build [what you do] for [who]. [Stage], [geography].
+```
+
+## What It Does
+
+1. Fetches your product page to understand what you're building
+2. Analyzes your product: category, differentiators, ICP
+3. Discovers 5 competitors in your space via DuckDuckGo search
+4. **Asks you to confirm the competitor list** before fetching any data
+5. Fetches each competitor's pricing page (3-tier fallback: direct fetch → Google cache → search snippet)
+6. Extracts structured pricing data: tiers, prices, limits, feature gates
+7. Analyzes patterns across all 5 competitors
+8. Maps competitive positioning and identifies underserved gaps
+9. Recommends a concrete pricing strategy for your product
+
+## Output
+
+A pricing intel report saved to `docs/pricing-intel/[product-slug]-[date].md` containing:
+
+- **Pricing Model Analysis** -- dominant model in your space (per-seat / flat-rate / usage-based / freemium) and why
+- **Price Point Benchmark Table** -- every competitor's tiers with exact prices, free tier, free trial
+- **Market ranges** -- entry tier median, mid tier median, enterprise floor
+- **Feature Gate Analysis** -- what's always free, what's always paid, what varies
+- **Competitive Positioning Map** -- who owns cheap+simple, middle market, enterprise, and where the gap is
+- **Recommended Pricing Strategy** -- model, entry price, mid price, top price, free tier decision, annual discount, what to gate behind paid
+
+## Cost
+
+**$0.00.** Entirely free using pip dependencies.
+
+Optional API upgrades:
+- Tavily API (free tier: 1000 credits/month) -- better search results
+- Firecrawl API (free tier: 500 credits/month) -- better JS-heavy page rendering
+
+## Zero-Hallucination Policy
+
+Every price in the output traces to fetched pricing page content or a search snippet. "Contact Sales" is recorded exactly -- never estimated. Fields that could not be sourced are labeled "not found in page data." Low-quality data (search snippets) is explicitly flagged so you know which competitors to verify manually.
+
+## How Pricing Page Fetching Works
+
+The script tries three methods per competitor, in order:
+
+1. **Direct fetch** (`requests` + `beautifulsoup4` + `html2text`) -- works for most pricing pages since companies make them SEO-friendly and server-rendered
+2. **Google cache** -- fallback for recently-changed pages or soft blocks
+3. **Search snippet** -- last resort; marks data quality as "low" in the output
+
+If you have a Firecrawl API key, it replaces step 1 with a fully JS-rendered fetch.
+
+## Project Structure
+
+```
+pricing-finder/
+├── SKILL.md                        -- 10-step workflow for Claude Code
+├── README.md                       -- this file
+├── .env.example                    -- optional API key template
+├── requirements.txt                -- free pip dependencies
+├── scripts/
+│   └── research.py                 -- two-phase data collector
+├── evals/
+│   └── evals.json                  -- 5 test cases
+└── references/
+    ├── pricing-models.md           -- per-seat, flat, usage, freemium definitions + signals
+    ├── extraction-guide.md         -- how to read a pricing page
+    └── positioning-guide.md        -- how to map competitors and find gaps
+```
+
+## Standalone Script Usage
+
+```bash
+# Phase 1: competitor discovery
+python3 scripts/research.py \
+    --phase discover \
+    --product-analysis /tmp/pf-product-analysis.json \
+    --output /tmp/pf-competitors-raw.json
+
+# Phase 2: fetch pricing pages
+python3 scripts/research.py \
+    --phase fetch-pricing \
+    --competitors /tmp/pf-competitors-confirmed.json \
+    --output /tmp/pf-pricing-raw.json
+
+# With optional API key upgrades
+python3 scripts/research.py \
+    --phase fetch-pricing \
+    --competitors /tmp/pf-competitors-confirmed.json \
+    --firecrawl-key "$FIRECRAWL_API_KEY" \
+    --tavily-key "$TAVILY_API_KEY" \
+    --output /tmp/pf-pricing-raw.json
+```