@opendirectory.dev/skills 0.1.35 → 0.1.36

package/skills/npm-downloads-to-leads/evals/evals.json

@@ -0,0 +1,119 @@
+[
+  {
+    "id": "eval_001",
+    "name": "Mixed package list: scoped + unscoped, breakout + steady + declining",
+    "description": "A list of packages across different growth stages and including one scoped package. Validates full pipeline: scoped URL encoding, velocity ranking, only breakout/watching packages get GitHub enrichment, correct tier classification.",
+    "input": {
+      "prompt": "Find leads from these npm packages: esbuild, @hono/hono, lodash, zod, deprecated-old-pkg. We build a TypeScript developer tooling platform.",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Parses 5 package names including scoped @hono/hono",
+      "Step 3 URL-encodes @hono/hono as %40hono%2Fhono for the npm API call",
+      "Fetches 12 weeks of daily download data per package",
+      "Step 4 computes velocity scores using (growth_ratio * acceleration * noise_factor * 100) formula",
+      "Packages sorted by velocity_score descending in output",
+      "Only breakout and watching packages have GitHub profiles fetched in Step 5",
+      "lodash classified as 'established' (>500K/week) -- no GitHub enrichment attempted",
+      "deprecated-old-pkg shows low or declining velocity -- classified as 'steady' or 'too_early'",
+      "Lead briefs name the specific package and TypeScript developer tooling context",
+      "Suggested first messages are specific to each maintainer's package -- not generic",
+      "Output saved to docs/npm-leads/[date].md",
+      "No em dashes anywhere in output"
+    ],
+    "expected_output": "Velocity leaderboard with 5 packages, lead briefs for breakout/watching packages only, scoped package correctly handled, suggested messages reference TypeScript developer tooling context"
+  },
+  {
+    "id": "eval_002",
+    "name": "Single breakout package: full lead brief with GitHub and Twitter",
+    "description": "A single package in clear breakout trajectory (1K to 15K weekly over 8 weeks). Validates that the full 8-step pipeline runs, a lead brief is generated, and GitHub + Twitter contact info is correctly sourced from the API.",
+    "input": {
+      "prompt": "Analyze npm momentum for: zod",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Fetches 12 weeks of download data for zod",
+      "Computes velocity score and classifies tier",
+      "Step 5 fetches npm registry metadata: description, keywords, maintainers, repository URL",
+      "Extracts GitHub owner from repository.url field",
+      "Fetches GitHub user profile for extracted owner",
+      "lead brief growth_summary uses exact numbers from npm API -- not rounded or modified",
+      "maintainer_handle comes from GitHub API response username field",
+      "twitter field uses twitter_username from GitHub API -- writes 'not found on GitHub' if field is null",
+      "why_now references specific weeks and growth numbers from the data",
+      "suggested_message names zod specifically and does not use placeholder text",
+      "Self-QA step verifies GitHub handle was in API response before including in output"
+    ],
+    "expected_output": "Full lead brief for zod with exact download numbers, verified GitHub handle, Twitter if set on GitHub profile, specific why_now and suggested_message"
+  },
+  {
+    "id": "eval_003",
+    "name": "Package that does not exist: continues with remaining packages",
+    "description": "One package name in the list does not exist on npm (returns 404). Validates that the skill notes it in data_quality_flags and continues analyzing the remaining packages without aborting.",
+    "input": {
+      "prompt": "Track npm trends for: vite, this-package-does-not-exist-xyz123, esbuild",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Step 3 gets 404 from npm API for 'this-package-does-not-exist-xyz123'",
+      "Skill does NOT abort -- continues with vite and esbuild",
+      "Not-found package gets status='not_found' in scored data with velocity_score=0",
+      "data_quality_flags includes note about the 404 package",
+      "Output presents velocity leaderboard for vite and esbuild",
+      "Output section shows which package was skipped and why",
+      "No crash or incomplete output due to the missing package"
+    ],
+    "expected_output": "Velocity leaderboard for 2 packages (vite, esbuild), data_quality_flags noting the 404, no crash or abort"
+  },
+  {
+    "id": "eval_004",
+    "name": "GITHUB_TOKEN missing, rate limit hit during Step 5",
+    "description": "No GITHUB_TOKEN is set and the unauthenticated rate limit (60/hr) is exhausted partway through Step 5. Validates graceful degradation: presents velocity leaderboard from npm data, skips remaining GitHub enrichments, flags in data_quality_flags.",
+    "input": {
+      "prompt": "Find breakout npm packages: pkg-a, pkg-b, pkg-c, pkg-d, pkg-e, pkg-f, pkg-g, pkg-h, pkg-i, pkg-j, pkg-k",
+      "env": {
+        "GITHUB_TOKEN": "not set"
+      }
+    },
+    "expected_behavior": [
+      "Step 1 warns about 60 req/hr unauthenticated limit",
+      "Step 5 begins GitHub profile fetches for breakout/watching packages",
+      "After some fetches, X-RateLimit-Remaining drops to 5 or below",
+      "Skill detects gh_rate_remaining <= 5 and stops further GitHub enrichments",
+      "Skill does NOT abort the whole run",
+      "Packages enriched before the rate limit hit have GitHub data",
+      "Packages after the rate limit hit have github_users=[] in their profile",
+      "data_quality_flags includes note about GitHub rate limit hit and how many profiles were skipped",
+      "Velocity leaderboard is complete (from npm data, unaffected by GitHub rate limit)",
+      "Lead briefs for packages without GitHub data show 'GitHub profile: not found' instead of invented data"
+    ],
+    "expected_output": "Complete velocity leaderboard, partial GitHub enrichment, data_quality_flags noting rate limit hit, no invented contact info for un-enriched packages"
+  },
+  {
+    "id": "eval_005",
+    "name": "All packages below noise floor: graceful stop at Step 4",
+    "description": "All provided packages have fewer than 500 weekly downloads. Validates the graceful stop at Step 4 with a clear message -- no GitHub enrichment or lead briefs are attempted.",
+    "input": {
+      "prompt": "Analyze these npm packages: my-tiny-util, another-small-pkg, micro-helper-lib",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Step 3 fetches download data for all 3 packages",
+      "Step 4 computes velocity scores -- all packages get tier='too_early' (recent_4_avg < 500)",
+      "Step 4 detects no breakout and no watching packages",
+      "Stops at Step 4 with message: 'All packages are below the 500 weekly downloads threshold for reliable velocity analysis. Try packages with more community adoption.'",
+      "Does NOT proceed to Step 5 (no GitHub enrichment attempted)",
+      "Does NOT generate lead briefs",
+      "Output shows the download numbers for each package so the user understands why they were below threshold"
+    ],
+    "expected_output": "Graceful stop at Step 4 with download counts, clear threshold explanation, no partial output or GitHub API calls"
+  }
+]

