@opendirectory.dev/skills 0.1.41 → 0.1.43

package/skills/competitor-pr-finder/evals/evals.json

@@ -0,0 +1,120 @@
+[
+  {
+    "id": "eval_001",
+    "name": "B2B SaaS developer tool -- full happy path",
+    "description": "A CI/CD developer tool with Firecrawl available. Validates the full 10-step workflow: fetch, competitor discovery, user confirmation, 3-track PR research, channel tiering, journalist lookup, cold pitch drafts, and saved output.",
+    "input": {
+      "prompt": "Find my PR targets: https://buildkite.com",
+      "env": {
+        "TAVILY_API_KEY": "set",
+        "FIRECRAWL_API_KEY": "set"
+      }
+    },
+    "expected_behavior": [
+      "Fetches product page via Firecrawl",
+      "Product analysis: taxonomy maps to software > DevTools > CI/CD automation",
+      "Phase 1 discovers 5 CI/CD or DevTools competitors (e.g. CircleCI, GitHub Actions, GitLab CI, Harness, Drone)",
+      "Step 5 shows competitor list and pauses for user confirmation",
+      "Phase 2 runs 3-track search (editorial, podcast, community) for all 5 confirmed competitors = 15 searches",
+      "Step 7 pattern analysis produces tier_1_channels with at least 1 tech editorial (TechCrunch, InfoQ, The New Stack, etc.)",
+      "Step 8 journalist lookup runs for each Tier 1 editorial channel",
+      "Cold pitch drafts reference buildkite.com-specific differentiators from the fetched page",
+      "Output saved to docs/pr-intel/buildkite-[date].md",
+      "No em dashes in output",
+      "No banned buzzwords in cold pitches"
+    ],
+    "expected_output": "Full PR intel report with Tier 1 deep dives, cold pitch drafts with subject lines, Tier 2 quick hits, 3 bonus hooks, saved to docs/pr-intel/"
+  },
+  {
+    "id": "eval_002",
+    "name": "Consumer social app -- different publication set, no B2B enterprise press",
+    "description": "A consumer mobile social app. Validates that the skill maps to consumer taxonomy, finds consumer-focused competitors, and surfaces consumer press (not enterprise publications).",
+    "input": {
+      "prompt": "Find PR targets for: https://www.bereal.com",
+      "env": {
+        "TAVILY_API_KEY": "set",
+        "FIRECRAWL_API_KEY": "set"
+      }
+    },
+    "expected_behavior": [
+      "Fetches product page successfully",
+      "Taxonomy maps to consumer > social media (NOT B2B SaaS or DevTools)",
+      "Competitors are consumer social apps (Snapchat, Instagram, VSCO, Locket, etc.)",
+      "Track A editorial results come from consumer press (The Verge, Mashable, TechCrunch consumer, Wired lifestyle)",
+      "No B2B enterprise publications (e.g. VentureBeat enterprise, InfoQ, The New Stack) appear in Tier 1",
+      "Track C community results include consumer subreddits (r/technology, r/socialmedia, etc.)",
+      "Cold pitch drafts reference consumer social angles (authenticity, Gen Z, photo sharing), not enterprise ROI",
+      "At least 1 podcast found in results (tech culture or consumer tech podcast)"
+    ],
+    "expected_output": "PR intel report with consumer-focused editorial, podcast, and community channels -- no enterprise B2B publications in Tier 1"
+  },
+  {
+    "id": "eval_003",
+    "name": "Description-only input (no URL) -- skips fetch, uses description for analysis",
+    "description": "User pastes a product description with no URL. Validates that Steps 3-4 are skipped and competitor discovery uses the pasted description as the product context.",
+    "input": {
+      "prompt": "Find PR targets for my startup. We make AI-powered code review tools for enterprise engineering teams. Seed stage, US-focused.",
+      "env": {
+        "TAVILY_API_KEY": "set",
+        "FIRECRAWL_API_KEY": "not set"
+      }
+    },
+    "expected_behavior": [
+      "Detects no URL in the input",
+      "Skips Step 3: no fetch attempt is made",
+      "Skips the Firecrawl/Tavily extract path entirely",
+      "AI derives product analysis from the description: taxonomy maps to software > DevTools > code review automation",
+      "competitor discovery query uses description-derived taxonomy",
+      "Competitors are AI code review tools (CodeRabbit, Reviewpad, SonarQube, Codacy, Snyk Code, etc.)",
+      "Full 3-track PR research runs normally using discovered competitors",
+      "data_quality_flags in output includes note: 'Product analysis from user description, not live page'",
+      "Stage noted as 'Seed (stated by user)' in analysis"
+    ],
+    "expected_output": "Full PR intel using description-derived taxonomy, with data_quality_flags noting source"
+  },
+  {
+    "id": "eval_004",
+    "name": "User edits competitor list at Step 5 -- edited list used for Phase 2",
+    "description": "Validates that when the user removes a competitor and adds a custom one at the confirmation step, Phase 2 runs on the edited list, not the original discovered list.",
+    "input": {
+      "prompt": "Find PR targets: https://linear.app",
+      "user_edits_competitors_at_step_5": true,
+      "edit_description": "Remove one discovered competitor, add 'Shortcut' as custom addition",
+      "env": {
+        "TAVILY_API_KEY": "set",
+        "FIRECRAWL_API_KEY": "set"
+      }
+    },
+    "expected_behavior": [
+      "Phase 1 discovers 5 competitors and shows them",
+      "Step 5 presents the list and waits for confirmation",
+      "AI updates /tmp/cprf-competitors-confirmed.json with the EDITED list (including user-added competitor)",
+      "Phase 2 uses the edited confirmed list (not the original discovered list)",
+      "The user-added competitor ('Shortcut') appears in /tmp/cprf-competitors-confirmed.json",
+      "PR research runs for exactly the edited set",
+      "Track results for user-added competitor appear in /tmp/cprf-pr-raw.json"
+    ],
+    "expected_output": "PR intel based on the user-confirmed (edited) competitor list, not the originally discovered candidates"
+  },
+  {
+    "id": "eval_005",
+    "name": "TAVILY_API_KEY missing -- immediate stop at Step 1",
+    "description": "Validates that the skill stops at Step 1 with exact setup instructions when Tavily key is absent.",
+    "input": {
+      "prompt": "Find PR targets: https://notion.so",
+      "env": {
+        "TAVILY_API_KEY": "not set",
+        "FIRECRAWL_API_KEY": "set"
+      }
+    },
+    "expected_behavior": [
+      "Step 1 detects TAVILY_API_KEY is missing",
+      "Stops immediately at Step 1",
+      "Tells the user: 'TAVILY_API_KEY is required to research competitor press coverage and journalist contacts. There is no fallback for this. Get it at app.tavily.com. Free tier: 1000 credits/month (about 40 full runs). Add it to your .env file.'",
+      "Does NOT fetch the product page",
+      "Does NOT run any Tavily searches",
+      "Does NOT attempt competitor discovery or PR research"
+    ],
+    "expected_output": "Immediate stop at Step 1 with exact error message including the URL to get the key. No partial output generated."
+  }
+]

