@opendirectory.dev/skills 0.1.15 → 0.1.17

package/skills/show-hn-writer/SKILL.md

@@ -1,303 +1,302 @@
 ---
 name: show-hn-writer
-description: ''
+description: 'Draft a Show HN post backed by real HN performance data. Uses observed patterns from 250 top HN posts to maximise score.'
 compatibility: [claude-code, gemini-cli, github-copilot]
-author: OpenDirectory
-version: 1.0.0
+author: Varnan / Paras Madan
+version: 2.0.0
+data-source: 250 top HN posts scraped April 18 2026
 ---
 
-# Show HN Writer
+# Show HN Writer — Data-Backed Edition
 
-Draft a Show HN post title and body that follows the unwritten rules of Hacker News: specific, honest, first-person, no marketing.
+This skill drafts HN posts using patterns extracted from 250 real top-ranking posts.
+Every rule below comes from observed data, not convention.
 
 ---
 
-**Critical rule:** Never use marketing language. No "game-changing", "revolutionary", "powerful", "robust", "seamless", "innovative", "best-in-class", or "streamline". Never write in third person about the product. Never ask readers to upvote, share, or check out other links.
+## What the data says (internalize this before writing anything)
 
----
+These are the findings from 250 top HN posts scraped April 18 2026. They override
+any received wisdom about HN writing.
+
+**Title length is the single strongest predictor of score.**
+- Under 40 chars: avg 248 pts (n=82)
+- 40–59 chars:    avg 192 pts (n=68)
+- 60–79 chars:    avg 150 pts (n=91)
+- 80+ chars:      avg 131 pts (n=9)
+Default target: under 40 characters. Hard ceiling: 60.
 
-## Step 1: Gather Project Context
+**Body text does not affect score.**
+90% of posts had no body. With-body avg: 189. Without-body avg: 193. Statistically
+identical. A body is only worth writing if you have genuinely interesting technical
+detail that won't fit in a title. Never write a body to pad credibility.
 
-Check if the user has already provided enough context to write the post. You need:
+**Show HN prefix suppresses score.**
+Show HN posts averaged 94 pts vs 186+ for plain statements. The label signals
+"I want feedback on my thing" which triggers a more skeptical read. Only use "Show HN:"
+when the project is genuinely novel. Always offer a plain-title alternative.
 
-- What the project does (one technical sentence)
-- What problem it solves and who has that problem
-- Why the builder made it (the honest story: scratch your own itch, side project, weekend hack)
-- What makes it technically interesting or different from existing solutions
-- Current state: alpha, beta, open source, free, paid, solo project, team
+**First-person titles outperform anonymous statements.**
+First-person ("I…", "My…", "We…"): avg 291 pts (n=9).
+Plain statement: avg 186 pts (n=126).
+If the builder's perspective is part of the story, lead with it.
 
-If any of these are missing, ask in a single message:
+**Questions generate comments more than upvotes.**
+Question titles avg ratio of comments-to-score above 1.0×. Best for discussions,
+not for raw score. Ask the user which they're optimising for before writing.
 
-"To write your Show HN post, I need a few details:
-1. What does [project name] do, technically? (one sentence)
-2. Who has the problem it solves? (be specific: 'developers who...' not 'anyone who...')
-3. Why did you build it? (the real story)
-4. What's technically interesting about how it works?
-5. What's the current state: open source? free? alpha?"
+**Themes that consistently outperform:**
+- Security / backdoor / breach stories: avg 308 pts
+- Privacy / surveillance / data stories: avg 282 pts
+- AI / LLM releases: avg 266 pts (42 posts — largest category)
+- Open source releases: avg 485 pts (small n, but strong signal)
 
-Do not proceed until you have answers to all five.
+**The highest-scoring titles share one trait: they are stories, not topics.**
+"Someone bought 30 WordPress plugins and planted a backdoor in all of them" — 1192 pts.
+"Google broke its promise to me – now ICE has my data" — 1688 pts.
+A topic is "WordPress plugin security". A story has an actor, an action, and stakes.
 
 ---
 
-## Step 2: Read Context Files (if available)
+## Step 1: Ask the user one question before anything else
 
-Check for project context files before asking:
+Before drafting, ask:
 
-```bash
-ls README.md 2>/dev/null && echo "README found"
-ls CLAUDE.md 2>/dev/null && echo "CLAUDE.md found"
-ls package.json 2>/dev/null && echo "package.json found"
-```
+"Two quick questions:
+1. Are you optimising for **score** (reach) or **comments** (discussion)?
+2. What does the project do — one sentence, technical, no adjectives?"
 
