Hacker News

Browse Hacker News in the terminal. A bundled Python script (scripts/hn.py, standard library only — no install) does the fetching and formats results as Markdown; your job is to map what the user asked for to the right command, run it, and present the output.

<SKILL_DIR> below is the directory containing this SKILL.md — substitute its absolute path when running.

Commands

# List a feed (default: top, 10 stories). Feeds: top, new, best, ask, show, job
python3 <SKILL_DIR>/scripts/hn.py list [feed] -n <count>

# Show a story's comment thread (needs the numeric id from a listing)
python3 <SKILL_DIR>/scripts/hn.py comments <id> -n <top-level> -d <max-depth>

# Search stories via Algolia (--sort date for newest-first instead of relevance)
python3 <SKILL_DIR>/scripts/hn.py search "<query>" -n <count> [--sort date]

Every command takes --json if you need structured data instead of Markdown (e.g. the user wants you to filter, rank, or summarize rather than just list).

Mapping requests to commands

The default — bare /hackernews, "what's on HN", "top stories" — is list with the default top feed and 10 stories. Honor an explicit count ("top 25", "show me 30") with -n. Map feed words directly: "new" / "newest" → new, "best" → best, "Ask HN" → ask, "Show HN" → show, "jobs" / "who's hiring" → job.

"Read the comments on #3" / "open that thread" / "what are people saying about the SpaceX one" → comments <id>, using the id shown in the listing you just produced (each line ends with `id <n>`). If the user names a story by topic rather than rank, pick the matching id from the most recent listing.

Superlative-across-the-front-page requests — "which story has the most comments", "the top discussion right now", "the highest-ranked one" — need a wider pull than the 10-story default, or you'll pick the max of the wrong set. The HN front page is ~30 stories, so list <feed> -n 30 first, choose the extremum from those 30, then act (e.g. comments <id>). Keep ordinary browsing at the 10-story default; only widen when the user's request hinges on a "most/highest/biggest" comparison.

"Search HN for Rust async" / "has HN discussed <X>" → search. Use --sort date when they want what's recent ("latest HN posts about …") rather than the most-upvoted all-time.

Presenting results

The script already emits clean, link-rich Markdown. Relay it to the user largely as-is — don't re-fetch each item or rewrite every line; that wastes time and adds nothing. A short framing line is welcome ("Here's the HN front page right now —"), and so is a one-line offer of the natural next step ("Want me to pull the comments on any of these?"). Keep the clickable links and the id markers intact so follow-ups work.

If the user asked a question about the stories (e.g. "anything about AI infra?", "summarize the top discussion") rather than just to see them, go ahead and read/summarize — fetch comments or use --json as needed, then answer.

Notes

• Stories carry an article link and a discussion link (the HN comment page); keep both — readers often want one or the other.
• Ask HN / Show HN text posts have no external URL, so the title links to the HN item and the post body shows at the top of its comments view.
• Comment fetching defaults to a focused view (8 top-level threads, depth 2, 30 nodes total) — enough to read the room without burying the user in a 300-reply megathread. When they want more ("go deeper", "show all comments", "the full thread"), widen with -n (more top-level), -d (deeper nesting), and --limit (raise the node budget, e.g. --limit 150).
• Hacker News data is public and read-only here; the script never posts, votes, or logs in.