package/skills/competitor-pr-finder/references/pitch-guide.md

@@ -0,0 +1,119 @@
+# Pitch Guide
+
+## Cold Email Structure (Editorial)
+
+A cold pitch to a journalist has two fields: `subject` (the subject line) and `body` (the email body, 3-4 sentences). The body has four parts. Each part is one sentence.
+
+1. **Hook** -- Why this journalist, why now. Reference a specific piece they wrote and connect it to your category.
+2. **What you do** -- One sentence: what the product does, for whom, the core value. No buzzwords.
+3. **Why it fits their beat** -- The specific angle that matches how they covered your competitors. Use the angle extracted from the search results, not a generic claim.
+4. **Ask** -- A concrete, low-commitment request: a 15-minute call, or "happy to send more if it's useful."
+
+**Total length: under 150 words.** Journalists receive dozens of pitches per day. Shorter is always better.
+
+---
+
+## Subject Line Formulas
+
+The subject line is the most important part of the email. It determines whether it gets opened.
+
+**Formula A -- Journalist + Topic + Angle:**
+`[First name]: [topic they cover] + [your specific angle]`
+Example: `Maya: developer tooling + CI/CD without YAML config`
+
+**Formula B -- Reference their past coverage:**
+`Following up on your [competitor] piece`
+Example: `Following up on your Buildkite funding piece`
+
+**Formula C -- Category observation:**
+`[Observation about category trend] -- [company name]`
+Example: `Shift-left testing is becoming standard -- here's what we're seeing`
+
+**Avoid:**
+- Generic: "Exciting opportunity", "Partnership proposal", "Press inquiry"
+- Clickbait: "You won't believe...", "URGENT:", "Quick question"
+- Overly personal: "I've been following your work for years..."
+
+---
+
+## Podcast Pitch Specifics
+
+A podcast pitch is shorter and more conversational than a journalist pitch.
+
+**Structure:**
+1. Reference a specific episode they did that relates to your category (1 sentence)
+2. Propose a specific topic or talking point for an episode -- not just "interview me" (1-2 sentences)
+3. One-line credibility: why you're the right person to speak on this (metrics, background, or unique angle)
+4. Optional: propose an episode title
+
+**Length:** 3-5 sentences. Podcast hosts read these on phones between recordings.
+
+**Example:**
+> "Your episode with the Harness founder on platform engineering was one I kept coming back to. I'm building a zero-config CI/CD tool for teams that hate YAML and have some data on where pipeline complexity kills developer velocity. Happy to propose a few angles if useful."
+
+---
+
+## Story Angle Extraction
+
+A story angle is the framing the journalist used to make the story newsworthy. Extract it from the article title in the search results -- do not infer from AI training knowledge.
+
+**Common angle types and how to identify them from titles:**
+
+| Angle type | Title pattern |
+|---|---|
+| Funding announcement | "raises $X", "closes $X Series Y", "secures funding" |
+| Product launch | "launches", "introduces", "releases", "now available" |
+| Founder story | "How [Name] built", "[Name]'s journey", "from [X] to [Y]" |
+| Category creation | "the future of X", "why X is changing Y", "the rise of X" |
+| Trend piece | "Why more companies are...", "The shift to...", "2024 state of X" |
+| Customer story | "How [Company] uses X to Y", "[Company] cut Z by W% with X" |
+| Partnership or acquisition | "partners with", "acquires", "joins forces" |
+
+When drafting a cold pitch: use the same angle type that got the competitor featured. If TechCrunch covered three competitors with funding announcements, pitch your funding (or next milestone) story.
+
+If no clear angle type matches, use: "coverage story" as a neutral fallback.
+
+---
+
+## Forbidden Phrases
+
+Never include these in a cold pitch draft. They are instant delete signals.
+
+**Opening lines:**
+- "I hope this email finds you well"
+- "I'm reaching out because..."
+- "I wanted to share..."
+- "I thought you might be interested in..."
+- "My name is [Name] and I..."
+
+**Buzzwords:**
+- powerful, seamless, innovative, game-changing, revolutionary, disruptive
+- cutting-edge, best-in-class, world-class, next-generation
+- excited to announce, thrilled to share, proud to introduce
+- leverage, synergy, paradigm shift, holistic, robust
+
+**Vague claims:**
+- "fastest growing" (without a number)
+- "trusted by thousands" (without a number)
+- "leading provider" (without evidence)
+- "unique solution" (explain why instead)
+
+---
+
+## Bonus Hook Identification
+
+Bonus hooks are story angles NOT used by any of the researched competitors. To identify them:
+
+1. List all story angle types found in the competitor PR search results
+2. List the angles that are present in the product analysis but NOT in the competitor coverage
+3. These gaps are potential first-mover angles for the user's product
+
+**Example:** If all competitors were covered with funding announcements, but the user's product has a strong open-source community angle that no competitor has leaned into -- that's a bonus hook.
+
+Common underused angles:
+- Bootstrapped / no-VC angle (if relevant)
+- Open source release or contribution
+- Customer data / original research
+- Category naming (creating a new term for what the space does)
+- Contrarian take on a common assumption in the industry
+- Founder background that makes this company uniquely credible