-If README.md exists, read the first 100 lines. Extract: what it does, tech stack, how to run it, any stated motivation.
-
-If you find enough context in the files, skip the Step 1 questions entirely or ask only what's missing.
+Do not proceed until you have both answers.
 
 ---
 
-## Step 3: Draft the Title
+## Step 2: Determine the right post type
 
-The Show HN title must start with "Show HN:": this is required, not optional.
+Based on the project and goal, decide which format to use:
 
-**Title format A: Product-First:**
-```
-Show HN: [Project Name] – [what it does in plain English]
-```
+**Plain title (recommended default)**
+No prefix. Just what it is or what happened. Highest avg score.
+Use when: sharing a release, article, tool, or event.
 
-**Title format B: Outcome-Focused:**
-```
-Show HN: [Project Name] – [specific outcome] for [specific person]
-```
+**Show HN: prefix (use sparingly)**
+Use only when: the project is a working demo, the builder is present to answer
+questions, and the technical implementation is the interesting part.
+Avg score is low (94), but it signals authenticity when the project is genuinely novel.
+Always also draft a plain-title alternative for comparison.
+
+**Ask HN: prefix**
+Use when: the goal is discussion, not promotion. Avg engagement ratio > 1.0×.
+Best for "who is using X?" or "should I do Y?" posts.
 
-**Title rules:**
-- 60-80 characters total (including "Show HN: ")
-- No exclamation marks
-- No adjectives ("fast", "simple", "easy", "powerful") unless they are literal technical specs
-- The dash is an en dash (–), not a hyphen (-)
-- No trailing punctuation
-- Describe what it does, not what it could do for someone
-
-Good examples:
-- `Show HN: Zulip – Group chat that threads every conversation`
-- `Show HN: Lite XL – A lightweight text editor written in C and Lua`
-- `Show HN: Datasette – Instantly publish SQLite databases to the web`
-
-Bad examples (never write these):
-- `Show HN: The most powerful tool for managing your workflow` (adjective, no specifics)
-- `Show HN: Check out my new project!` (no description, no name)
-- `Show HN: I built a thing for developers` (vague)
-
-Draft three title variants:
-1. Product-First format
-2. Outcome-Focused format
-3. Technical-Angle format (lead with the interesting technical decision)
+**Tell HN: prefix**
+Whistleblowing, accountability, or disclosure. One data point at 819 pts.
+Only use if the post is factual, verifiable, and the builder is named.
 
 ---
 
-## Step 4: Draft the Body
+## Step 3: Draft the title
 
-The Show HN body is a builder talking to peers. It is not a product description. It is not a pitch.
+**The title is the entire post.** Treat the body as optional.
 
-**Structure:**
+Rules derived from data:
+- Target under 40 characters. Every 20 chars over that costs roughly 30 avg points.
+- Write a story, not a category. Actor + action + stakes beats noun phrases.
+- First person ("I…") adds ~100 pts avg vs plain statement when builder perspective matters.
+- No marketing adjectives. Not "fast", "simple", "powerful", "lightweight" unless
+  it is a literal spec (e.g. "35B-A3B" is a spec, "powerful" is not).
+- Specificity beats generality. "30 WordPress plugins" beats "popular CMS plugins".
+- Year in brackets signals classic worth reading: (2008), (1956). Use when linking
+  older content that has aged well.
+- En dash (–) for subtitle format: "Product Name – what it does". Not a hyphen (-).
 
-**Opening line:** One sentence, first-person, what you built. Not "Introducing X" or "X is a tool that". Just: "I built [X] because [reason]." or "For the past [N] months I've been working on [X]."
+Draft three variants:
+1. Shortest possible (aim for under 35 chars) — strip everything non-essential
+2. Story angle — actor + action + stakes
+3. Technical angle — lead with the interesting engineering decision
 
-**The why:** Two to four sentences on why you made it. Was it a problem you had personally? Something frustrating at work? A technical curiosity? Be specific and honest. If you built it for fun, say so.
+Then apply the length test: count chars on each. Flag any over 60.
 
-**How it works:** Three to six sentences on the technical approach. This is what HN readers care about. What's the interesting engineering decision? What did you learn? What tradeoff did you make and why? Name the specific technology choices.
+---
+
+## Step 4: Decide whether to write a body
 
-**Current state:** One to two sentences. Is it open source? Free? Alpha? Looking for beta users? Solo project or team? How long have you been working on it?
+Ask yourself: does the technical implementation have a detail that cannot fit in
+the title and that HN engineers would find genuinely interesting?
 
