@opendirectory.dev/skills 0.1.34 → 0.1.36

package/skills/gh-issue-to-demand-signal/evals/evals.json

@@ -0,0 +1,118 @@
+[
+  {
+    "id": "eval_001",
+    "name": "Popular OSS repo: full pipeline with 100+ issues, all 6 categories populated",
+    "description": "A large, active public repo with hundreds of open issues. Validates the full 8-step workflow, noise filtering, demand scoring, all 6 categories appearing in output, and correct sorting.",
+    "input": {
+      "prompt": "Scan competitor GitHub issues: https://github.com/facebook/react",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Parses owner=facebook, repo=react correctly",
+      "Fetches 2 pages of issues from GitHub REST API",
+      "Checks X-RateLimit-Remaining after first page fetch",
+      "Filters out pull requests (pull_request key present), bot-authored issues, chore/deps/bump title patterns, zero-reaction + zero-comment issues",
+      "Issue count after filtering is above 10 -- proceeds to clustering",
+      "demand_score computed as (reactions_plus1 * 2) + (comments * 0.5) for each issue",
+      "ignored_demand field set to true only for issues with reactions >= 10, age_days >= 180, and no planned label",
+      "Skill prints filtered issues and asks the AI to classify them into 6 categories",
+      "AI writes /tmp/ghd-clusters.json with classified_issues, cluster_themes, and category_counts",
+      "All 6 categories appear in category_counts",
+      "Top-10 list sorted by demand_score descending",
+      "Skill prints top 3 clusters and asks the AI to write a messaging brief",
+      "AI writes /tmp/ghd-brief.json with exactly 3 positioning_angles, 3 outreach_hooks, 3 cluster_headlines",
+      "Every outreach hook contains a quoted verbatim issue title",
+      "Output saved to docs/demand-signals/facebook-react-[date].md",
+      "No em dashes in any output section"
+    ],
+    "expected_output": "Full demand gap report with leaderboard, ignored demand section, top-10, cluster deep dives, messaging brief, and GTM angles"
+  },
+  {
+    "id": "eval_002",
+    "name": "Small or inactive repo: graceful stop after Step 4",
+    "description": "A repo with very few open issues or a niche project where most issues have zero reactions. After noise filtering, fewer than 10 issues remain. Validates graceful stop with a clear explanation.",
+    "input": {
+      "prompt": "Analyze issues in this repo: https://github.com/nicowillis/tiny-test-repo",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Fetches issues successfully",
+      "Noise filter removes most issues (zero engagement, bot patterns, etc.)",
+      "After filtering, fewer than 10 issues remain",
+      "Stops at Step 4 -- does NOT proceed to clustering",
+      "Tells the user exactly how many issues were found and how many were filtered",
+      "Explains why fewer than 10 issues is insufficient for reliable clustering",
+      "Suggests trying a larger or more community-engaged repo",
+      "No partial output generated"
+    ],
+    "expected_output": "Graceful stop message with issue counts, noise breakdown, and suggestion to try a different repo"
+  },
+  {
+    "id": "eval_003",
+    "name": "Private or non-existent repo: stops at Step 3 with exact error",
+    "description": "User provides a URL for a repo that either does not exist (404) or is private (403). Validates that the skill stops at Step 3 with a clear, actionable error message.",
+    "input": {
+      "prompt": "Find demand gaps in https://github.com/nonexistent-org/nonexistent-repo-xyz",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Parses owner/repo from URL",
+      "Attempts GitHub API fetch",
+      "GitHub returns 404",
+      "Stops immediately at Step 3",
+      "Tells the user: 'Repo not found. Check the URL or slug and try again. Private repos are not accessible without authentication and explicit repo scope.'",
+      "Does NOT attempt noise filtering",
+      "Does NOT proceed to clustering"
+    ],
+    "expected_output": "Immediate stop at Step 3 with 404 error message. No partial analysis generated."
+  },
+  {
+    "id": "eval_004",
+    "name": "owner/repo slug input (no full URL): parses correctly and runs full pipeline",
+    "description": "User provides an owner/repo slug instead of a full GitHub URL (e.g. 'vercel/next.js' instead of 'https://github.com/vercel/next.js'). Validates that the slug parsing path works correctly.",
+    "input": {
+      "prompt": "What are users asking for in vercel/next.js?",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Step 2 detects no 'github.com' URL in the input",
+      "Falls into the owner/repo slug parsing path",
+      "Correctly splits 'vercel/next.js' into owner=vercel, repo=next.js",
+      "Writes 'vercel/next.js' to /tmp/ghd-target.txt",
+      "Step 3 fetches from https://api.github.com/repos/vercel/next.js/issues successfully",
+      "Full pipeline runs to completion",
+      "Output filename uses 'vercel-next.js' as the repo slug",
+      "No error about invalid URL format"
+    ],
+    "expected_output": "Full demand gap report identical in format to a full URL run. Slug parsing is transparent to the output."
+  },
+  {
+    "id": "eval_005",
+    "name": "No GITHUB_TOKEN, rate limit hit: stops with reset time and token instructions",
+    "description": "User has no GITHUB_TOKEN and has already hit the 60/hr unauthenticated rate limit. Validates that the skill detects the rate limit header and stops with the reset time and token setup instructions.",
+    "input": {
+      "prompt": "What are users asking for in facebook/react?",
+      "env": {
+        "GITHUB_TOKEN": "not set"
+      }
+    },
+    "expected_behavior": [
+      "Step 1 notes GITHUB_TOKEN is not set and warns about 60 req/hr limit",
+      "Step 3 attempts GitHub API fetch without token",
+      "GitHub API returns X-RateLimit-Remaining: 0 header",
+      "Skill detects the header value after the first page fetch",
+      "Stops immediately with message: exact reset time (converted from X-RateLimit-Reset timestamp) and instructions to add GITHUB_TOKEN at github.com/settings/tokens",
+      "Does NOT attempt page 2 fetch",
+      "Does NOT proceed to noise filtering or clustering"
+    ],
+    "expected_output": "Stop at Step 3 with rate limit message, reset time, and GitHub token setup link. No analysis generated."
+  }
+]