package/skills/competitor-pr-finder/references/pr-channel-types.md

@@ -0,0 +1,81 @@
+# PR Channel Types
+
+## The Three Tracks
+
+### Track A: Editorial / News
+A journalist or staff writer published a piece about the company. The piece has a byline and appeared on a publication's website.
+
+**How to identify from a Tavily result:**
+- URL contains a known publication domain: `techcrunch.com`, `forbes.com`, `wired.com`, `theverge.com`, `venturebeat.com`, `infoq.com`, `thenewstack.io`, `businessinsider.com`, `fastcompany.com`, `inc.com`
+- Title format: "Company X Raises $Y", "How Company X is Changing Z", "Company X Launches...", "[Name] Profile: ..."
+- Content includes phrases like "reported", "according to", "the company said", "in an interview"
+
+**Why it matters for outreach:**
+Editorial coverage is the hardest to get but the most credible. Journalists have a beat -- they cover a specific domain -- so a pitch that fits their beat history gets read. The goal is not to pitch the publication; it's to pitch the specific journalist who already covers your category.
+
+**Approach method:** Cold email with a subject line tailored to their beat. Keep it under 150 words. Reference a specific piece they wrote.
+
+---
+
+### Track B: Podcasts
+A founder or executive appeared as a guest on a podcast episode to discuss their product, vision, or category.
+
+**How to identify from a Tavily result:**
+- URL contains: `podcasts.apple.com`, `open.spotify.com/episode`, `overcast.fm`, `pca.st`, `pod.link`, `buzzsprout.com`, `anchor.fm`, `transistor.fm`
+- Title format: "Ep 123: [Name] on building X", "[Name] interviews founder of Y", "How [Company] bootstrapped to $1M ARR"
+- A specific podcast name appears consistently: "Indie Hackers", "How I Built This", "The SaaS Podcast", "My First Million", "Acquired", "Lenny's Podcast"
+- Content describes a long-form conversation, not a news article
+
+**Why it matters for outreach:**
+Podcast hosts are warmer than journalists -- they talk to founders for 30-60 minutes per episode and often have a loyal audience in a specific niche. A show that has featured 3 of your competitors has already built audience trust in your category. The pitch is shorter and more conversational than an editorial pitch.
+
+**Approach method:** Short, casual pitch. Reference a specific episode they did in your space. Propose a concrete angle or talking point, not just "interview me about my startup."
+
+---
+
+### Track C: Communities
+The company was discussed, featured, or launched on a community platform -- discussion threads, upvotes, launch pages.
+
+**How to identify from a Tavily result:**
+- URL domain: `reddit.com/r/`, `news.ycombinator.com`, `producthunt.com`, `indiehackers.com`, `dev.to`, `hashnode.com`, `discord.gg` (less common in search results)
+- HN titles: "Show HN: [Company]" or "Ask HN: ..." with Company mentioned
+- Reddit titles: discuss, review, recommendation thread mentioning competitor
+- ProductHunt: `/posts/[company-name]` URL, "The best tool for X"
+
+**Why it matters for outreach:**
+Communities are earned, not pitched. You cannot pay or email your way in -- but you can post authentically. Subreddits and HN threads about your category are places where the audience already congregates. A ProductHunt launch in the right community can drive more trial signups than a Forbes article.
+
+**Approach method:** Not an email pitch. Launch on ProductHunt. Post genuinely on relevant subreddits (follow community rules, no spam). For HN: "Show HN" post when you have something real to show.
+
+---
+
+## Normalizing URLs to Domains
+
+When building the channel frequency map (Step 7), normalize all result URLs to their root domain so variants of the same publication are grouped:
+
+| Raw URL | Root domain |
+|---|---|
+| `techcrunch.com/2024/01/company-raises-x` | `techcrunch.com` |
+| `www.techcrunch.com/startups/...` | `techcrunch.com` |
+| `open.spotify.com/episode/abc123` | `spotify.com (podcast)` |
+| `podcasts.apple.com/us/podcast/...` | `apple podcasts` |
+| `news.ycombinator.com/item?id=123` | `news.ycombinator.com` |
+| `reddit.com/r/devops/comments/...` | `reddit.com/r/devops` |
+| `producthunt.com/posts/company-name` | `producthunt.com` |
+
+Reddit: preserve the subreddit level (`reddit.com/r/devops` not just `reddit.com`) because different subreddits serve different audiences.
+
+Podcasts hosted on Spotify or Apple: use the show name, not the platform domain, as the channel identifier. The platform is just the delivery mechanism.
+
+---
+
+## Channel Type to Approach Method
+
+| Channel Type | Approach Method | Notes |
+|---|---|---|
+| Editorial | Cold email to journalist | Find journalist name via Step 8 lookup |
+| Podcast | Pitch email to host or show booking email | Often listed on show website |
+| Community (ProductHunt) | Launch on ProductHunt | Schedule for Tuesday AM PT |
+| Community (Reddit) | Authentic post or comment in thread | No overt pitching; add value |
+| Community (HN) | Show HN post | Must have working product |
+| Newsletter | Reply to the author's last issue | Most newsletters have personal reply addresses |

