GitHub - JanBussieck/hn-skill: Claude Code skills for HN posting, built on 5 years of front page data. Analyze, score, and optimize your Hacker News submissions.

7 min read Original article ↗

Claude Code skills for optimizing Hacker News posts, built on 5 years of data from top-performing submissions (2021-2026).

What's in the box

Three skills that cover the full lifecycle of an HN submission:

Skill What it does
/hn-optimize Optimize a specific post — headline, timing, content type, submission strategy
/hn-spin Take any content idea and reframe it for the HN audience with a full content outline
/hn-score Score content across 7 dimensions on an 87-point scale with actionable fixes

Install

Clone this repo and the skills are available in any Claude Code session started from this directory:

git clone https://github.com/YOUR_USERNAME/hn-skill.git
cd hn-skill
claude

Or copy the .claude/skills/ directory into your own project.

For global access (all projects), copy to your home directory:

cp -r .claude/skills/hn-* ~/.claude/skills/

The data behind it

These skills aren't vibes-based. They're built on analysis of:

  • Top 31 posts (3,000+ points each) from 2021-2026, including scoring patterns and content types
  • 157,000+ Show HN submissions analyzed for timing breakout rates
  • HN's ranking algorithm: Score = (P-1)^0.8 / (T+2)^1.8 * penalty_factor — including penalty multipliers, flamewar detection, and vote ring thresholds
  • Front page composition data: personal blogs (26%), news (36%), corporate blogs (11%), Show HN (<2%)
  • Domain performance: GitHub (7%+ front page rate), Medium (<3%), self-hosted personal blogs (2.4x better than corporate)

The full research is in research/hn-top-posts-analysis.md.

Example: Optimizing this very repo for HN

We used /hn-spin on this project itself. Here's what it produced:

Suggested headlines by angle

Contrarian Data Take — challenge the assumption that HN success is random:

Show HN: 90% of HN posts get 1-2 points – I built a tool to beat those odds    (74 chars)
Show HN: I reverse-engineered what makes HN posts hit the front page           (72 chars)

Builder's Journey — personal project, show your work:

Show HN: I analyzed 157K HN posts to build an open-source submission optimizer (78 chars)
Show HN: I scraped 5 years of HN data and turned it into a posting strategy    (73 chars)

Deep Technical / Algorithm Exposé — lead with the surprising findings:

Show HN posts need 2.5x the upvotes to rank equally – and other HN secrets     (76 chars)
Your HN post has a 90% chance of dying – here's what the 10% do differently    (75 chars)

Meta / Self-referential — the most provocative, highest risk/reward:

Show HN: I used HN's own data to game HN (and you can too)                     (55 chars)
Show HN: The HN post optimizer that analyzed itself to write this headline      (73 chars)

Why "90% of HN posts get 1-2 points" works

Follows the contrarian-with-evidence archetype ("Google Search Is Dying" got 3,636 points with the same structure). Leads with a specific, surprising statistic. Implies the tool has a solution without making a promise. The number "90%" does the heavy lifting — it's concrete and slightly alarming.

Recommended submission strategy

  • Content type: Show HN + GitHub repo link
  • Timing: Sunday 11:00-16:00 UTC (best breakout window at 12-14%)
  • README: This file serves as the content — no blog post needed since the repo is the product
  • First comment: Post the research methodology and a few surprising findings from the data. Keep it technical, not promotional.
  • Resubmit plan: If no traction after 1 hour, try the next headline variant. Wait at least 1 day between attempts. Max 3 tries.

Usage

/hn-optimize — Full submission optimization

/hn-optimize I built an open-source alternative to Linear using SQLite

Returns: headline score (1-10), 3-5 alternative headlines, content type recommendation (blog vs repo vs Show HN), optimal posting windows in your timezone, pre/post submission checklist.

/hn-spin — Content angle + outline

/hn-spin A Rust rewrite of our Python data pipeline that cut costs by 80%

Returns: 2-3 ranked HN angles mapped to viral archetypes, full content outline section by section with word counts and evidence to include, headline suggestions.

/hn-score — Score existing content

/hn-score https://myblog.com/reverse-engineering-spotify-recommendations

