Agent Skills: hackernews

How to Use

1. Get Top Stories

Fetch IDs of the current top 500 stories:

curl -s "https://hacker-news.firebaseio.com/v0/topstories.json" | jq '.[:10]'

2. Get Best Stories

Fetch the best stories (highest voted over time):

curl -s "https://hacker-news.firebaseio.com/v0/beststories.json" | jq '.[:10]'

3. Get New Stories

Fetch the newest stories:

curl -s "https://hacker-news.firebaseio.com/v0/newstories.json" | jq '.[:10]'

4. Get Ask HN Stories

Fetch "Ask HN" posts:

curl -s "https://hacker-news.firebaseio.com/v0/askstories.json" | jq '.[:10]'

5. Get Show HN Stories

Fetch "Show HN" posts:

curl -s "https://hacker-news.firebaseio.com/v0/showstories.json" | jq '.[:10]'

6. Get Job Stories

Fetch job postings:

curl -s "https://hacker-news.firebaseio.com/v0/jobstories.json" | jq '.[:10]'

Item Details

7. Get Story/Comment/Job Details

Fetch full details for any item by ID. Replace <item-id> with the actual item ID:

curl -s "https://hacker-news.firebaseio.com/v0/item/<item-id>.json"

Response fields:

| Field | Description | |-------|-------------| | id | Unique item ID | | type | story, comment, job, poll, pollopt | | by | Username of author | | time | Unix timestamp | | title | Story title (stories only) | | url | Story URL (if external link) | | text | Content text (Ask HN, comments) | | score | Upvote count | | descendants | Total comment count | | kids | Array of child comment IDs |

8. Get Multiple Stories with Details

Fetch top 5 stories with full details. Replace <item-id> with the actual item ID:

curl -s "https://hacker-news.firebaseio.com/v0/topstories.json" | jq '.[:5][]' | while read id; do
  curl -s "https://hacker-news.firebaseio.com/v0/item/${id}.json" | jq '{id, title, score, url, by}'
done

9. Get Story with Comments

Fetch a story and its top-level comments. Replace <story-id> with the actual story ID:

curl -s "https://hacker-news.firebaseio.com/v0/item/<story-id>.json" | jq '{title, score, descendants, kids}'

Then for each comment ID in the kids array, replace <comment-id> with the actual comment ID:

curl -s "https://hacker-news.firebaseio.com/v0/item/<comment-id>.json" | jq '{by, text, score}'

User Data

10. Get User Profile

Fetch user details. Replace <username> with the actual username:

curl -s "https://hacker-news.firebaseio.com/v0/user/<username>.json"

Response fields:

| Field | Description | |-------|-------------| | id | Username | | created | Account creation timestamp | | karma | User's karma score | | about | User bio (HTML) | | submitted | Array of item IDs submitted |

11. Get User's Recent Submissions

Fetch a user's recent submissions. Replace <username> with the actual username:

curl -s "https://hacker-news.firebaseio.com/v0/user/<username>.json" | jq '.submitted[:5]'

Real-time Updates

12. Get Max Item ID

Get the current largest item ID (useful for polling new items):

curl -s "https://hacker-news.firebaseio.com/v0/maxitem.json"

13. Get Changed Items and Profiles

Get recently changed items and profiles (for real-time updates):

curl -s "https://hacker-news.firebaseio.com/v0/updates.json"

Practical Examples

Fetch Today's Top 10 with Scores

curl -s "https://hacker-news.firebaseio.com/v0/topstories.json" | jq '.[:10][]' | while read id; do
  curl -s "https://hacker-news.firebaseio.com/v0/item/${id}.json" | jq -r '"\(.score) points | \(.title) | \(.url // "Ask HN")"'
done

Find High-Scoring Stories (100+ points)

curl -s "https://hacker-news.firebaseio.com/v0/topstories.json" | jq '.[:30][]' | while read id; do
  curl -s "https://hacker-news.firebaseio.com/v0/item/${id}.json" | jq -r 'select(.score >= 100) | "\(.score) | \(.title)"'
done

Get Latest AI/ML Related Stories

curl -s "https://hacker-news.firebaseio.com/v0/topstories.json" | jq '.[:50][]' | while read id; do
  curl -s "https://hacker-news.firebaseio.com/v0/item/${id}.json" | jq -r 'select(.title | test("AI|GPT|LLM|Machine Learning|Neural"; "i")) | "\(.score) | \(.title)"'
done

API Endpoints Summary

| Endpoint | Description | |----------|-------------| | /v0/topstories.json | Top 500 stories | | /v0/beststories.json | Best stories | | /v0/newstories.json | Newest 500 stories | | /v0/askstories.json | Ask HN stories | | /v0/showstories.json | Show HN stories | | /v0/jobstories.json | Job postings | | /v0/item/{id}.json | Item details | | /v0/user/{id}.json | User profile | | /v0/maxitem.json | Current max item ID | | /v0/updates.json | Changed items/profiles |

Guidelines

1. No rate limits documented: But be respectful, add delays for bulk fetching
2. Use jq for filtering: Filter JSON responses to extract needed data
3. Cache results: Stories don't change frequently, cache when possible
4. Batch requests carefully: Each item requires a separate API call
5. Handle nulls: Some fields may be null or missing (e.g., url for Ask HN)
6. Unix timestamps: All times are Unix timestamps, convert as needed