package/skills/gh-issue-to-demand-signal/references/demand-categories.md

@@ -0,0 +1,181 @@
+# Demand Categories Reference
+
+Used by SKILL.md Step 5 to guide AI classification of GitHub issues into one of 6 demand categories.
+
+---
+
+## The 6 Categories
+
+### feature_gap
+
+**What it captures:** Functionality the product does not have yet. User is describing something they want to do that is currently impossible.
+
+**Signal phrases:**
+- "add support for..."
+- "it would be great if..."
+- "please add..."
+- "feature request:"
+- "allow users to..."
+- "I wish I could..."
+- "would love to see..."
+
+**Examples:**
+- "Add support for keyboard shortcuts in the editor"
+- "Allow exporting to PDF format"
+- "Feature request: dark mode"
+- "Support for multiple workspaces per account"
+
+**Scoring note:** feature_gap issues with 20+ reactions represent product roadmap signals. These are the gaps your product can claim as intentional design choices.
+
+---
+
+### bug_pattern
+
+**What it captures:** Recurring broken behavior that erodes user trust. Distinct from a one-off error -- the word "pattern" matters. Multiple issues with similar titles indicate a systemic problem.
+
+**Signal phrases:**
+- "broken when..."
+- "not working..."
+- "fails to..."
+- "error when..."
+- "crashes if..."
+- "regression in..."
+- "breaks after..."
+
+**Examples:**
+- "Login fails when using SSO with Google"
+- "File upload crashes on files over 10MB"
+- "Pagination breaks on mobile"
+- "Notifications not sending after the latest update"
+
+**Scoring note:** Bug patterns with high reactions signal trust erosion. If a competitor has 5+ high-reaction bug issues in the same functional area, that area is a liability in their product positioning.
+
+---
+
+### ux_complaint
+
+**What it captures:** Friction, confusion, or workflow problems. The feature exists but it is hard to use, hard to find, or does not match how users actually work.
+
+**Signal phrases:**
+- "confusing..."
+- "hard to..."
+- "unclear how to..."
+- "should be easier to..."
+- "the UI for X is..."
+- "annoying that..."
+- "clunky..."
+- "why does X require..."
+
+**Examples:**
+- "Confusing navigation between projects"
+- "Hard to find the settings for notifications"
+- "Should be easier to bulk-edit items"
+- "The import flow has too many steps"
+
+**Scoring note:** UX complaints are positioning gold. "Confusing to use" is a contrast you can own directly. If their users are calling something confusing, your messaging can address that exact friction without naming the competitor.
+
+---
+
+### performance
+
+**What it captures:** Slowness, timeouts, resource usage, or reliability problems that degrade the experience even when the feature works correctly.
+
+**Signal phrases:**
+- "slow..."
+- "timeout..."
+- "takes too long..."
+- "high memory usage..."
+- "performance regression..."
+- "loading forever..."
+- "lags when..."
+- "CPU usage..."
+
+**Examples:**
+- "Search is slow on repos with 1000+ files"
+- "Dashboard takes 10+ seconds to load"
+- "Memory usage spikes when processing large files"
+- "Build times increased 3x after v2.0"
+
+**Scoring note:** Performance issues cluster by data size or scale. If the complaints mention large repos, large teams, or high-volume usage, the competitor has a scale ceiling. That ceiling is your advantage if you have solved it.
+
+---
+
+### integration_missing
+
+**What it captures:** Requests to connect with other tools, APIs, or platforms. Users want the product to work alongside something else in their stack.
+
+**Signal phrases:**
+- "integrate with..."
+- "support for [tool name]..."
+- "webhook..."
+- "API for..."
+- "connect to..."
+- "import from..."
+- "sync with..."
+- "plugin for..."
+
+**Examples:**
+- "Integrate with Slack for notifications"
+- "Support GitHub Actions webhook triggers"
+- "Add Zapier integration"
+- "Import from Notion"
+- "VS Code extension"
+
+**Scoring note:** Integration requests cluster around the tools their users already use. A high-reaction integration request tells you where their users spend the rest of their day. If you already have that integration, it is a direct switch argument.
+
+---
+
+### docs_missing
+
+**What it captures:** Confusion caused by absent, incomplete, or incorrect documentation. The product may work correctly, but users cannot figure out how to use it.
+
+**Signal phrases:**
+- "no documentation for..."
+- "docs are missing..."
+- "unclear how to..."
+- "example for..."
+- "how do I..."
+- "docs don't explain..."
+- "add docs for..."
+- "tutorial for..."
+
+**Examples:**
+- "No documentation for the webhook authentication flow"
+- "Missing example for advanced configuration"
+- "How do I set up custom domains? Docs don't cover this."
+- "Add a tutorial for migrating from v1 to v2"
+
+**Scoring note:** docs_missing issues often indicate a product that has grown faster than its documentation. High-reaction docs issues in a specific area indicate that the area is both important to users and opaque in practice.
+
+---
+
+## Classification Rules
+
+### One category per issue
+Every issue gets exactly one category. Use the primary pain, not all possible interpretations.
+
+- "The export feature is broken and also slow" -- classify as `bug_pattern` (primary pain: it does not work)
+- "Export to PDF is slow" -- classify as `performance` (it works, it is just slow)
+- "Add export to PDF" -- classify as `feature_gap` (it does not exist)
+
+### When to use ux_complaint vs docs_missing
+- If the user says "I can't figure out how to X" and the docs don't cover it: `docs_missing`
+- If the user says "X is confusing" or "X is hard to use" and the feature exists: `ux_complaint`
+- If both apply: `ux_complaint` (the UI is the product, the docs are secondary)
+
+### When to use bug_pattern vs performance
+- If it does not work at all: `bug_pattern`
+- If it works but is slow or resource-heavy: `performance`
+
+---
+
+## Category Demand Signal Interpretation
+
+| Category | What high demand here tells you |
+|---|---|
+| feature_gap | Their roadmap is behind their users. Name what you have built. |
+| bug_pattern | Trust erosion in a specific area. Position your reliability there. |
+| ux_complaint | Their users are struggling. Position your simplicity there. |
+| performance | They hit a scale ceiling. Position your throughput or response time. |
+| integration_missing | Their users live in a different stack. Show your integration depth. |
+| docs_missing | They ship but do not explain. Position your onboarding and support. |