-**Invitation:** One sentence to close. Invite feedback, questions, or criticism. Never ask for upvotes or shares. Examples: "Would love to hear what you think." / "Happy to answer questions about the implementation." / "Criticism welcome: still early days."
+If yes: write a body (see Step 5).
+If no: stop at the title. No body is better than a padded body.
 
-**Body rules:**
-- Write in first person throughout
-- 150-350 words total
-- No bullet points, no headers, no bold text
-- No links in the body (the URL goes in the submission, not the body)
-- No asking people to sign up, follow, or subscribe
-- No comparison tables or feature lists
-- If there's a demo or GitHub link, do NOT add it to the body: it goes in the URL field of the submission
+The data shows bodies do not increase score. The only reason to write one is if
+the implementation is interesting enough that engineers will ask "how does this work?"
+and you want to pre-answer that.
 
 ---
 
-## Step 5: Summarize Submission with Gemini
-
-Write a Gemini request to evaluate the draft and check for Show HN anti-patterns:
-
-```bash
-cat > /tmp/show-hn-review-request.json << 'ENDJSON'
-{
-  "system_instruction": {
-    "parts": [{
-      "text": "You are a longtime Hacker News member reviewing a Show HN post draft. Your job is to catch anything that will hurt its reception: marketing language, vague descriptions, third-person writing, requests for upvotes/shares, adjectives without specifics, titles over 80 characters. For each issue found, state: the exact phrase, why it hurts, and a specific suggested replacement. If the post passes, say 'Passes review.' Output only the review: no commentary, no preamble. Do not use em dashes. Do not praise the post."
-    }]
-  },
-  "contents": [{
-    "parts": [{
-      "text": "DRAFT_POST_HERE"
-    }]
-  }],
-  "generationConfig": {
-    "temperature": 0.2,
-    "maxOutputTokens": 1024
-  }
-}
-ENDJSON
-
-curl -s -X POST \
-  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d @/tmp/show-hn-review-request.json \
-  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
-```
+## Step 5: Write the body (only if Step 4 said yes)
 
-Replace `DRAFT_POST_HERE` with the full title and body text.
+Structure — keep it tight:
 
-**If GEMINI_API_KEY is not set:** Skip this step. Proceed with the manual self-QA in Step 6.
+**Line 1:** One sentence. What you built and why. First person.
+Not "Introducing X." Not "X is a tool that." Just: "I built X because Y."
 
----
+**Lines 2–4:** The real reason. Honest. Specific. Was it a problem you hit yourself?
+Something frustrating at work? A curiosity? "I was annoyed that..." is better than
+"Developers often struggle with...". The builder's voice is the point.
 
-## Step 6: Self-QA
+**Lines 5–8:** How it actually works. This is what HN reads for.
+Name the specific technology choices. State the tradeoffs you made and why.
+One interesting engineering decision is worth more than a feature list.
 
-Before presenting the final output, check each item:
+**Line 9:** Current state in one sentence. Open source? Free? Alpha? Solo?
+How long you've been working on it.
 
-**Title checks:**
-- [ ] Starts with exactly "Show HN:" (capital H, capital N, colon, space)
-- [ ] 60-80 characters total
-- [ ] Contains no marketing adjectives
-- [ ] Describes what the product does, not what it will do for someone
-- [ ] No exclamation marks
+**Line 10:** One closing sentence inviting feedback or questions.
+"Happy to answer questions about the implementation." / "Criticism welcome."
+Never ask for upvotes, shares, or sign-ups.
 
-**Body checks:**
-- [ ] Opens in first person ("I built...", "For the past N months...", "I've been working on...")
-- [ ] 150-350 words
-- [ ] Contains at least one technical detail (language, approach, architecture decision)
-- [ ] No links in the body text
-- [ ] Closes with an invitation for feedback, not a call to action
-- [ ] No bullet points or headers
-- [ ] No marketing words: "game-changer", "revolutionary", "powerful", "robust", "seamless", "innovative", "best-in-class", "streamline", "leverage", "transform"
-
-If any check fails, fix before presenting.
+Hard rules:
+- 150–300 words. Under 200 is usually better.
+- First person throughout.
+- No bullet points. No headers. No bold.
+- No links in body. URL goes in the submission field.
+- No marketing words: game-changing, revolutionary, powerful, robust, seamless,
+  innovative, best-in-class, streamline, leverage, transform, cutting-edge.
 
 ---
 
-## Step 7: Post to Hacker News (Optional)
-
-If `HN_USERNAME` and `HN_PASSWORD` are set in the environment, offer to post directly.
+## Step 6: Self-check before presenting
 