package/skills/competitor-pr-finder/references/tier-scoring.md

@@ -0,0 +1,91 @@
+# Channel Tier Scoring
+
+## Core Tiering Rule
+
+Channels are tiered by how many of the 5 researched competitors appeared in that channel's coverage.
+
+| Tier | Threshold | What it means |
+|---|---|---|
+| Tier 1 | 3 or more competitors | Proven beat for this space. The journalist/host actively covers this category. Highest-value targets. |
+| Tier 2 | Exactly 2 competitors | Warm lead. Some demonstrated interest in the category. Worth pursuing after Tier 1. |
+| Tier 3 | Exactly 1 competitor | Discovery list only. May be a one-off or a niche fit. No deep dive or pitch draft required. |
+
+## Counting Rules
+
+- Count each **root domain** once per competitor, regardless of how many articles appeared from that domain.
+  - Example: 3 TechCrunch articles about the same competitor = TechCrunch counts as 1 for that competitor.
+- Count across all three tracks (editorial, podcast, community).
+  - A channel can be Tier 1 through a mix of tracks -- e.g., TechCrunch appears in Track A for 3 different competitors.
+- If the same channel appears across multiple tracks for the same competitor, it still counts as 1 for that competitor.
+
+## Override Rules
+
+**Tier 2 -> Tier 1 override:**
+If a Tier 2 channel is the dominant podcast for the space (estimated >100k listeners, or the most prominent show in the category), elevate it to Tier 1. This override exists because audience quality matters more than raw frequency for podcasts.
+
+Signals for override eligibility:
+- The podcast name is well-known in the category (e.g., "Acquired", "My First Million", "Lenny's Podcast" for B2B SaaS)
+- The episode title implies a deep-dive format (1+ hour, not a news brief)
+- Search results show a consistent pattern of category founders as guests
+
+**Geography filter:**
+- If the product's geography is US: deprioritize EU-only publications (Financial Times, TechCrunch EU section, Sifted). They can appear in Tier 3 but should not be elevated to Tier 1 or 2.
+- If the product's geography is Europe: deprioritize US-only niche press. Major US outlets (TechCrunch, Forbes) are still relevant as they cover global companies.
+- If geography is Global: no filter applied.
+
+**Community deduplication:**
+Reddit and Hacker News count as separate channels. `reddit.com/r/devops` and `reddit.com/r/programming` count as separate channels (different audiences). ProductHunt is its own channel.
+
+## What Goes in Each Tier's Output Section
+
+**Tier 1 -- Deep dives:**
+Each Tier 1 channel gets a full section in the output:
+- Channel name, type, frequency count, which competitors appeared
+- Evidence URLs from search results
+- Story angle type extracted from titles
+- Journalist/host name + beat (from Step 8 lookup, or "not found in search data")
+- Approach method
+- Cold pitch draft: subject line + 3-4 sentence body
+
+**Tier 2 -- Quick hits table:**
+A summary table: channel name, which competitors appeared, URL.
+No journalist lookup. No pitch draft. User can follow up manually.
+
+**Tier 3 -- Discovery list:**
+A bullet list: channel name + URL only.
+No analysis. Just awareness that coverage exists.
+
+## Channel Frequency Map Construction (Step 7)
+
+To build the frequency map:
+
+1. Collect all result URLs from `/tmp/cprf-pr-raw.json` for all competitors.
+2. For each result URL, extract the root domain (normalize per `pr-channel-types.md`).
+3. Build a set per competitor: which root domains appeared in their results?
+4. Count how many competitors each domain appears in.
+5. Sort by count descending. Domains with count >= 3 are Tier 1. Count == 2 are Tier 2. Count == 1 are Tier 3.
+
+**Example frequency map:**
+```
+techcrunch.com:       4 competitors (Tier 1)
+news.ycombinator.com: 4 competitors (Tier 1)
+producthunt.com:      3 competitors (Tier 1)
+infoq.com:            2 competitors (Tier 2)
+thenewstack.io:       2 competitors (Tier 2)
+devops.com:           1 competitor  (Tier 3)
+reddit.com/r/devops:  1 competitor  (Tier 3)
+```
+
+## Maximum Output Limits
+
+To keep the output actionable (not overwhelming):
+
+- Tier 1 deep dives: maximum 7 channels
+- Tier 2 quick hits: maximum 10 channels
+- Tier 3 discovery: maximum 15 channels (list only)
+- Bonus hooks: exactly 3
+
+If more channels qualify for a tier than the limit, prioritize by:
+1. Highest frequency count
+2. For equal counts: editorial > podcast > community
+3. For still-equal: alphabetical by domain name (deterministic)