/hackernews

name: hackernews
description: 'Interact with Hacker News (news.ycombinator.com) — browse top, new, and best stories, read item details and comment threads, look up user profiles, and search posts via Algolia. Use this skill whenever the user mentions Hacker News, HN, YCombinator news, ycombinator.com, news.ycombinator.com, wants to browse tech news, read HN discussions, search HN posts, or look up HN users. Also trigger when the user pastes an HN URL (e.g. news.ycombinator.com/item?id=12345). Keywords: Hacker News, HN, YC, ycombinator, tech news, Show HN, Ask HN, HN front page.'

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 commen