package/skills/gh-issue-to-demand-signal/references/gtm-translation.md

@@ -0,0 +1,211 @@
+# GTM Translation Reference
+
+How to convert demand clusters from competitor GitHub issues into GTM language. Used by SKILL.md Step 6 to guide the messaging brief generation.
+
+---
+
+## The Translation Problem
+
+Raw demand data from GitHub is in user language, not buyer language. A product manager reads:
+
+> "Add support for multiple workspaces per account" -- 87 reactions, open 2 years
+
+A GTM-trained analyst reads:
+
+> "Enterprise buyers need multi-tenancy. This competitor has not shipped it in 2 years. 87 teams are waiting. If you have this, lead with it."
+
+This reference document is the bridge between those two readings.
+
+---
+
+## Translation by Category
+
+### feature_gap clusters
+
+**What the data shows:** Users want something that does not exist.
+
+**GTM translation:**
+- If you have the feature: "We built what [competitor] has not." Name the feature specifically.
+- If you are building it: Use the cluster as proof that the market exists. "87 teams on [competitor] asked for X. We built it."
+- If you do not have it: This is a roadmap signal, not a positioning signal yet.
+
+**Outreach hook pattern:**
+```
+"[Number] teams on [competitor] have been asking for [specific feature] for [time].
+We shipped [your feature] in [your product] [time ago / as a core feature].
+[One-line ask]."
+```
+
+**Example:**
+```
+"Over 200 teams on [competitor] asked for multi-workspace support. It has been open for 3 years with no planned label.
+We built workspace isolation as a core feature, not an add-on.
+Would a 20-minute call be useful?"
+```
+
+---
+
+### bug_pattern clusters
+
+**What the data shows:** Something is reliably broken. High reaction counts on bug issues mean many users hit the same wall.
+
+**GTM translation:**
+- Do not say "they are buggy." Say: "Teams in [X workflow] need reliability."
+- Position the broken area as a category where you have invested specifically.
+- The number of reactions is the credibility anchor. Use it.
+
+**Outreach hook pattern:**
+```
+"[Number] teams using [competitor] hit [specific bug area].
+[Your product] was built [for/around/specifically to handle] this workflow without [the failure mode].
+[One-line ask]."
+```
+
+**Example:**
+```
+"Teams using [competitor] have hit login failures with SSO -- 43 reactions on that issue, open for 18 months.
+We built our auth layer around SSO-first design and have not had an SSO outage in 18 months of production.
+Worth a conversation?"
+```
+
+---
+
+### ux_complaint clusters
+
+**What the data shows:** The feature exists but users cannot use it without friction.
+
+**GTM translation:**
+- Simplicity is a product decision, not a feature. Position it as intentional design.
+- Use "setup time" or "time to value" as the measurable proxy for simplicity.
+- Do not say "our UI is better." Say: "Teams get to [outcome] in [time], without [the friction they described]."
+
+**Outreach hook pattern:**
+```
+"[Number] users of [competitor] said [specific UX friction in quotes].
+[Your product] gets [persona] to [outcome] in [time] with [fewer steps / no setup / no configuration].
+[One-line ask]."
+```
+
+**Example:**
+```
+"158 users of [competitor] called the project navigation 'confusing' -- that issue is 2 years old.
+We redesigned navigation around the workflow, not the feature tree. Teams reach their first result in under 2 minutes.
+Would you like to see it?"
+```
+
+---
+
+### performance clusters
+
+**What the data shows:** The product hits a scale ceiling. High-reaction performance issues cluster around a specific bottleneck (large files, large teams, high query volume).
+
+**GTM translation:**
+- Name the scale ceiling specifically: "repos over 1000 files", "teams over 50 users", "queries over 10k/day".
+- If you have benchmarks, use them. If not, use the absence of the complaint as proof.
+- Performance positioning works best for technical buyers (engineers, infrastructure teams).
+
+**Outreach hook pattern:**
+```
+"Teams at [competitor] hit [specific bottleneck] at [scale threshold].
+[Your product] handles [scale threshold] in [benchmark or time].
+[One-line ask]."
+```
+
+**Example:**
+```
+"Engineering teams using [competitor] report 10+ second load times on repos over 500 files -- 67 reactions, no fix in sight.
+We load repos of that size in under 1.5 seconds because we index differently.
+I can show you a benchmark on a repo your size."
+```
+
+---
+
+### integration_missing clusters
+
+**What the data shows:** Users work in tools this competitor does not connect to. High-reaction integration requests tell you exactly what else is in their users' daily stack.
+
+**GTM translation:**
+- If you have the integration: make it the lead, not a footnote.
+- The reaction count is the size of the audience that wants this bridge. Name the number.
+- Integration positioning works best when the target tool is a category leader (Slack, Notion, GitHub Actions, Salesforce).
+
+**Outreach hook pattern:**
+```
+"[Number] teams on [competitor] asked for [specific integration]. It has been open [time] with no planned label.
+[Your product] connects to [integration] natively -- [brief description of how it works].
+[One-line ask]."
+```
+
+**Example:**
+```
+"94 teams on [competitor] asked for Slack integration. The request is 3 years old with no planned label.
+We shipped bidirectional Slack sync 6 months ago -- alerts in Slack, actions back to [your product].
+Worth showing you?"
+```
+
+---
+
+### docs_missing clusters
+
+**What the data shows:** Users cannot figure out how to do something. The product may work, but the path to value is opaque.
+
+**GTM translation:**
+- Documentation is a trust signal, not a feature. "We have clear docs" is not a hook.
+- Translate to: "Teams are in production in [time]" or "We have a guided setup for [exact use case they documented badly]."
+- Onboarding speed is the business outcome. Use it.
+
+**Outreach hook pattern:**
+```
+"[Number] users on [competitor] asked for documentation on [specific topic].
+We have [specific guide / template / interactive tutorial] for [exact use case].
+Teams using our [guide/setup] are in production in [time].
+[One-line ask]."
+```
+
+**Example:**
+```
+"38 teams on [competitor] asked for documentation on webhook authentication. There is still no official guide.
+We have a step-by-step webhook setup guide that gets teams from zero to first event in under 15 minutes.
+I can send it -- it works for any webhook destination, not just ours."
+```
+
+---
+
+## Using Verbatim Issue Language
+
+The most effective outreach hooks use the user's exact words from the issue title. This works because:
+
+1. It proves you read real feedback, not marketing copy.
+2. It speaks in the buyer's language, not product language.
+3. It names the pain before pitching the solution.
+
+**Wrong approach (paraphrased):**
+> "Many teams find navigation confusing in competitor products."
+
+**Right approach (verbatim quote):**
+> "158 users said 'confusing navigation between projects' has been open for 2 years. We redesigned for workflow, not feature hierarchy."
+
+The quote is the credibility anchor. Do not remove it.
+
+---
+
+## Ignored Demand: The Highest-Signal Category
+
+An issue that meets all three criteria:
+- 10+ reactions (significant real demand)
+- Open 180+ days (competitor has had time to act)
+- No planned/in-progress label (they have explicitly not prioritized it)
+
+This is not a feature request. This is a documented unmet need with a timestamp.
+
+**GTM translation:** "Their users asked. Their team did not respond. We built it."
+
+This framing works across all 6 categories. The combination of volume + age + inaction is the signal. The category determines the messaging angle.
+
+**Ignored demand outreach template:**
+```
+"[Competitor]'s users have been asking for [verbatim issue title] for [age].
+[Reaction count] teams upvoted it. There is no planned label.
+[Your product] handles this [natively / differently / as a core feature].
+[One-line ask]."
+```

