@opendirectory.dev/skills 0.1.44 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/registry.json

@@ -217,6 +217,14 @@
     "version": "0.0.1",
     "path": "skills/npm-downloads-to-leads"
   },
+  {
+    "name": "oss-launch-kit",
+    "description": "Higher-level OSS launch orchestrator that analyzes repos, selects channels, and coordinates launch plans.",
+    "tags": [],
+    "author": "OpenDirectory",
+    "version": "0.2.0",
+    "path": "skills/oss-launch-kit"
+  },
   {
     "name": "outreach-sequence-builder",
     "description": "Takes a buying signal and generates a personalized multi-channel outreach sequence across email, LinkedIn, and phone.",

package/skills/oss-launch-kit/.env.example

@@ -0,0 +1,2 @@
+# GitHub API access for repo context fetching
+GITHUB_TOKEN=

package/skills/oss-launch-kit/PRD.md

@@ -0,0 +1,122 @@
+# oss-launch-kit PRD
+
+## Overview
+`oss-launch-kit` is an advanced OpenDirectory skill that turns a public GitHub repo URL into a grounded launch package for open-source projects.
+
+The v1 output is a single Markdown document containing:
+- executive summary & launch readiness
+- Launch Readiness Fix Plan
+- soft launch strategy (for medium readiness)
+- coordinated launch timeline (for medium/high readiness)
+- channel strategy hooks (Show HN, PH, Reddit, X)
+- explicit handoffs to specialized skills ([!TIP])
+- full confidence notes & assumptions
+
+## Problem Statement
+Open-source maintainers often know how to build and ship the product, but not how to package it for launch. The hardest part is not writing generic marketing copy; it is translating a repo’s real signal into channel-specific content that is honest, specific, and usable.
+
+This skill solves that by taking one repo URL and generating launch assets that a maintainer can post or adapt with minimal editing.
+
+### Why a repo URL is enough for v1
+A GitHub repo already exposes the highest-signal inputs for launch copy:
+- repository name and description
+- README content
+- topics and homepage
+- primary language
+- stars, forks, license
+- optional release metadata
+
+That is enough to infer what the project is, who it is for, what problem it solves, and what makes it worth announcing. V1 does not need deeper scraping or user-provided briefs.
+
+### Why this is better scoped than the previous FAQ attempt
+The closed `api-error-to-faq-builder` idea tried to infer support content from noisy inputs and broad product repos, which made hallucination and generic output more likely.
+
+`oss-launch-kit` is narrower in three ways:
+- input is a single public repo with structured metadata
+- output is a bounded launch kit, not open-ended support material
+- the skill can stay grounded in the repo’s own README and metadata
+
+That makes the challenge more mergeable and easier to validate.
+
+## Goals
+- Analyze repo context to determine appropriate launch channels and project maturity.
+- Act as a Phase 0 orchestrator: decide *if* and *how* to launch, not to write every post.
+- Provide a prioritized, actionable Launch Readiness Fix Plan for missing signals.
+- Generate strategic hooks and positioning for key channels.
+- Provide a coordinated, day-by-day launch strategy.
+- Minimize hallucinations and unsupported claims.
+- Explicitly flag low-confidence areas when the README or metadata is sparse.
+
+## Non-Goals
+- No direct posting to Product Hunt, Reddit, HN, or X.
+- No scraping of private sites.
+- No invented traction, testimonials, users, or metrics.
+- No attempt to infer hidden business strategy or audience beyond available evidence.
+
+## User Input Contract
+### Required CLI input
+- `--repo-url <url>`: public GitHub repository URL.
+
+### Optional CLI inputs
+- `--output <path>`: write Markdown to a file instead of stdout.
+  - default: `launch-kit.md`
+
+### Environment variables
+- `GITHUB_TOKEN`: optional, used to raise GitHub API rate limits.
+- `OPENAI_API_KEY` or equivalent model credentials only if the implementation uses a hosted LLM.
+
+### Validation rules
+- Repo URL must resolve to a public GitHub repository.
+- Invalid or private repos should fail with a clear message.
+- If README is missing, the skill should continue with lowered confidence and flag the gap.
+
+## Output Contract
+The output must be a single Markdown document with stable headings.
+
+### Required structure
+1. `# Launch Orchestrator for <repo>`
+2. `## Executive Summary & Launch Readiness` (with readiness score and CAUTION nodes)
+3. `## Launch Readiness Fix Plan` (Condition: Readiness is LOW/MEDIUM)
+4. `## Soft Launch Strategy` (Condition: Readiness is MEDIUM)
+5. `## Coordinated Launch Timeline` (Condition: Readiness is MEDIUM/HIGH)
+6. `## Channel Strategy & Positioning` (Condition: Readiness is HIGH)
+7. `## Full Confidence Notes & Assumptions`
+
+### Content expectations
+- Executive Summary cites only verified repo facts and computed project maturity.
+- Fix Plan provides prioritized, actionable steps (e.g., "Add Quickstart", "Add License").
+- Channel Strategy provides hooks, taglines, and niche community targets.
+- Coordinated Launch Timeline is a practical, day-based coordination plan.
+- Integration uses `[!TIP]` handoffs to specialized skills (`producthunt-launch-kit`, `show-hn-writer`, etc.).
+- Low-confidence areas must explicitly list anything inferred rather than verified.
+
+## Data Sources
+### Essential
+- repo name
+- repo description
+- README
+- topics
+- homepage
+- primary language
+- stars
+- forks
+- license
+
+### Optional
+- latest release metadata
+- release notes
+- repo archived/fork status
+- README badges if easily parsed
+
+### Priority order
+1. README
+2. repo description
+3. topics and homepage
+4. language, stars, forks, license
+5. optional release info
+
+## Success Criteria
+- Launch assets feel specific to the repo, not generic.
+- No fabricated claims.
+- The user can use the drafts with light editing.
+- Weak repos still produce honest output with confidence notes.

package/skills/oss-launch-kit/README.md

@@ -0,0 +1,27 @@
+<img src="./hero.png" width="100%" alt="OSS Launch Kit Cover" />
+
+# oss-launch-kit (Orchestrator)
+
+The high-level **OSS Launch Orchestrator** for GitHub repositories. It serves as the strategic entry point that analyzes your repo and coordinates a multi-channel launch plan.
+
+## Features
+
+- **Project Analysis**: Differentiates between CLI tools, libraries, apps, and templates.
+- **Enhanced Readiness**: Checks for installation guides, usage examples, license, and metadata.
+- **Channel Orchestration**: Recommends the best channels (PH, HN, Reddit, X) based on fitness.
+- **Skill Hand-offs**: Provides hooks and pointers to `show-hn-writer`, `producthunt-launch-kit`, and `reddit-post-engine`.
+- **Honest Feedback**: Explicitly flags low-readiness repos and recommends documentation sprints.
+
+## Usage
+
+```bash
+# Generate a launch strategy and checklist for a repo
+python scripts/run.py --repo-url https://github.com/owner/repo
+```
+
+## Differentiation
+
+Unlike single-channel generators, `oss-launch-kit` acts as the **Root Strategy Layer**:
+1. It tells you **if and where** you should launch.
+2. It provides a **timed checklist** for coordination.
+3. It hands off to **specialized skills** for channel-specific drafting.

package/skills/oss-launch-kit/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: oss-launch-kit
+description: Higher-level OSS launch orchestrator that analyzes repos, selects channels, and coordinates launch plans.
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 0.2.0
+---
+
+# OSS Launch Kit (Orchestrator)
+
+The `oss-launch-kit` is the **root orchestration layer** for open-source launches in OpenDirectory. It turns a GitHub repository URL into a grounded, coordinated launch strategy. 
+
+Rather than just writing generic copy, this skill serves as the **Strategic Entry Point**: it evaluates readiness, determines channel fitness (Show HN vs. Product Hunt vs. Reddit), and provides the coordination logic needed to use specialized skills effectively.
+
+## How it works
+
+- **Project Analysis**: Differentiates between CLI tools, libraries, apps, and templates.
+- **Launch Readiness**: Stronger checks for installation guides, examples, and licenses.
+- **Skill Orchestration**: Provides hooks and explicit handoffs to `show-hn-writer`, `producthunt-launch-kit`, and `reddit-post-engine`.
+- **Coordinated Strategy**: A timed checklist for multi-channel launches.
+- **Honest Feedback**: Proactively flags sparse READMEs and recommends documentation sprints.
+
+## When to use
+
+- **Primary Entry Point**: Use this first to map out your launch strategy.
+- **Readiness Assessment**: Determine if your repo is actually ready for high-friction channels.
+- **Skill Orchestration**: Get hooks and handoffs to specialized skills:
+  - `show-hn-writer` (for technical deep-dives)
+  - `producthunt-launch-kit` (for PH assets and badges)
+  - `reddit-post-engine` (for community-specific variants)
+  - `tweet-thread-from-blog` (for Twitter/X threads)
+  - `linkedin-post-generator` (for LinkedIn posts)
+- **Coordinated Strategy**: Get a realistic, timed checklist for multiple platforms.

package/skills/oss-launch-kit/TECHNICAL_DESIGN.md

@@ -0,0 +1,187 @@
+# oss-launch-kit Technical Design
+
+## Architecture Summary
+`oss-launch-kit` should follow the same advanced-skill pattern used elsewhere in this repo:
+- `README.md` for public overview and usage
+- `SKILL.md` for operational instructions
+- `.env.example` for required environment variables
+- `scripts/` for executable orchestration
+- `references/` for design guides, templates, and frameworks (note: these are for design-time reference, the current scripts use hardcoded templates for maximum performance and stability).
+- `evals/` for validation cases
+
+The implementation should be a two-stage pipeline:
+
+1. repo context -> structured product brief
+2. product brief -> channel-specific launch assets
+
+This mirrors the repo’s stronger launch skills and keeps the generation grounded.
+
+## Stage A: Repo Context -> Product Brief
+### Responsibility
+Convert raw GitHub repo data into a normalized brief that captures only what can be supported by evidence.
+
+### Inputs
+- repo metadata JSON
+- README text
+- optional release metadata
+
+### Output schema
+```json
+{
+  "repo_name": "string",
+  "one_line_summary": "string",
+  "project_type": "string",
+  "launch_readiness": {
+    "score": "low | medium | high",
+    "signals": "object",
+    "fix_plan": "list"
+  },
+  "audience": "string",
+  "problem_solved": "string",
+  "value_proposition": "string",
+  "key_proof_points": "list",
+  "key_features": "list",
+  "links": "object",
+  "confidence": "low | medium | high",
+  "assumptions": "list",
+  "channel_fitness": "object"
+}
+```
+
+### Failure cases
+- README is sparse or missing.
+- Repo description conflicts with README.
+- Audience is implied, not explicit.
+
+### Hallucination controls
+- Treat README and repo metadata as the only factual source.
+- Allow `unknown` or empty values when evidence is missing.
+- Store evidence alongside every major inference.
+
+## Stage B: Product Brief -> Launch Assets
+### Responsibility
+Use the brief to generate channel-specific drafts with channel rules applied.
+
+### Inputs
+- product brief JSON
+- channel rules from `references/channel_rules.md`
+- output template from `references/output_template.md`
+
+### Output
+- final Markdown launch kit
+
+### Failure cases
+- assets become generic
+- channel tone drifts away from platform norms
+- unsupported claims leak into drafts
+
+### Hallucination controls
+- no new facts beyond the brief
+- confidence notes carry through to final output
+- use explicit `[!TIP]` handoffs to specialized skills
+- suppress aggressive channels for unready repos
+
+## Channel Rules
+### Show HN
+- direct and technical
+- no hype language
+- no fake performance claims
+- plain title alternative only if useful
+
+### Product Hunt
+- include tagline and description
+- maker comment should sound human and specific
+- avoid invented social proof
+- do not exceed practical PH length constraints
+
+### Reddit
+- generate niche suggestions based on repo tags and description
+- include a warning to verify subreddit rules before posting
+- prioritize feedback-first communities for early-stage repos
+
+### Twitter/X
+- concise thread
+- each tweet should carry one idea
+- use evidence-based language only
+- no spammy hashtags
+
+## File Structure
+```text
+skills/oss-launch-kit/
+├── README.md
+├── SKILL.md
+├── .env.example
+├── PRD.md
+├── TECHNICAL_DESIGN.md
+├── evals/
+│   └── evals.json
+├── references/
+│   ├── launch_framework.md
+│   ├── channel_rules.md
+│   └── output_template.md
+└── scripts/
+    ├── run.py
+    ├── fetch_repo_context.py
+    ├── build_product_brief.py
+    └── generate_assets.py
+```
+
+## Implementation Phases
+### Phase 1: Skeleton and docs
+- Create folder structure and planning docs.
+- Acceptance: skill folder exists with PRD, technical design, and reference stubs.
+- Risk: too much upfront design before validation.
+
+### Phase 2: GitHub fetcher
+- Implement repo URL parsing and GitHub API fetches.
+- Acceptance: metadata and README resolve for public repos.
+- Risk: API rate limits and README format variance.
+
+### Phase 3: Brief builder
+- Turn repo context into structured brief JSON.
+- Acceptance: evidence-backed fields and explicit confidence notes.
+- Risk: over-inference from weak READMEs.
+
+### Phase 4: Asset generation
+- Produce final channel drafts from the brief.
+- Acceptance: all outputs obey channel rules and remain grounded.
+- Risk: repetitive or generic copy.
+
+### Phase 5: Testing on 3 public repos
+- Test on a dev tool repo, a library/package repo, and a weak README repo.
+- Acceptance: all three produce usable outputs with honest low-confidence handling.
+- Risk: one-size-fits-all messaging.
+
+### Phase 6: README polish and PR prep
+- Align README with final behavior and usage.
+- Acceptance: maintainer can review quickly and see the merge value.
+
+## Testing Strategy
+### Test set
+- one dev-tool repo with strong README
+- one library/package repo with clear positioning
+- one repo with a weak README
+
+### Good output means
+- factual repo summary
+- specific audience and problem framing
+- channel-appropriate tone
+- no fabricated proof points
+- explicit assumptions where evidence is thin
+
+## Risks and Mitigations
+- Weak README: keep output short, honest, and confidence-tagged.
+- Misleading repo description: prefer README over description.
+- Unclear audience: provide one primary hypothesis and note ambiguity.
+- Generic launch copy: require evidence fields before drafting assets.
+- Wrong subreddit suggestions: mark them as suggestions, not endorsements.
+- Hallucinated claims: final validation pass checks every claim against brief evidence.
+
+## PR Plan
+- Branch: `skill/oss-launch-kit`
+- PR title: `feat(skill): add oss-launch-kit`
+- Commit sequence:
+  - `docs(skill): add oss-launch-kit prd and technical design`
+  - `docs(skill): add oss-launch-kit reference docs and scaffold`
+  - `feat(skill): implement repo context fetcher`
+  - `feat(skill): implement brief builder and launch asset generation`

package/skills/oss-launch-kit/evals/cli-cli.full.md

@@ -0,0 +1,49 @@
+# Launch Orchestrator for cli/cli
+
+
+
+## Executive Summary & Launch Readiness
+
+**Project Maturity**: HIGH
+
+
+
+## Coordinated Launch Timeline
+
+- [ ] Day 1: Show HN
+- [ ] Day 3: Reddit
+- [ ] Day 5: Product Hunt
+
+
+
+This is identified as a **tool** with **High Launch Readiness**.
+- **Show HN**: High fit. Technical communities appreciate technical tools and libraries.
+- **Product Hunt**: Not recommended yet. Pure libraries or early-stage tools often struggle on PH without a UI/Demo.
+
+
+
+## Channel Strategy & Positioning
+### [Show HN] - Fit: HIGH
+**Positioning**: Focus on technical implementation and 'why I built this'.
+**Recommended Title**: `Show HN: cli/cli - GitHub’s official command line tool`
+**Hook**: I built cli/cli because I wanted a clearer way to serve data/infra users who need github’s official command line tool.
+> [!TIP]
+> Use `show-hn-writer` for a full submission draft.
+
+### [Reddit] - Fit: MEDIUM
+**Niche Strategy**: Engage r/devtools, r/opensource, r/commandline with feedback-first posts.
+**Key Hook**: GitHub’s official command line tool
+> [!TIP]
+> Use `reddit-post-engine` to generate subreddit-specific variants.
+
+### [Twitter/X] - Fit: HIGH
+**Thread Strategy**: Start with the problem of GitHub’s official command line tool.
+**Hook**: I built `cli/cli` to solve github’s official command line tool.
+> [!TIP]
+> Use `tweet-thread-from-blog` or `linkedin-post-generator` to expand this hook.
+
+
+
+## Full Confidence Notes & Assumptions
+
+- Confidence: high

package/skills/oss-launch-kit/evals/evals.json

@@ -0,0 +1,44 @@
+[
+  {
+    "repo": "cli/cli",
+    "full": "cli-cli.full.md",
+    "description": "Strong CLI tool",
+    "expectations": [
+      "**Project Maturity**: HIGH",
+      "Show HN fitness is HIGH",
+      "Includes Channel Strategy & Positioning section",
+      "Timeline includes Show HN"
+    ]
+  },
+  {
+    "repo": "octocat/Hello-World",
+    "full": "octocat-hello-world.full.md",
+    "description": "Weak project",
+    "expectations": [
+      "**Project Maturity**: LOW",
+      "> [!CAUTION]",
+      "This project is not launch-ready yet",
+      "Show HN and Product Hunt are NOT recommended",
+      "Channel Strategy & Positioning section is absent",
+      "Coordinated Launch Timeline is absent"
+    ]
+  },
+  {
+    "repo": "pydantic/pydantic",
+    "full": "pydantic-pydantic.full.md",
+    "description": "Mature library",
+    "expectations": [
+      "**Project Maturity**: HIGH",
+      "Show HN fitness is HIGH"
+    ]
+  },
+  {
+    "repo": "vercel/next.js",
+    "full": "vercel-next-js.full.md",
+    "description": "Polished framework",
+    "expectations": [
+      "**Project Maturity**: HIGH",
+      "Product Hunt fitness is HIGH"
+    ]
+  }
+]

package/skills/oss-launch-kit/evals/octocat-hello-world.full.md

@@ -0,0 +1,53 @@
+# Launch Orchestrator for octocat/Hello-World
+
+
+
+## Executive Summary & Launch Readiness
+
+**Project Maturity**: LOW
+
+
+> [!WARNING]
+
+> **Launch Readiness is Low.** This project currently looks like a toy or template repo.
+
+> Recommended next steps: improve README, add installation examples, and fix core metadata.
+
+
+
+- Confidence: low
+- Assumptions: Audience inferred from repo metadata only.; No clear installation instructions found in README
+Edit before posting: this repo context is sparse, so tighten the copy after reviewing the README and repo signals.
+
+
+
+## Coordinated Launch Timeline
+
+- [ ] Day 1-3: Documentation Sprint (Fix README, add examples)
+- [ ] Day 4: Ask for feedback on Reddit (r/opensource or relevant niche)
+- [ ] Day 5: Soft launch on Twitter/X to gathered followers
+- [ ] Day 7+: Re-evaluate for Show HN/PH once README is robust
+
+
+
+This is identified as a **project** with **Low Launch Readiness**.
+- **Show HN**: Not recommended yet. Repository context might be too thin for Hacker News.
+- **Product Hunt**: Not recommended yet. Pure libraries or early-stage tools often struggle on PH without a UI/Demo.
+- **Reddit**: OK for feedback only. Avoid a 'launch' post; ask for specific technical reviews instead.
+
+
+
+## Channel Strategy & Positioning
+### [Twitter/X] - Fit: HIGH
+**Thread Strategy**: Start with the problem of My first repository on GitHub!.
+**Hook**: I built `octocat/Hello-World` to solve my first repository on github!.
+> [!TIP]
+> Use `tweet-thread-from-blog` or `linkedin-post-generator` to expand this hook.
+
+
+
+## Full Confidence Notes & Assumptions
+
+- Confidence: low
+- Assumptions: Audience inferred from repo metadata only.; No clear installation instructions found in README
+Edit before posting: this repo context is sparse, so tighten the copy after reviewing the README and repo signals.