-```bash
-echo "HN_USERNAME: ${HN_USERNAME:-not set}"
-echo "HN_PASSWORD: ${HN_PASSWORD:+set (hidden)}"
-```
+Run through this list. Fix anything that fails before outputting.
 
-If both are set, tell the user: "HN credentials found. Confirm to submit this post directly to Hacker News, or say 'output only' to get the text."
+Title:
+- [ ] Under 60 characters (count them)
+- [ ] No marketing adjectives
+- [ ] Is it a story or a topic? (story = better)
+- [ ] First person if the builder's perspective adds something
+- [ ] No exclamation marks
 
-On confirmation, run the three-step submission:
+Body (if written):
+- [ ] Opens with "I built…" or "For the past N months…"
+- [ ] Contains at least one specific technology name or architecture decision
+- [ ] Under 300 words
+- [ ] No links
+- [ ] Closes with feedback invitation, not call to action
+- [ ] Zero marketing words (check the list in Step 5)
 
-**Step A: Authenticate and get session cookie**
-```bash
-HN_COOKIE=$(curl -s -c /tmp/hn-cookies.txt -b /tmp/hn-cookies.txt \
-  -X POST "https://news.ycombinator.com/login" \
-  -d "acct=${HN_USERNAME}&pw=${HN_PASSWORD}&goto=news" \
-  -D /tmp/hn-headers.txt \
-  -L -o /dev/null -w "%{http_code}")
+Post type:
+- [ ] If using Show HN prefix: is a plain-title alternative also drafted?
+- [ ] If goal is comments: is it a question or divisive framing?
+- [ ] If goal is score: is it a statement, not a question?
 
-# Verify login succeeded (should redirect to news, not back to login)
-grep -c "user?id=${HN_USERNAME}" /tmp/hn-headers.txt > /dev/null 2>&1 \
-  || curl -s -b /tmp/hn-cookies.txt "https://news.ycombinator.com/" \
-     | grep -c "logout" > /dev/null 2>&1 \
-  && echo "Login: success" || echo "Login: failed: check credentials"
-```
+---
 
-If login fails: stop. Tell the user their credentials did not work and present the draft for manual submission instead.
-
-**Step B: Fetch the submission form to get the CSRF token (fnid)**
-```bash
-FNID=$(curl -s -b /tmp/hn-cookies.txt \
-  "https://news.ycombinator.com/submit" \
-  | python3 -c "
-import sys, re
-html = sys.stdin.read()
-m = re.search(r'name=\"fnid\" value=\"([^\"]+)\"', html)
-print(m.group(1) if m else 'NOT_FOUND')
-")
-echo "fnid: $FNID"
-```
+## Step 7: Present output
 
-If fnid is NOT_FOUND: stop. HN may have changed their form structure. Present the draft for manual submission.
+Format exactly as follows. No commentary before or after.
 
-**Step C: Submit the post**
+```
+## HN Post
 
-For a URL submission (project URL):
-```bash
-curl -s -b /tmp/hn-cookies.txt \
-  -X POST "https://news.ycombinator.com/r" \
-  -d "title={ENCODED_TITLE}&url={ENCODED_URL}&fnid=${FNID}&fnop=submit-page" \
-  -D /tmp/hn-submit-headers.txt \
-  -L -o /tmp/hn-submit-response.html
+### Recommended title
+[title — the shortest, strongest variant]
 
-# Check for success: HN redirects to the post or to newest
-grep -E "item\?id=|/newest" /tmp/hn-submit-headers.txt \
-  && echo "Submission: success" || echo "Submission: check manually"
-```
+### Alternative titles
+1. [variant 2]
+2. [variant 3]
 
-For a text post (no URL, just body):
-```bash
-curl -s -b /tmp/hn-cookies.txt \
-  -X POST "https://news.ycombinator.com/r" \
-  -d "title={ENCODED_TITLE}&text={ENCODED_BODY}&fnid=${FNID}&fnop=submit-page" \
-  -D /tmp/hn-submit-headers.txt \
-  -L -o /tmp/hn-submit-response.html
-```
+---
 
-**After submission:**
-1. Extract the post URL from the redirect headers
-2. Tell the user: "Posted: https://news.ycombinator.com/item?id=[ID]"
-3. Remind them: "Reply to comments within the first two hours. Do not reshare the link for 24 hours: HN penalizes vote rings."
+### Body
+[body text, or "Not recommended — title is sufficient." if Step 4 said no body]
 
-**If any step fails:** Clean up cookie file (`rm -f /tmp/hn-cookies.txt`) and present the draft for manual submission. Do not retry automatically.
+---
 
-```bash
-# Always clean up credentials from disk after the session
-rm -f /tmp/hn-cookies.txt /tmp/hn-headers.txt /tmp/hn-submit-headers.txt /tmp/hn-submit-response.html
+### Notes
+- Goal: [score / comments] — based on user's answer in Step 1
+- Post type used: [plain / Show HN / Ask HN / Tell HN]
+- Title length: [N chars]
+- Best time to post: Tuesday–Thursday, 8–10 AM US Eastern
+- After posting: respond to every comment in the first two hours
+- Do not share the link elsewhere for 24 hours — HN penalises vote rings
 ```
 
-If `HN_USERNAME` or `HN_PASSWORD` is not set: skip this step entirely and proceed to Step 8.
-
 ---
 
-## Step 8: Present Output
-
-Present in this order:
+## Step 8: Optional — scrape current top HN posts for context
 
-```
-## Show HN Post
+If the user wants to check whether similar posts have been submitted recently,
+or wants to see what is performing in their category right now, run the scraper:
 
