Research
Gather source material for the radio show based on the user's prompt. The research strategy is agent-driven — you decide how to gather content based on what the user asks for.
Scripts
All research scripts live in skills/research/scripts/ and output to {workspace}/data/research/. They use only Python stdlib — no dependencies.
| Script | Command | Source |
|---|---|---|
fetch_hn.py |
python3 skills/research/scripts/fetch_hn.py --workspace ./workspace --top 6 |
Hacker News |
fetch_github.py |
python3 skills/research/scripts/fetch_github.py --repo owner/repo --workspace ./workspace |
GitHub repos |
fetch_url.py |
python3 skills/research/scripts/fetch_url.py --url https://... --workspace ./workspace |
Any URL |
Script Details
fetch_hn.py — Hacker News (two-phase)
Phase 1: Scan — grab top 10 story titles, scores, and comment counts (fast, no deep-diving):
python3 skills/research/scripts/fetch_hn.py --workspace ./workspace --mode scan --top 10
Output: {workspace}/data/research/hn-scan.md — a list of stories with IDs.
You read this file, pick the 2-3 most interesting stories for radio, then run phase 2.
When picking stories, SKIP anything related to politics, race, religion, international conflicts, historical controversies, gender/culture wars, or immigration. Stick to tech, programming, AI/ML, open source, science, startups, and developer culture.
Phase 2: Deep-dive — fetch full comment threads for the stories you picked:
python3 skills/research/scripts/fetch_hn.py --workspace ./workspace --mode deep-dive --stories 43210987,43209876
Output: {workspace}/data/research/hacker-news.md — full stories with top comments.
| Argument | Default | Description |
|---|---|---|
--workspace |
workspace |
Root workspace directory |
--mode |
(required) | scan or deep-dive |
--top |
10 |
Number of stories to scan (scan mode only) |
--stories |
(required for deep-dive) | Comma-separated story IDs |
fetch_github.py — GitHub Repository
python3 skills/research/scripts/fetch_github.py --repo googleapis/python-genai --workspace ./workspace
Accepts owner/repo or a full GitHub URL (https://github.com/owner/repo).
| Argument | Default | Description |
|---|---|---|
--repo |
(required) | GitHub repo (owner/repo or full URL) |
--workspace |
workspace |
Root workspace directory |
--releases |
5 |
Number of releases to fetch |
--issues |
8 |
Number of top issues to fetch |
What it does:
- Fetches repo metadata (stars, description, language).
- Fetches and decodes the README.
- Fetches recent releases with changelogs.
- Fetches top issues by comment count, including top comments.
- Outputs →
{workspace}/data/research/github.md
Uses the GitHub REST API directly — no auth needed for public repos.
fetch_url.py — Any URL
python3 skills/research/scripts/fetch_url.py --url https://example.com/blog-post --workspace ./workspace
| Argument | Default | Description |
|---|---|---|
--url |
(required) | URL to fetch content from |
--workspace |
workspace |
Root workspace directory |
--max-chars |
8000 |
Max chars to extract |
What it does:
- Fetches the HTML page.
- Strips scripts, styles, nav, footer.
- Converts HTML to markdown-like text.
- Extracts title and meta description.
- Outputs →
{workspace}/data/research/url_<safe_name>.md
Works for blog posts, documentation pages, arXiv abstracts, news articles, etc.
General Topic (no script — agent-driven)
If the user provides a topic without a specific source:
- Use Google Search to find recent articles, blog posts, and discussions
- Gather multiple perspectives and opposing viewpoints
- Write the research markdown directly to
{workspace}/data/research/
Output
- Directory:
{workspace}/data/research/ - Format: One or more markdown files with structured content
- All research must be saved here regardless of source — the script-writing step reads from this directory.
What to look for
When reviewing the research output, identify:
- Consensus: What do most people agree on?
- Debates: What are the key disagreements?
- Contrarian takes: Any notable dissenting opinions?
- Expert insights: Comments or quotes from people with domain expertise.
- Emotional stories: Anything that would make compelling radio.