package/skills/npm-downloads-to-leads/references/outreach-timing.md

@@ -0,0 +1,163 @@
+# Outreach Timing Reference
+
+Used by SKILL.md Step 6 to guide AI generation of lead briefs and outreach messages. The right timing and angle depends on where the maintainer is in their growth arc.
+
+---
+
+## Why Timing Is Everything
+
+A developer who just crossed 1,000 weekly downloads on their package is experiencing something new: real, sustained organic adoption. They are probably:
+- Watching the download counter more closely than usual
+- Starting to get GitHub issues from people they have never met
+- Wondering if they should write docs or a blog post
+- Not yet thinking about monetization, partnerships, or DevRel relationships
+
+This is the window. A relevant, specific message from a company that actually understands what they built lands completely differently than it would 6 months later when they have speaking requests, Twitter DMs from recruiters, and three other companies already in their inbox.
+
+---
+
+## Outreach by Growth Stage
+
+### Stage 1: First Traction (500 to 3,000/week)
+
+The maintainer is in "is this real?" territory. Downloads are clearly growing but they may still be wondering if it is a fluke.
+
+**What works:**
+- Acknowledge the specific thing they built, not just "your project"
+- Ask for feedback or perspective -- they are not famous enough yet to expect sponsorships or partnerships
+- Peer-to-peer framing: "We're building X and we noticed your package solves Y for the same developers"
+- Low-commitment ask: feedback, a question, or just an introduction
+
+**What does not work:**
+- "We'd love to partner with you" (too big for where they are)
+- "We noticed your package is growing fast" without specifics (sounds like a bot)
+- Pitching them immediately before establishing relevance
+
+**Template:**
+```
+Subject: [package-name] -- quick question from a builder in your space
+
+We use [package-name] for [specific use case] and noticed it's been growing fast.
+We build [brief description] for the same developers.
+[Specific observation about their package or a genuine question about their design decision]
+No ask yet -- just wanted to say it's a well-built tool.
+[Name]
+```
+
+---
+
+### Stage 2: Clear Breakout (3,000 to 20,000/week)
+
+The maintainer now knows the growth is real. They are getting more issues, maybe some contributions, possibly a few people asking about commercial support.
+
+**What works:**
+- Naming the inflection: "You've gone from X to Y downloads in 8 weeks -- that puts you in rare company"
+- Connecting their growth to a specific audience you both serve
+- A concrete proposal: integration, co-marketing, or early access to something relevant to their users
+- Flattery that is specific: quote something from their README or a design decision that shows you read it
+
+**What does not work:**
+- Vague partnership offers without a specific benefit
+- Asking them to promote your product in their README cold
+- Not mentioning their package by name
+
+**Template:**
+```
+Subject: [package-name] -- [specific angle in 6 words]
+
+[Package-name] went from [X] to [Y] downloads over the last 8 weeks.
+We build [product] for [same developer segment] and have been using it for [specific use case].
+[One sentence connecting their package's growth to why you're reaching out now]
+[Specific ask: integration conversation, early access, 20-minute call, or feedback request]
+[Name]
+```
+
+---
+
+### Stage 3: Established Breakout (20,000 to 100,000/week)
+
+The maintainer is now a recognized figure in their sub-community. They have probably been featured somewhere, have hundreds of GitHub stars, and are starting to think about sustainability.
+
+**What works:**
+- Direct business value: sponsorship, paid integration, commercial use case
+- "We have [N] customers using your package" -- this legitimizes you and signals commercial interest
+- Conference, podcast, or content collaboration (they are now building a reputation)
+- Concrete numbers: "We could get you in front of 5,000 of your target users"
+
+**What does not work:**
+- Pure outreach without a business angle (they are getting enough of that)
+- Asking for free consulting or feedback without offering something in return
+- Generic partnership language
+
+**Template:**
+```
+Subject: [package-name] -- [N] of our customers use it
+
+We have [N] teams using [package-name] through [your product].
+We build [product] for [developer segment] and your package is a core dependency for [specific workflow].
+[Specific proposal: integration, sponsorship, co-marketing, conference slot, or collaboration]
+[One-line ask: call, intro, or yes/no question]
+[Name]
+```
+
+---
+
+## The Verbatim Quote Technique
+
+The single highest-signal move in any outreach message is quoting something specific from their project -- README language, a design decision they wrote about, a specific feature name.
+
+**Without quote:**
+> "We noticed you built a validation library and we think there's a fit."
+
+**With quote:**
+> "Your README says 'Zod's goal is to eliminate duplicative type declarations' -- that's exactly the problem our users have when they adopt TypeScript on a legacy codebase. We built something adjacent for the API layer."
+
+The quote proves you read it. It also filters you out of the 95% of outreach that clearly does not. A developer who has been sending bug fixes to a project at midnight will respond to someone who clearly understood what they were building.
+
+---
+
+## Finding the Right Angle Based on Package Category
+
+Use the keywords and description from the npm registry to match the outreach angle to the package type.
+
+| Package Category | Best Angle |
+|---|---|
+| Build tools / bundlers | Performance, DX, CI integration time, large codebase support |
+| Validation / schema | Type safety, form handling, API contract enforcement |
+| HTTP / API clients | Multi-environment support, retry logic, error handling |
+| Testing utilities | Coverage, speed, snapshot behavior |
+| State management | Scale, debugging, SSR support |
+| CLI tools | Scripting workflows, automation, team adoption |
+| Database / ORM | Migration pain, type inference, query complexity |
+| Auth / security | Compliance, session management, multi-provider support |
+
+The suggested first message should reference the specific category and connect it to what the person reaching out actually builds.
+
+---
+
+## What to Never Write
+
+Regardless of growth stage or package category, these phrases signal a template and get ignored:
+
+- "I came across your project" -- too generic
+- "I'm a huge fan of your work" -- unverifiable and sounds like a bot
+- "We'd love to explore synergies" -- says nothing
+- "Your package is powerful" -- the word "powerful" is on every cold email
+- "I know you're busy" -- everyone is busy; mentioning it wastes a line
+- "Just wanted to reach out" -- there is always a reason; state it
+- "Feel free to ignore this" -- they will
+- Any subject line over 8 words
+
+The outreach hook that works is: specific thing they built + specific reason you noticed it now (the growth inflection) + specific reason you are the right person to reach out. Three sentences. Under 100 words total.
+
+---
+
+## Following Up
+
+If there is no response after 7 days, one follow-up is acceptable. The follow-up should not repeat the pitch -- it should add new information:
+
+- A new data point: "Your downloads crossed [milestone] since I last wrote"
+- A new connection: "I saw you mentioned [topic] in [place] -- that's exactly what we're solving"
+- A direct question instead of a pitch: "Are you thinking about [specific pain point] yet?"
+
+Two messages with no response means the timing is wrong. Do not send a third. Revisit in 90 days if the package keeps growing.

