hackernews-post - SKILL.md Agent Skill

name: hackernews-post description: How to write a Hacker News Show HN post that survives the notoriously tough HN crowd.

Writing a Hacker News "Show HN" Post

Title Rules

Max 80 characters (HN enforces this)
Format: Show HN: project-name – What it does in plain English
Be specific about what problem it solves, not vague marketing
Don't use buzzwords ("revolutionary", "blazing fast", "next-gen")
Good: Show HN: measure-fn – One-line timing, tracing, and error handling for TS
Bad: Show HN: measure-fn – The ultimate TypeScript observability framework

HN Formatting

HN does NOT support Markdown. No \``code blocks````, no bold, no headers.

Code blocks

Leave an empty line, then indent every line by 2 spaces:

Normal text here.

  const x = await doThing();
  console.log(x);

More normal text.

Links

Just paste the raw URL. HN auto-links them. No markdown link syntax.

Emphasis

Use asterisks for italic. No bold available.

Avoiding the HN Pedant Trap

HN commenters are notoriously pedantic. They will debate your premise instead of discussing your project if you give them an opening.

Never make absolute statements

❌ "Every function needs error handling" → top comment will argue fail-fast philosophy
✅ "Whenever a function needs error handling..." → soft, undebatable

Never claim it's "the best" or "the only way"

❌ "The right way to handle errors in TypeScript"
✅ "One approach to reducing try-catch boilerplate"

Frame around universally agreed pain points

Some contexts are undebatable — everyone agrees they need try-catch:

Network calls / external APIs
Database queries
File I/O
Data pipelines with multiple steps

But don't limit your tool to these — just use them to avoid philosophical debates.

Address known objections pre-emptively

If your tool has a design choice that will trigger debate, address it early:

Returning null on error? → Mention the return type is T | null and that .assert() exists for fail-fast
Wrapping everything? → Frame as "for boundaries where you'd add try-catch anyway"
Another logging library? → Lead with the unique feature (hierarchical IDs, one-line wrapper)

Post Structure

1. Opening hook (1-2 sentences)

Frame the pain point. Use "Whenever" or "When building X" — not absolutes.

2. Before/After code comparison

The single most effective way to sell a dev tool. Show the manual boilerplate, then the one-liner. Both should produce the same output.

3. Address the fail-fast crowd immediately

If your tool catches errors by default, mention the escape hatch (.assert(), rethrow) right after the first example.

4. Show the unique feature

What makes this different from console.log + try-catch? Show it (nesting, hierarchy, timeouts, etc.)

5. List additional features briefly

One line listing the extras. Don't over-explain — link to the README.

6. Closing

Something actionable. Links to GitHub and npm.

Don'ts

Don't say "I built this" or use first person — HN prefers impersonal technical writing
Don't start with "AI" unless AI is actually the core feature
Don't use marketing language ("game-changer", "10x", "zero config")
Don't include features you haven't shipped
Don't link to a landing page — link directly to the GitHub repo
Don't post on weekends (lower traffic) — best times are Tuesday-Thursday 9-11am ET

Submission

Go to https://news.ycombinator.com/submit
Enter your title and URL
If doing a self-post (Show HN with text), paste your text in the text field. URL field should still point to your repo.
After posting, you have a 2-hour edit window to fix typos or tweak wording based on early comments

Template

## Title
Show HN: [name] – [what it does, max 80 chars]

## URL
https://github.com/[user]/[repo]

## Text

[1-2 sentence hook framing the pain point — soft language, no absolutes]

  [manual boilerplate code — 2-space indent]

[project name] does the same in one line:

  [your one-liner — 2-space indent]

Both produce:

  [output — 2-space indent]

[Address null/error behavior + escape hatch for fail-fast crowd]

[Show unique feature with code + output]

[One-line list of additional features]

[Closing line]

GitHub: [url]
npm: [url]