Returns: 87-point scorecard across 7 dimensions (headline, depth, audience fit, content type, accessibility, timing, discussion potential), top 3 improvements ranked by impact, comparable real HN posts with scores.

How this was built

These skills were created through a two-phase process: automated data research followed by manual guardrails and overrides from lived experience posting on HN.

Phase 1: Data research

We used Claude Code to scrape and synthesize data from multiple sources into a single analysis (research/hn-top-posts-analysis.md):

  • HN Algolia API — Queried for the highest-scoring posts from 2021-2026. Extracted the top 31 posts (all 3,000+ points) with scores, dates, comment counts, and domains. Also pulled top Show HN and Ask HN posts separately.
  • Amplify Partners front page analysis — Front page composition data: what percentage of the front page is personal blogs vs news vs corporate blogs vs Show HN.
  • Myriade timing analysis (157,000+ Show HN posts) — Breakout rates by day of week and hour of day. Identified Sunday 11:00-16:00 UTC as the best posting window.
  • Outerbounds sentiment analysis (350M tokens, 100K posts) — Topic trends from 2020-2023: what HN loves, hates, and finds divisive. Year-by-year trend shifts.
  • Refactoring English blog rankings — Top-performing personal blog domains on HN with total scores and per-post averages.
  • HN ranking algorithm documentation — The scoring formula (P-1)^0.8 / (T+2)^1.8 * penalty_factor, penalty multipliers for Show HN (0.4x), flamewar detection, domain penalties, vote ring thresholds, and the second-chance pool.
  • Multiple independent studies on HN posting strategy, GitHub star impact from front page posts, and conversion rate benchmarks.

The research agent ran ~47 tool calls across web searches, API queries, and page fetches to compile the dataset. The raw findings were then distilled into the scoring rubrics, timing recommendations, and headline patterns embedded in each skill.

Phase 2: Manual guardrails and overrides

Data analysis alone produces optimization advice that's technically accurate but ethically incomplete. The skills include manual guardrails added from direct experience with the HN community:

Bait and switch rule — The initial headline suggestions optimized for click-through without ensuring the title honestly described the content. We tested the skills on this very repo and caught the problem: provocative headlines like "90% of HN posts die" buried the fact that this is a Claude Code skill. The fix: every skill now enforces that the title must clearly state what the thing actually is. Spin the framing, not the facts.

Ethics guardrails — Four non-negotiable rules added across all skills, enforced before any optimization advice is given:

  1. No exaggeration — Don't inflate numbers or overstate results. The honest version is almost always more compelling on HN.
  2. No passing off others' work as your own — "I built" implies original authorship. If it's a fork or derivative, say so.
  3. Always credit prior art and sources — HN readers often know the prior art better than the poster. Getting caught omitting credit is worse than never posting.
  4. No self-promotional or sales content — The post must provide standalone value. If its primary purpose is driving signups or sales, it doesn't belong on HN.

In /hn-score, these ethics checks are enforced as a pass/fail gate before dimensional scoring — a post that fails any check is hard-capped at 40/87 regardless of how well it scores elsewhere.

These guardrails exist because optimizing for engagement without ethical constraints is how you end up writing content marketing that HN rightfully flags and buries. The skills should help you present good work effectively, not help you dress up bad work.

Key findings from the research

A few things that surprised us:

  • Sunday posts have a 15.7% breakout rate at the best hour vs ~9.5% on weekdays — 20-30% less competition
  • Show HN carries a 0.4x ranking penalty — your Show HN post needs ~2.5x the upvotes to rank equally with a regular link
  • Personal blogs reach the front page at 2.4x the rate of corporate blogs — self-host your content
  • Vote ring detection triggers at just 5-6 coordinated upvotes — don't ask your Slack channel to upvote
  • Medium has a <3% front page rate — worst of any major platform
  • Even power users only achieve ~50% front page rate — the baseline failure rate is 90%
  • Identical content can vary 1,000x in performance — "Gemma 3: Google's new multimodal models" got 4 upvotes while "Gemma 3 Technical Report [pdf]" got 1,324

License

MIT