package/skills/npm-downloads-to-leads/references/velocity-scoring.md

@@ -0,0 +1,136 @@
+# Velocity Scoring Reference
+
+Used by SKILL.md Step 4 to classify npm packages by growth trajectory. The velocity score identifies packages in the hockey-stick growth phase, not just packages with high download volumes.
+
+---
+
+## The Problem with Raw Downloads
+
+If you rank npm packages by raw weekly downloads, the top results are always React, lodash, TypeScript, and axios. These packages are not leads. Their maintainers are already famous, already overwhelmed with outreach, and already well beyond the "catch them early" window.
+
+The signal is relative growth -- a package going from 1,000 to 8,000 weekly downloads over 8 weeks is more interesting than React at 50 million, because:
+1. The maintainer just crossed an inflection point -- they are building an audience now
+2. They are not yet famous -- your outreach lands in a less-crowded inbox
+3. Their growth signals that developers are finding value in what they built -- that is the same developer segment you are trying to reach
+
+---
+
+## The Velocity Score Formula
+
+```python
+recent_4 = sum(weeks[-4:]) / 4    # average of last 4 weeks
+prior_4 = sum(weeks[-8:-4]) / 4   # average of prior 4 weeks
+recent_2 = sum(weeks[-2:]) / 2    # last 2 weeks (acceleration check)
+mid_2 = sum(weeks[-4:-2]) / 2     # previous 2 weeks (acceleration baseline)
+
+growth_ratio = recent_4 / max(prior_4, 1)
+acceleration = recent_2 / max(mid_2, 1)
+
+# Sweet spot multiplier
+if recent_4 < 500:
+    noise_factor = max(recent_4 / 500, 0.1)   # penalize noise floor
+elif recent_4 > 500_000:
+    noise_factor = max(500_000 / recent_4, 0.1)  # penalize established giants
+else:
+    noise_factor = 1.0
+
+velocity_score = growth_ratio * acceleration * noise_factor * 100
+```
+
+**Why three components:**
+
+- `growth_ratio`: Is the package getting more downloads recently than before? A ratio of 2.0 means double the average downloads in the recent 4 weeks vs the prior 4.
+- `acceleration`: Is growth speeding up? A ratio of 1.2 means the last 2 weeks were 20% higher than the 2 weeks before that. This distinguishes a sustained breakout from a one-week spike.
+- `noise_factor`: The sweet spot correction. Packages under 500/week are statistically unreliable (one viral tweet can quadruple downloads). Packages over 500K/week grow slowly by necessity -- a 10% growth at that scale represents millions of new downloads but looks small as a ratio.
+
+---
+
+## Score Interpretation
+
+| Velocity Score | What it means |
+|---|---|
+| > 150 | Exceptional breakout. Growth is fast and accelerating. The maintainer is in a phase they probably have not experienced before. |
+| 80-150 | Clear breakout. Consistent multi-week growth with acceleration. Strong lead candidate. |
+| 40-80 | Watching. Growing but not at breakout pace. Worth monitoring -- may cross into breakout in 4-8 weeks. |
+| 10-40 | Steady. Growing slowly or holding volume. Not a near-term lead from growth signals alone. |
+| < 10 | Declining or flat. May have had growth earlier, but current trend is neutral or down. |
+
+---
+
+## Tier Definitions
+
+| Tier | Criteria | Action |
+|---|---|---|
+| `breakout` | velocity_score > 80 AND 500 < recent_4 < 500,000 | Generate full lead brief + outreach message |
+| `watching` | velocity_score > 40 | Generate lead brief, flag as "not yet breakout" |
+| `steady` | velocity_score 10-40 | Show in leaderboard, no lead brief |
+| `established` | recent_4 >= 500,000 | Show in leaderboard, note scale ceiling on velocity |
+| `too_early` | recent_4 < 500 | Note download count, suggest revisiting when above 500/week |
+| `insufficient_data` | fewer than 4 weeks of data | Skip velocity calculation entirely |
+
+---
+
+## The Sweet Spot: 500 to 500,000 Weekly Downloads
+
+**Below 500/week:** A single blog post, a tweet from a developer with 10K followers, or a single CI pipeline at a large company can temporarily push a package from 50 to 300 downloads. This is not a trend -- it is a random event. The velocity score for these packages is unreliable and should not drive outreach decisions.
+
+**500 to 10,000/week:** This is where breakout discovery is most valuable. The package has real organic adoption, the maintainer is seeing real growth for possibly the first time, and the audience is still small enough that outreach from a relevant company feels meaningful rather than corporate.
+
+**10,000 to 100,000/week:** Still strong territory. The maintainer is probably getting some attention now but is not yet the subject of conference talks and podcast interviews. Still a good window.
+
+**100,000 to 500,000/week:** The package is well-established. The maintainer likely has some reputation in the ecosystem. Outreach still works but requires a stronger angle -- you are not the first person to notice them.
+
+**Above 500,000/week:** These are the top 0.1% of npm packages. Their maintainers are public figures in the developer ecosystem. The "before they are famous" window has closed.
+
+---
+
+## Acceleration Matters More Than You Expect
+
+A package with `growth_ratio = 2.0` but `acceleration = 0.7` means: it doubled over 8 weeks, but the growth is actually slowing down. The last 2 weeks were slower than the 2 weeks before. This could be:
+- A spike fading (viral moment passing)
+- Growth plateauing after an initial launch burst
+- A product that got attention but is not retaining users who try it
+
+A package with `growth_ratio = 1.5` and `acceleration = 1.4` means: 50% growth over 8 weeks and the last 2 weeks were 40% higher than the prior 2. This is a package that is still accelerating. The inflection may not have happened yet.
+
+The velocity formula weights both. A package that is growing AND accelerating gets a higher score than one that grew quickly but is now decelerating.
+
+---
+
+## Common Misclassifications
+
+**Spike then flat:** A package gets 5,000 downloads in one week (from a tweet or Product Hunt feature) and then returns to 200/week. If the spike is in the recent_4 window, it will inflate the velocity score. Check the weekly trend array -- if it shows a single high spike rather than a steady incline, the breakout classification is unreliable.
+
+**New package (fewer than 8 weeks old):** A new package going from 0 to 800 in its first 4 weeks will have a high growth_ratio (prior_4 is near 0). The formula guards against this with `max(prior_4, 1)`, which keeps the ratio from being infinity but can still produce inflated scores. The insufficient_data tier handles packages with fewer than 4 full weeks.
+
+**Seasonal packages:** Some packages (tax filing tools, holiday card generators) have predictable annual spikes. If the analysis runs during the spike season, the velocity score will be high. The 12-week window partially mitigates this but does not eliminate it.
+
+---
+
+## What a Real Breakout Looks Like (Weekly Trend)
+
+Genuine sustained breakout:
+```
+Week 1:  1,200
+Week 2:  1,400
+Week 3:  1,900
+Week 4:  2,800
+Week 5:  3,900
+Week 6:  5,200
+Week 7:  6,800
+Week 8:  8,900
+```
+
+Spike-and-flat (not a breakout):
+```
+Week 1:    800
+Week 2:    850
+Week 3: 12,400  <-- viral tweet or HN post
+Week 4:    900
+Week 5:    950
+Week 6:  1,000
+Week 7:    980
+Week 8:  1,050
+```
+
+The trend array in the output lets you visually distinguish these patterns. A good velocity score combined with a consistent upward trend array is the strongest signal.