package/skills/npm-downloads-to-leads/.env.example

@@ -0,0 +1,4 @@
+GITHUB_TOKEN=    # optional -- github.com/settings/tokens (no scopes needed for public user profiles)
+                 # Without it: 60 req/hr unauthenticated -- enough for ~10 packages before degrading
+                 # With it: 5000 req/hr -- handles any reasonable package list without hitting limits
+                 # The skill degrades gracefully if the limit is hit: shows npm velocity data without GitHub enrichment

package/skills/npm-downloads-to-leads/README.md

@@ -0,0 +1,146 @@
+# npm-downloads-to-leads
+
+Give this skill a list of npm packages. It fetches 12 weeks of download data, scores each package by growth velocity, maps maintainers to GitHub and Twitter, and outputs a ranked lead brief per breakout package: who built it, how to reach them, and what to say.
+
+## Install
+
+```bash
+npx "@opendirectory.dev/skills" install npm-downloads-to-leads --target claude
+```
+
+### Video Tutorial
+
+https://github.com/user-attachments/assets/ee98a1b5-ebc4-452f-bbfb-c434f2935067
+
+### Step 1: Download from GitHub
+1. Click the **Code** button on this repo's GitHub page.
+2. Select **Download ZIP**.
+3. Extract the ZIP on your computer.
+
+### Step 2: Install in Claude
+1. Open the **Claude desktop app**.
+2. Go to **Customize** in the sidebar.
+3. Click the **Skills** tab, then the **+** button.
+4. Choose **Upload a skill** and drop the folder or ZIP file.
+
+Note: Upload the folder that contains the `SKILL.md` file.
+
+## What It Does
+
+- Fetches 12 weeks of daily download data per package from the npm Downloads API
+- Aggregates to weekly buckets and computes a velocity score: recent growth x acceleration x sweet-spot multiplier
+- Classifies each package as BREAKOUT, WATCHING, steady, established, or too early
+- Fetches maintainer profiles from the npm registry and GitHub API
+- Extracts GitHub followers, Twitter handle, bio, and company from each maintainer's GitHub profile
+- Generates a lead brief per breakout package: growth story, contact signals, why to reach out now, and a suggested first message
+- Saves output to `docs/npm-leads/[date].md`
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|---|---|---|
+| GitHub token | Raises rate limit from 60/hr to 5000/hr for maintainer profile lookups | github.com/settings/tokens (no scopes needed for public user profiles) |
+
+No external AI API key needed. The npm and npm registry APIs are fully public with no auth. GitHub token is optional but recommended for lists larger than 10 packages.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Add GITHUB_TOKEN (optional, recommended for larger package lists)
+```
+
+## How to Use
+
+```
+"Find leads from these npm packages: esbuild, vite, @hono/hono, zod"
+"Track download trends for competitor packages: turbo, nx, lerna"
+"Who maintains these breakout npm packages? bun, oxc-parser, biome"
+"Find evangelists before they are famous: @effect-ts/core, fp-ts, zod"
+"Analyze npm momentum for my space: my-package, competitor-a, competitor-b"
+"Map npm maintainers to Twitter for these packages: ..."
+```
+
+Include a short description of your product and the skill will tailor the outreach message to your context.
+
+## Why Velocity Score, Not Raw Downloads
+
+React gets 50 million downloads a week. Its maintainers are already famous, already inundated with outreach, and already aligned with a framework you are likely building on.
+
+The velocity score finds the package going from 1K to 8K weekly downloads over 8 weeks. That maintainer just crossed a growth inflection. They are building an audience, they are not yet overwhelmed, and they are in a phase where your product makes a difference to their workflow.
+
+The formula: `velocity_score = growth_ratio x acceleration x sweet_spot_multiplier`
+
+- `growth_ratio`: recent 4-week average divided by prior 4-week average
+- `acceleration`: last 2 weeks vs mid 2 weeks (is growth speeding up?)
+- `sweet_spot_multiplier`: 1.0 for 500 to 500K weekly downloads, lower for noise floor or established giants
+
+Breakout threshold: velocity score above 80 AND 500 to 500K weekly downloads.
+
+## The Lead Brief
+
+For each breakout and watching package:
+
+- **Growth story**: exact download numbers, 8-week comparison, weekly trend
+- **Maintainer profile**: GitHub handle, Twitter, bio, company, follower count
+- **Why reach out now**: specific to this package's growth inflection point
+- **Suggested first message**: names the package, its growth, and connects to your product context
+
+## Cost Per Run
+
+- npm Downloads API: free, no auth, no rate limit concerns
+- npm Registry API: free, no auth
+- GitHub API: free (60 req/hr unauthenticated, 5000/hr with token)
+- AI analysis: uses the model already running the skill; no additional cost
+- Total: free
+
+## Standalone Script
+
+Run the data fetching step directly from the terminal without Claude. Useful for scheduled jobs, CI pipelines, or exploring data before generating lead briefs.
+
+```bash
+# Basic usage
+python3 scripts/fetch.py esbuild zod @hono/hono
+
+# With product context
+python3 scripts/fetch.py esbuild zod --context "We build a TypeScript DX platform"
+
+# From a file (one package per line)
+python3 scripts/fetch.py --file packages.txt --output results.json
+
+# Print to stdout
+python3 scripts/fetch.py esbuild zod --stdout | jq '.summary'
+```
+
+The script handles Steps 3 to 5 (download fetch, velocity scoring, maintainer enrichment) and writes a JSON file. Open that file with Claude and ask: "Generate lead briefs from this npm data."
+
+```bash
+GITHUB_TOKEN=your_token python3 scripts/fetch.py esbuild zod @hono/hono
+```
+
+Script output fields per package:
+
+- `velocity_score`, `growth_pct`, `recent_4_avg`, `prior_4_avg`, `tier`
+- `weeks`: array of 12 weekly download counts, oldest to newest
+- `profile.description`, `profile.keywords`, `profile.npm_maintainers`
+- `profile.github_users`: array with `username`, `twitter_username`, `followers`, `bio`, `company`
+
+## Project Structure
+
+```
+npm-downloads-to-leads/
+├── SKILL.md
+├── README.md
+├── .env.example
+├── scripts/
+│   └── fetch.py           standalone data fetcher (Steps 3 to 5, no Claude needed)
+├── evals/
+│   └── evals.json
+└── references/
+    ├── velocity-scoring.md
+    └── outreach-timing.md
+```
+
+## License
+
+MIT