Hacker News

Browse, search, and read Hacker News stories, comments, and user profiles.

Skill Directory

<SKILL_DIR> is the directory containing this SKILL.md file. Determine it ONCE at the start and reuse it.

Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip this step.

sig status hackernews 2>&1

Check the JSON output fields configured and valid:

• configured: false → run Provider Setup below. Do NOT proceed without completing it.
• valid: false (but configured: true) → run sig login hackernews, then re-check.
• valid: true → detect proxy (see below), then execute the user's request.

Provider Setup

1. Read <SKILL_DIR>/references/provider-config.yaml
2. Append the provider block to ~/.sig/config.yaml under providers:
3. Ask the user: "Do you need a proxy to access this site?" — if yes, add networkProxy: <url> under the provider in config.yaml
4. Run sig login hackernews (with --network-proxy <url> if proxy was specified)
5. Verify: run sig status hackernews again — must show valid: true before proceeding

Proxy Detection (after provider is valid)

grep -A15 "^\s*hackernews:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}'

If this outputs a URL, prefix ALL python3 commands with HTTPS_PROXY=<url> HTTP_PROXY=<url>. If using socks5, convert to socks5h for python (e.g. socks5://... → socks5h://...). If empty, no proxy needed.

Running Scripts

All scripts require setup to be completed first (see above).

Read operations — use sig run to inject cookie (enables authenticated features like vote status):

sig run hackernews -- bash -c 'python3 <SKILL_DIR>/scripts/hn_top.py --cookie "$SIG_HACKERNEWS_COOKIE" --limit 10'

Write operations — require sig run (cookie is mandatory):

sig run hackernews -- bash -c 'python3 <SKILL_DIR>/scripts/hn_vote.py --cookie "$SIG_HACKERNEWS_COOKIE" --id 12345'

Env var: SIG_HACKERNEWS_COOKIE

On auth error (401/403): run sig login hackernews automatically (no user prompt), then retry.

Scripts Reference

All scripts are in <SKILL_DIR>/scripts/. Run via Bash tool.

Read Operations

Script	Purpose	Auth
hn_top.py	Top stories (front page)	None
hn_new.py	Newest stories	None
hn_best.py	Best stories	None
hn_ask.py	Ask HN stories	None
hn_show.py	Show HN stories	None
hn_jobs.py	Job postings	None
hn_item.py	Item detail + comment tree	None
hn_user.py	User profile + submissions	None
hn_search.py	Full-text search via Algolia	None

Write Operations

Script	Purpose	Auth
hn_submit.py	Submit a story	Required
hn_comment.py	Post a comment	Required
hn_vote.py	Upvote an item	Required

hn_top.py

--limit N             Max stories to fetch (default: 30)

hn_new.py

--limit N             Max stories to fetch (default: 30)

hn_best.py

--limit N             Max stories to fetch (default: 30)

hn_ask.py

--limit N             Max stories to fetch (default: 30)

hn_show.py

--limit N             Max stories to fetch (default: 30)

hn_jobs.py

--limit N             Max jobs to fetch (default: 30)

hn_item.py

--id ID               Item ID (required)
--depth N             Max comment tree depth (default: 2)
--comments-limit N    Max comments to fetch (default: 20)

hn_user.py

--username NAME       HN username (required)
--include-submissions Include recent submitted item details (flag)

hn_search.py

--query TEXT          Search query (required)
--type TYPE           Filter: "story", "comment", "ask_hn", "show_hn"
--sort SORT           Sort by: "relevance" (default) or "date"
--limit N             Max results (default: 30)
--author NAME         Filter by author username
--points-min N        Minimum points filter

hn_submit.py

--cookie COOKIE       HN session cookie (required)
--title TEXT          Story title (required)
--url URL             URL to submit (for link posts)
--text TEXT           Text body (for Ask HN / text posts)

hn_comment.py

--cookie COOKIE       HN session cookie (required)
--parent ID           Parent item ID — story or comment (required)
--text TEXT           Comment text (required)

hn_vote.py

--cookie COOKIE       HN session cookie (required)
--id ID               Item ID to upvote (required)

Safety

Always show the user the title/body and get explicit confirmation before calling hn_submit.py. Submissions are public.

Always confirm before hn_comment.py. Comments are public and cannot be deleted after a few minutes.

hn_vote.py is reversible — you can un-upvote by clicking the upvote button again on the HN website.

Key Concepts

Item types — Hacker News items have a type field: story, comment, job, poll, pollopt. Stories have title, url, score, and descendants (total comment count). Comments have text and parent.

Item IDs — Numeric IDs found in URLs like news.ycombinator.com/item?id=12345. Get IDs from top/new/best/search results, then use with hn_item.py.

Comment trees — Comments are nested via the kids array. hn_item.py recursively fetches comment trees up to --depth levels. Each comment includes replies for nested children.

Story categories — Use hn_ask.py for Ask HN, hn_show.py for Show HN, hn_jobs.py for job postings.

Algolia search — hn_search.py uses the Algolia HN Search API for full-text search with filtering by type, author, and minimum points.

Error Handling

Error	Cause	Fix
HTTP_404	Item or user not found	Check the ID / username
HTTP_429	Rate limited by API	Wait and retry
SEARCH_ERROR	Algolia API unavailable	Try again later
ERROR	Network or unexpected failure	Check connectivity

Workflow Examples

Browse top stories

1. python3 <SKILL_DIR>/scripts/hn_top.py --limit 10

Read a specific story and its comments

1. python3 <SKILL_DIR>/scripts/hn_item.py --id 12345 --depth 3 --comments-limit 30

Search for topics

1. python3 <SKILL_DIR>/scripts/hn_search.py --query "Rust programming" --type story --limit 10

Look up a user

1. python3 <SKILL_DIR>/scripts/hn_user.py --username pg --include-submissions

Submit a story

1. Show title/URL to user and get confirmation
2. sig run hackernews -- bash -c 'python3 <SKILL_DIR>/scripts/hn_submit.py --cookie "$SIG_HACKERNEWS_COOKIE" --title "My Post" --url "https://example.com"'

Comment on a story

1. Show comment text to user and get confirmation
2. sig run hackernews -- bash -c 'python3 <SKILL_DIR>/scripts/hn_comment.py --cookie "$SIG_HACKERNEWS_COOKIE" --parent 12345 --text "Great article!"'

Upvote a story

1. sig run hackernews -- bash -c 'python3 <SKILL_DIR>/scripts/hn_vote.py --cookie "$SIG_HACKERNEWS_COOKIE" --id 12345'