-### Recommended Title
-Show HN: [title]
+```python
+import requests
+from concurrent.futures import ThreadPoolExecutor
 
-### Alternative Titles
-1. Show HN: [variant 1]
-2. Show HN: [variant 2]
+HN_API = "https://hacker-news.firebaseio.com/v0"
 
----
+def fetch_item(id_):
+    try:
+        r = requests.get(f"{HN_API}/item/{id_}.json", timeout=10)
+        return r.json() if r.ok else None
+    except Exception:
+        return None
 
-### Body
+ids = requests.get(f"{HN_API}/topstories.json").json()[:250]
+with ThreadPoolExecutor(max_workers=20) as ex:
+    items = [i for i in ex.map(fetch_item, ids) if i]
 
-[post body text]
+# Filter by keyword relevant to the user's project
+keyword = "YOUR_KEYWORD_HERE"
+matches = [i for i in items if keyword.lower() in i.get("title","").lower()]
 
----
+for i, item in enumerate(matches, 1):
+    score = item.get("score", 0)
+    title = item.get("title", "")
+    by = item.get("by", "")
+    print(f"{i:>2}. [{score:>4}pts] {title} — {by}")
 
-### Submission Notes
-- URL field: [project URL or GitHub URL]
-- Best time to post: Tuesday to Thursday, 8–10 AM US Eastern
-- After posting: Respond to every comment in the first two hours
-- Do not share the link elsewhere for the first 24 hours: HN flags vote rings
+print(f"\nTotal matching: {len(matches)}")
 ```
 
-Do not add commentary about the post. Present the output, then stop.
-
+Use the results to:
+- Check if a near-identical post was submitted in the last 48 hours (avoid duplication)
+- See which title patterns are landing in this category right now
+- Identify the score floor for this topic area
 
+Results are also appended to hn_log.csv automatically if the full scraper is used.
 
+---
 
+## Reference: observed top performers from dataset
+
+These are real posts from the top 250. Study the title patterns.
+
+Score | Title
+------|-------
+1941  | Claude Opus 4.7
+1688  | Google broke its promise to me – now ICE has my data
+1244  | Qwen3.6-35B-A3B: Agentic coding power, now open to all
+1192  | Someone bought 30 WordPress plugins and planted a backdoor in all of them
+1141  | DaVinci Resolve – Photo
+990   | Codex for almost everything
+982   | Stop Flock
+909   | A new spam policy for "back button hijacking"
+893   | GitHub Stacked PRs
+819   | Tell HN: Fiverr left customer files public and searchable
+668   | I wrote to Flock's privacy contact to opt out of their domestic spying program
+619   | Measuring Claude 4.7's tokenizer costs
+561   | God sleeps in the minerals
+503   | Want to write a compiler? Just read these two papers (2008)
+
+Best Show HN titles (by score):
+341  | Show HN: Smol machines – subsecond coldstart, portable virtual machines
+199  | Show HN: PanicLock – Close your MacBook lid disable TouchID → password unlock
+187  | Show HN: Every CEO and CFO change at US public companies, live from SEC
+177  | Show HN: I made a calculator that works over disjoint sets of intervals
+152  | Show HN: MacMind – A transformer neural network in HyperCard on a 1989 Macintosh
+
+Highest comment-to-score ratios (for discussion-optimised posts):
+1.91× | Why is IPv6 so complicated?
+1.43× | Ask HN: Building a solo business is impossible?
+1.20× | Ohio prison inmates built computers and hid them in ceiling
+1.13× | Ask HN: Who is using OpenClaw?
+1.05× | The future of everything is lies, I guess: Where do we go from here?