askaipods 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delibread0601
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# askaipods
+
+> Search AI podcast quotes about a topic — find what real guests on Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens of other AI podcasts are actually saying. A universal [agentskills.io](https://agentskills.io) skill compatible with Claude Code, OpenAI Codex, Hermes Agent, OpenClaw, and any other agent that supports the open skill standard. Powered by [podlens.net](https://podlens.net).
+
+```
+$ askaipods "what are people saying about test-time compute"
+
+# askaipods · "what are people saying about test-time compute"
+
+*Tier: anonymous · Results: 10 · Quota: 1/10 daily*
+
+## Results — newest first
+
+### 1. Lenny's Podcast — AI Engineering 101 with Chip Huyen
+*2025-10*
+
+> Test-time compute — spending more compute during inference by generating
+> multiple answers and selecting the best, or allowing more reasoning/thinking ...
+
+### 2. Latent Space — Better Data is All You Need (Ari Morcos, Datology)
+*2025-08*
+
+> Test-time compute as a paradigm pushes toward smaller base models because
+> the cost of solving a prob...
+
+(...8 more results, newest-first...)
+```
+
+## Why this exists
+
+Web search is bad at "what is the AI community thinking about X right now". You get blog posts, Reddit threads, and outdated news articles. What you actually want is the *real conversation* — what researchers, founders, and investors are saying on AI podcasts, in their own words.
+
+`askaipods` is a thin CLI + agent skill that asks the [PodLens](https://podlens.net) semantic search API and returns the most relevant quote excerpts, sorted newest-first. The skill teaches your agent (Claude Code, OpenAI Codex, Hermes, OpenClaw, and any other [agentskills.io](https://agentskills.io)-compatible runtime) when to call the CLI, how to parse the output, and how to write a useful **Insights** section that summarizes the patterns across the returned quotes.
+
+## Install
+
+### Option 1: as a CLI (works in any terminal)
+
+```bash
+npx askaipods "your query here"
+```
+
+That's the entire install. `npx` fetches and runs the latest version each time. No global install needed.
+
+To install globally (faster startup):
+
+```bash
+npm install -g askaipods
+askaipods "your query here"
+```
+
+### Option 2: as an agent skill (Claude Code, Codex, Hermes, OpenClaw, etc.)
+
+```bash
+git clone https://github.com/Delibread0601/askaipods.git
+```
+
+Then copy or symlink the `skill/askaipods/` directory into your agent's skills folder. Per-runtime instructions:
+
+| Runtime | Skill folder | Install guide |
+|---|---|---|
+| Claude Code | `~/.claude/skills/askaipods/` | [examples/claude-code-install.md](examples/claude-code-install.md) |
+| OpenAI Codex CLI | `~/.agents/skills/askaipods/` ✨ | [examples/codex-install.md](examples/codex-install.md) |
+| OpenClaw | `~/.agents/skills/askaipods/` ✨ or `~/.openclaw/skills/askaipods/` | [examples/openclaw-install.md](examples/openclaw-install.md) |
+| Hermes Agent | `~/.hermes/skills/askaipods/` | [examples/hermes-install.md](examples/hermes-install.md) |
+| Any other agentskills.io-compatible runtime | per runtime docs | follow the agentskills.io standard — copy `skill/askaipods/` into your agent's skills directory |
+
+✨ **Two-for-one tip**: Codex CLI and OpenClaw both read from `~/.agents/skills/`, so a single install at `~/.agents/skills/askaipods/` covers both runtimes simultaneously.
+
+The skill folder is self-contained: it tells the host agent how to invoke `askaipods` (via `npx`), how to parse the JSON, and how to render the response with a **Latest** + **Top Relevant** + **Insights** structure.
+
+## Usage
+
+### As a CLI
+
+```bash
+# Default: human-readable markdown to terminal
+askaipods "what are VCs saying about reasoning models"
+
+# JSON output (for scripts and agents)
+askaipods "Anthropic safety research" --format json
+
+# Restrict to recent episodes only (max 7 days for anonymous tier; member tier accepts any value)
+askaipods "GPU shortage" --days 7
+
+# Use a member-tier API key for 50/day instead of 10/day
+ASKAIPODS_API_KEY=pk_xxx askaipods "your query"
+askaipods "your query" --api-key pk_xxx
+```
+
+### As an agent skill
+
+Once the skill is installed in your agent's skills directory, simply ask:
+
+> What are people saying about test-time compute on AI podcasts?
+
+Your agent will recognize the trigger phrase, invoke `askaipods`, and present the results with a Latest section, a Top Relevant section, and an AI-generated Insights summary. No CLI knowledge required from the user.
+
+## Tier comparison
+
+| | Anonymous (default) | Member |
+|---|---|---|
+| **Daily quota** | 10 searches per IP | 50 searches per user |
+| **Results returned** | 10 (randomized from top 20) | 20 (fixed top 20) |
+| **Text length** | Truncated by rank (150/100/60 chars) | Full text |
+| **Date precision** | Month only (`2025-10`) | Full date (`2025-10-15`) |
+| **Setup** | Nothing | `ASKAIPODS_API_KEY` env var |
+| **Sign up** | n/a | https://podlens.net |
+
+The anonymous tier exists so you can try the skill end-to-end with zero setup. Sign up for member access only when you outgrow the 10/day quota or need full text and exact dates.
+
+## Honest limitations
+
+- **No speaker attribution.** The corpus indexes quotes at the episode level but does not attempt to identify *which guest* said each quote. The upstream pipeline avoids speaker labeling because automatic diarization is unreliable, and a wrong attribution is worse than no attribution.
+- **No episode URLs.** The public API does not expose direct podcast or episode links. You will need to search the podcast and episode title in your podcast app of choice.
+- **AI-focused corpus.** Coverage is dense for AI research, ML engineering, AI investing, and AI policy. Off-topic queries return sparse, noisy results.
+- **Short quote excerpts.** Each result is typically 1-3 sentences (anonymous tier truncates further). For long-form context, listen to the episode.
+
+These are not bugs. The skill surfaces them honestly so neither you nor your agent fabricate things the API does not provide.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Usage error / invalid arguments / API key rejected |
+| `2` | Daily quota exhausted |
+| `3` | Network error / podlens.net unavailable |
+
+## How the skill renders results
+
+For member tier (`render_hint: dual_view`), the host agent renders two sections plus insights:
+
+```markdown
+## 🆕 Latest 5
+(5 most recent of the 20 returned results)
+
+## 🎯 Top 5 Most Relevant
+(5 results with api_rank 1-5, regardless of date)
+
+## 💡 Insights
+(3-5 bullets synthesizing patterns across the quotes)
+```
+
+For anonymous tier (`render_hint: single_view`), only Latest and Insights — the Top Relevant section is intentionally suppressed because anonymous results are randomized within the top 20, so api_rank does not represent true semantic relevance.
+
+See [`skill/askaipods/SKILL.md`](skill/askaipods/SKILL.md) for the full skill specification.
+
+## Architecture
+
+```
+askaipods/
+├── bin/askaipods.js       ← CLI entry (shebang)
+├── src/
+│   ├── cli.js             ← arg parsing, format auto-detection
+│   ├── client.js          ← podlens.net /api/search/semantic client
+│   └── format.js          ← time-desc sort + JSON / markdown rendering
+├── skill/askaipods/
+│   └── SKILL.md           ← agentskills.io standard skill file
+├── examples/              ← per-runtime install guides
+├── package.json           ← zero dependencies (Node 18+ stdlib only)
+├── LICENSE                ← MIT
+└── README.md
+```
+
+The CLI is intentionally zero-dependency (Node 18+ stdlib only) so `npx askaipods` cold-starts in under a second and the package install footprint is minimal.
+
+## Contributing
+
+Issues and PRs welcome at https://github.com/Delibread0601/askaipods.
+
+If you find a runtime that conforms to [agentskills.io](https://agentskills.io) but is not yet listed in the install table above, please open an issue or PR with the install path and we'll add it.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Powered by [podlens.net](https://podlens.net) — AI podcast intelligence.

package/bin/askaipods.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2)).catch((err) => {
+  const message = err?.message ?? String(err);
+  process.stderr.write(`askaipods: ${message}\n`);
+  process.exit(typeof err?.exitCode === "number" ? err.exitCode : 1);
+});

package/examples/claude-code-install.md

@@ -0,0 +1,54 @@
+# Install askaipods in Claude Code
+
+## Personal install (available across all your projects)
+
+```bash
+git clone https://github.com/Delibread0601/askaipods.git ~/Code/askaipods
+mkdir -p ~/.claude/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.claude/skills/askaipods
+```
+
+The symlink lets you `git pull` updates to the repo and have them picked up automatically without recopying.
+
+If you prefer a copy over a symlink:
+
+```bash
+cp -r ~/Code/askaipods/skill/askaipods ~/.claude/skills/askaipods
+```
+
+## Project-only install (only for the current repo)
+
+```bash
+mkdir -p .claude/skills
+cp -r /path/to/askaipods/skill/askaipods .claude/skills/askaipods
+```
+
+Project-level skills override personal-level skills with the same name.
+
+## Verify
+
+In Claude Code, ask:
+
+> What skills are available?
+
+You should see `askaipods` in the list. Or invoke it directly:
+
+> /askaipods test-time compute
+
+Or trigger it organically:
+
+> What are people saying about test-time compute on AI podcasts?
+
+Claude Code should recognize the trigger phrase, run `npx askaipods search "..." --format json`, parse the response, and render the Latest / Top Relevant / Insights sections.
+
+## Troubleshooting
+
+- **Skill not appearing**: Make sure the parent directory name matches the `name` field in `SKILL.md` (both must be `askaipods`).
+- **`npx askaipods` fails**: Check that Node.js 18+ is installed: `node --version`. The CLI uses zero dependencies so there are no other prereqs.
+- **Anonymous quota exhausted**: Sign up at https://podlens.net for 50/day, then `export ASKAIPODS_API_KEY=pk_xxx`.
+- **Skill triggers too rarely**: Front-load your prompt with the trigger phrases in `SKILL.md` description, or invoke directly with `/askaipods <query>`.
+
+## Reference
+
+- [Claude Code skills documentation](https://code.claude.com/docs/en/skills)
+- [agentskills.io specification](https://agentskills.io/specification)

package/examples/codex-install.md

@@ -0,0 +1,47 @@
+# Install askaipods in OpenAI Codex CLI
+
+Codex CLI typically looks in `~/.agents/skills/` (user-level) and `.agents/skills/` (project / repo level). Project-scoped skills win over user-scoped when both exist with the same name. For the authoritative scope list and any system-level paths your installed version supports, consult the [official Codex skills documentation](https://developers.openai.com/codex/skills/).
+
+For most users, the **user-level** install is what you want — it makes `askaipods` available across every project.
+
+## User-level install
+
+```bash
+git clone https://github.com/Delibread0601/askaipods.git ~/Code/askaipods
+mkdir -p ~/.agents/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
+```
+
+Symlink (above) is recommended so `git pull` updates flow through automatically. Or copy:
+
+```bash
+cp -r ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
+```
+
+## Project-only install
+
+```bash
+mkdir -p .agents/skills
+cp -r /path/to/askaipods/skill/askaipods .agents/skills/askaipods
+```
+
+## Verify
+
+Codex CLI detects skill changes automatically. If the skill does not appear after install, restart the Codex session.
+
+In Codex, ask:
+
+> What are people saying about reasoning models on AI podcasts?
+
+Codex should detect the trigger, run `npx askaipods search "..." --format json`, and render the structured response per `SKILL.md`.
+
+## Troubleshooting
+
+- **Skill not detected**: Restart Codex (per the official docs, "If an update doesn't appear, restart Codex").
+- **Multiple skills with the same name across scopes**: Codex shows both in the selector — repository-scoped wins by default.
+- **`npx askaipods` fails**: Check Node.js 18+: `node --version`.
+
+## Reference
+
+- [OpenAI Codex skills documentation](https://developers.openai.com/codex/skills/)
+- [agentskills.io specification](https://agentskills.io/specification)

package/examples/hermes-install.md

@@ -0,0 +1,36 @@
+# Install askaipods in Hermes Agent
+
+[Hermes Agent](https://github.com/nousresearch/hermes-agent) is built by Nous Research and is compatible with the [agentskills.io](https://agentskills.io) open standard. Skills live in `~/.hermes/skills/`.
+
+## Install
+
+```bash
+git clone https://github.com/Delibread0601/askaipods.git ~/Code/askaipods
+mkdir -p ~/.hermes/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.hermes/skills/askaipods
+```
+
+Or copy:
+
+```bash
+cp -r ~/Code/askaipods/skill/askaipods ~/.hermes/skills/askaipods
+```
+
+## Verify
+
+In a Hermes session, ask:
+
+> Find what AI podcasts are saying about test-time compute
+
+Hermes should pick up the skill from `~/.hermes/skills/askaipods/`, shell out to `npx askaipods`, and present the structured results.
+
+## Troubleshooting
+
+- **`npx askaipods` fails**: Hermes is Python-based but the askaipods CLI is Node. Make sure Node.js 18+ is on PATH alongside Python: `node --version`.
+- **Skill not picked up**: Hermes documentation indicates skills are loaded from `~/.hermes/skills/`. Restart the agent after install if needed.
+- **Quota exhausted**: Set `ASKAIPODS_API_KEY` in your shell environment before launching Hermes so the variable propagates to subprocess calls.
+
+## Reference
+
+- [Hermes Agent README](https://github.com/nousresearch/hermes-agent)
+- [agentskills.io specification](https://agentskills.io/specification)

package/examples/openclaw-install.md

@@ -0,0 +1,62 @@
+# Install askaipods in OpenClaw
+
+[OpenClaw](https://github.com/openclaw/openclaw) is [agentskills.io](https://agentskills.io)-compatible. Per the [official docs](https://docs.openclaw.ai/tools/skills), it loads skills from four locations with this precedence (highest first):
+
+1. `<workspace>/skills/` — workspace skills (highest)
+2. `<workspace>/.agents/skills/` — project agent skills
+3. `~/.agents/skills/` — personal agent skills (shared with OpenAI Codex CLI)
+4. `~/.openclaw/skills/` — managed/local skills (shared across all agents on the machine)
+
+For most users, **option 3 is the best choice** because the same `~/.agents/skills/askaipods/` install also makes the skill available in OpenAI Codex CLI — one install, two runtimes.
+
+## Recommended install (shared with Codex)
+
+```bash
+git clone https://github.com/Delibread0601/askaipods.git ~/Code/askaipods
+mkdir -p ~/.agents/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
+```
+
+If you don't already use Codex and prefer to keep OpenClaw skills separate, install into the OpenClaw-native location instead:
+
+```bash
+mkdir -p ~/.openclaw/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.openclaw/skills/askaipods
+```
+
+Or use the OpenClaw CLI once askaipods is published to the ClawHub registry (not yet — check back, or open an issue to track):
+
+```bash
+openclaw skills install askaipods   # not yet available
+```
+
+## Workspace-only install
+
+To make askaipods available only inside a specific OpenClaw workspace:
+
+```bash
+mkdir -p <workspace>/skills
+cp -r ~/Code/askaipods/skill/askaipods <workspace>/skills/askaipods
+```
+
+This wins over all user-level installs for that workspace.
+
+## Verify
+
+In OpenClaw, ask:
+
+> What are AI podcasts saying about reasoning models?
+
+OpenClaw should recognize the trigger phrase, shell out to `npx askaipods search "..." --format json`, and render the structured response per the SKILL.md template.
+
+## Troubleshooting
+
+- **Skill not detected**: Run `openclaw skills update --all` to refresh, or restart the OpenClaw session. Check that the directory name `askaipods` matches the `name` field in `SKILL.md`.
+- **`npx askaipods` fails**: Make sure Node.js 18+ is on PATH: `node --version`.
+- **Conflicting copies across precedence levels**: Only the highest-precedence one wins. If you have askaipods in both `~/.agents/skills/` and `<workspace>/skills/`, the workspace one takes effect.
+
+## Reference
+
+- [OpenClaw skills documentation](https://docs.openclaw.ai/tools/skills)
+- [OpenClaw GitHub](https://github.com/openclaw/openclaw)
+- [agentskills.io specification](https://agentskills.io/specification)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "askaipods",
+  "version": "0.1.0",
+  "description": "Search AI podcast quotes by topic — find what Lex Fridman, Dwarkesh Patel, No Priors, and Latent Space guests are actually saying. Universal agentskills.io skill compatible with Claude Code, OpenAI Codex, Hermes Agent, OpenClaw, and any other agent that supports the open skill standard. Powered by podlens.net.",
+  "type": "module",
+  "bin": {
+    "askaipods": "./bin/askaipods.js"
+  },
+  "main": "./src/cli.js",
+  "exports": {
+    ".": "./src/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/askaipods.js",
+    "test": "echo 'no automated tests yet — see CONTRIBUTING for the test plan' && exit 0"
+  },
+  "keywords": [
+    "ai",
+    "podcasts",
+    "search",
+    "agent-skill",
+    "agentskills",
+    "claude-code",
+    "codex",
+    "hermes",
+    "openclaw",
+    "podlens",
+    "semantic-search",
+    "llm-tools",
+    "agentic"
+  ],
+  "author": "Delibread0601",
+  "license": "MIT",
+  "homepage": "https://github.com/Delibread0601/askaipods#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Delibread0601/askaipods.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Delibread0601/askaipods/issues"
+  }
+}

package/skill/askaipods/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: askaipods
+description: Search AI podcast quotes about a topic. Use whenever the user asks "what are people saying about X", "latest takes on Y", "find AI podcast quotes about Z", "who is discussing <model/concept>", or wants to know how AI researchers, founders, or VCs are publicly discussing any AI topic — even when they don't say "podcast". Returns recent excerpts from real episodes of Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens more, sorted newest-first via the podlens.net semantic search API. Trigger eagerly on AI-research, ML-engineering, AI-investing, or AI-policy questions where real-human commentary beats a web search summary. Do not use for general web search, full transcript reading, or non-AI topics.
+license: MIT
+requirements: Node.js 18+ on PATH, internet access to podlens.net. Optional ASKAIPODS_API_KEY env var unlocks the 50/day member tier; without it the skill works on the 10/day anonymous tier (per-IP).
+---
+
+# askaipods — AI podcast quote search
+
+This skill turns "what is the AI community saying about X" into a list of real quote excerpts pulled from recent episodes of top AI podcasts. The corpus is semantically indexed (embedding-based search), so phrasings like "test-time compute", "inference-time scaling", and "thinking longer" all return overlapping results — the user does not need to guess the exact words a guest used.
+
+The data source is the public PodLens search API at `podlens.net`. The skill never hits that API directly from your model context — it shells out to a small bundled CLI (`askaipods`) that handles HTTP, retries, error mapping, and result sorting. Your job is to invoke the CLI, parse its JSON, and present the results in the format below.
+
+## When to invoke
+
+Trigger eagerly. The Anthropic skill best-practices warn that models tend to **undertrigger** skills — please do not be that model. Invoke this skill when the user is asking about how the AI community is publicly discussing any topic. Concrete trigger patterns:
+
+- "What are people saying about <X>?"
+- "What's the latest take on <X>?"
+- "Find quotes from AI podcasts about <X>"
+- "Who is discussing <model / company / paper / concept>?"
+- "What are VCs / researchers / founders saying about <X>?"
+- "Has anyone on a podcast talked about <X>?"
+- Any AI-research, ML-engineering, AI-investing, AI-safety, or AI-policy question where the user would clearly benefit from real-human commentary (as opposed to a textbook summary or a web search snippet)
+
+You may invoke even when the user does not say "podcast" — if the question is about *what people think* on an AI topic, this skill is the right tool.
+
+## When NOT to invoke
+
+- General web search (use a web search tool)
+- Reading a specific episode end-to-end (this skill returns short quote excerpts, not full transcripts)
+- Non-AI topics (the corpus is AI-focused; results for unrelated subjects will be sparse and noisy)
+- Code generation, math, or any task that doesn't benefit from human commentary
+
+## How to invoke
+
+Run the bundled CLI and pass `--format json`. The flag matters because without it the CLI auto-detects the output format from `isTTY`, and an agent calling via shell may or may not get a TTY depending on the runtime — explicit `--format json` removes that variability.
+
+```bash
+npx askaipods search "<USER QUERY>" --format json
+```
+
+If `npx askaipods` is not available in the user's environment (e.g. the package was not yet published to npm), fall back to running the local CLI from this skill's parent directory:
+
+```bash
+node <path-to-askaipods-repo>/bin/askaipods.js search "<USER QUERY>" --format json
+```
+
+To restrict to recent episodes only, add `--days N` (the API caps anonymous tier at 7 days; member tier accepts any value):
+
+```bash
+npx askaipods search "<USER QUERY>" --days 30 --format json
+```
+
+## JSON shape returned by the CLI
+
+```json
+{
+  "tier": "anonymous" | "member",
+  "query": "the user's query string",
+  "fetched_at": "<ISO-8601 timestamp set by the CLI at request time>",
+  "render_hint": "single_view" | "dual_view",
+  "results": [
+    {
+      "podcast": "Dwarkesh Patel",
+      "episode": "Dario Amodei on the future of AI",
+      "date": "2026-03-15",
+      "text": "the actual quote excerpt ...",
+      "api_rank": 1
+    }
+  ],
+  "meta": {
+    "total_returned": 20,
+    "quota": { "used": 3, "limit": 50, "period": "daily" },
+    "restrictions": null,
+    "query_hash": "..."
+  }
+}
+```
+
+Field notes that affect how you render:
+
+- **`tier`** — `member` if the user has a valid API key, `anonymous` otherwise. Drives the rendering branch below. The CLI defaults `tier` to `"anonymous"` if the upstream response somehow lacks the field, so you will always land on one of the two documented branches — never on a third "unknown" path.
+- **`render_hint`** — `dual_view` for member, `single_view` for anonymous. Honor this. The reason: anonymous results are a randomized 10-of-20 subset, so `api_rank` only describes order *within that random subset*, not true semantic relevance against the corpus. Showing a "Top Most Relevant" section for anonymous tier would mislead the user.
+- **`results[]`** — already sorted **newest first** by the CLI. Each result carries `api_rank` (1 = most semantically relevant in API order) so you can derive a "Top Relevant" sub-view without re-querying.
+- **`results[].podcast` / `episode` / `date`** — any of these may be `null` if the upstream record is incomplete. Render `Unknown podcast` / `Untitled episode` / `date unknown` rather than dropping the result. The CLI's own markdown renderer falls back the same way.
+- **`results[].date` format** — `YYYY-MM-DD` (or full ISO timestamp) for member tier; `YYYY-MM` only for anonymous tier (deliberately fuzzed by the API for query privacy). Display whatever you got — don't guess a day.
+- **`meta.quota`** — passed through from the podlens.net API. Sub-fields like `used`, `limit`, `period` are reliably present; other sub-fields (e.g., a reset timestamp) may or may not appear depending on the server version. Treat all sub-fields as optional and degrade gracefully.
+- **`meta.restrictions`** — `null` for member tier; for anonymous tier, an object describing the cap (e.g., `{ max_results: 10, text_truncated: true, results_randomized: true }`). If non-null, the closing anonymous-tier note (templated below) is the right way to surface it; do not parse the object field-by-field.
+- **No speaker name and no episode URL.** The corpus is indexed at the key-point level without per-speaker attribution (the upstream pipeline intentionally avoids attributing quotes to individuals because automatic speaker diarization is unreliable). Episode URLs are also not exposed by the public API. Render `Podcast — Episode` only; do not fabricate "Dario said" if the text doesn't already attribute itself.
+
+## How to render the response
+
+Output exactly this structure. It is required for consistency across runtimes — users of this skill across Claude Code, OpenAI Codex, Hermes Agent, OpenClaw, and any other agentskills.io-compatible agent should see the same shape regardless of which agent ran it.
+
+(Note: the CLI's own `--format markdown` output uses a different layout — `### N. Podcast — Episode` headings — because that mode targets humans running `askaipods` directly in a terminal. As an agent you should always pass `--format json` and reformat the parsed payload yourself per the templates below; do not copy the CLI's markdown.)
+
+### For `render_hint: "dual_view"` (member tier)
+
+```markdown
+## 🆕 Latest 5
+
+1. **<podcast>** — *<episode>* · <date>
+   > "<quote text>"
+
+2. ...
+
+(continue through the 5 most recent of the returned results, which are the first 5 in the `results` array since the CLI already sorted by date desc)
+
+## 🎯 Top 5 Most Relevant
+
+1. **<podcast>** — *<episode>* · <date>
+   > "<quote text>"
+
+2. ...
+
+(these 5 are the results with `api_rank` 1 through 5, regardless of date — pull them from the same `results` array by filtering on `api_rank`)
+
+## 💡 Insights
+
+- <bullet 1>
+- <bullet 2>
+- <bullet 3>
+- (3-5 bullets total — see Insights guidelines below)
+```
+
+If the same result appears in both Latest and Top Relevant sections, that's fine and informative (it means a recent quote is also semantically central) — show it in both. Do not deduplicate.
+
+### For `render_hint: "single_view"` (anonymous tier)
+
+```markdown
+## 🆕 Recent Quotes
+
+1. **<podcast>** — *<episode>* · <date>
+   > "<quote text>"
+
+2. ...
+
+(all returned results, in `results` array order which is already newest-first; expect up to 10)
+
+## 💡 Insights
+
+- <bullet 1>
+- <bullet 2>
+- <bullet 3>
+
+---
+
+*Anonymous tier: 10 randomized results from top 20, text truncated by rank, dates fuzzed to month. Set `ASKAIPODS_API_KEY` for 50 searches/day with full text and full dates — sign up at https://podlens.net.*
+```
+
+The closing note about the anonymous tier matters because it tells the user (a) why the text looks chopped, (b) why the dates are coarse, and (c) what the upgrade path is. Skipping it leaves the user wondering if the skill is broken.
+
+## Insights guidelines
+
+The Insights section is the most valuable part of your response — it is what differentiates this skill from a raw API call. The user could read 10 quotes themselves; what they cannot easily do is *spot the patterns across the 10*. That is your job.
+
+Write 3-5 bullets, each one concrete and one sentence long. Cover at least three of these dimensions:
+
+1. **Common themes** — what idea, framing, or concept is repeating across multiple quotes? Be specific: "three guests describe X as a 'phase transition'" beats "people are excited about X".
+2. **Temporal trend** — is the conversation accelerating, shifting, or fading? Are recent quotes saying something different from older ones in the same set?
+3. **Notable podcasts or episodes** — which shows are over-represented? An over-representation often signals which community is most engaged with the topic. (You cannot identify individual speakers, but you can identify which podcasts the topic clusters in.)
+4. **Disagreements** — do quotes contradict each other? Where are the live debates?
+5. **What's missing** — what obvious angle, counter-argument, or stakeholder voice is conspicuously absent from the returned results? Gaps are signals too.
+
+What to avoid:
+
+- Generic observations like "people are excited about AI" — the user could write that themselves.
+- Restating individual quotes — the user already sees the quotes above.
+- Confident claims about who said what — the API does not return speaker names; do not invent attribution.
+- Bullet points that exceed one sentence — the goal is dense pattern-recognition, not paragraphs.
+
+## Error handling
+
+The CLI uses stable exit codes so you can branch on the failure mode:
+
+| Exit code | Meaning | What to tell the user |
+|---|---|---|
+| `0` | Success | Render the results normally |
+| `1` | Usage error / invalid arguments / API key rejected | Surface the stderr message verbatim — it will be a clear actionable error |
+| `2` | Daily quota exhausted | "Daily search quota reached. Anonymous tier resets at 00:00 UTC; for 50 searches/day, set `ASKAIPODS_API_KEY` (sign up at https://podlens.net)." |
+| `3` | Network error / podlens.net unavailable | Retry once after a brief pause; if it fails again, tell the user "PodLens search is temporarily unavailable. Try again in a few minutes." |
+
+If the `results` array is empty (zero matches above the similarity threshold), say so explicitly: "No quotes found for that topic. The corpus is AI-focused — for non-AI topics, try a web search instead. For AI topics, try rephrasing or broadening the query." Do not invent quotes to fill the gap.
+
+Never silently swallow an error. Never fabricate quotes when the API returns nothing.
+
+## Honest limitations to set user expectations
+
+- **No speaker attribution.** The API returns "podcast + episode + quote text" but not "who said it". The upstream pipeline avoids per-speaker attribution because automatic speaker diarization is unreliable — surfacing wrong attribution would be worse than no attribution.
+- **No episode URLs.** The public API does not expose direct links to episodes. Users who want to listen will need to search the podcast and episode title in their podcast app of choice.
+- **AI-focused corpus.** Coverage is dense for AI research, ML engineering, AI investing, and AI policy. Coverage for unrelated topics is sparse and noisy.
+- **Short quote excerpts, not transcripts.** Each result is one extracted "key point" from an episode, typically 1-3 sentences (anonymous tier truncates further). For long-form context, the user will need to listen.
+
+These limitations are not bugs — surfacing them honestly is better than the user discovering them mid-task and losing trust.

package/src/cli.js

@@ -0,0 +1,122 @@
+// CLI entry point — argument parsing, format auto-detection, dispatch.
+//
+// Why it's structured this way:
+//   - parseArgs (Node 18+ stdlib) keeps the package zero-dependency,
+//     which matters for `npx askaipods` cold-start time and for the
+//     skill story (zero install footprint beyond Node itself).
+//   - Format auto-detects from `process.stdout.isTTY`: a human running
+//     `askaipods "..."` in a terminal gets markdown, a host agent that
+//     pipes the output gets JSON. SKILL.md still tells the agent to
+//     pass `--format json` explicitly so the contract isn't load-bearing
+//     on isTTY behavior across shells.
+
+import { parseArgs } from "node:util";
+import { search, AskaipodsError } from "./client.js";
+import { renderJson, renderMarkdown } from "./format.js";
+
+const VERSION = "0.1.0";
+
+const HELP_TEXT = `askaipods ${VERSION} — search AI podcast quotes by topic
+
+USAGE:
+  askaipods <query>
+  askaipods search <query> [options]
+
+OPTIONS:
+  --format <json|markdown>   Output format (default: markdown if TTY, json if piped)
+  --days <N>                 Only return results from the last N days (max 7 for anonymous tier; member tier accepts any value)
+  --api-key <key>            PodLens API key (overrides ASKAIPODS_API_KEY env var)
+  -h, --help                 Show this message
+  -v, --version              Show version
+
+ENVIRONMENT:
+  ASKAIPODS_API_KEY          PodLens API key. Without it: 10 searches/day per IP (anonymous).
+                             With it: 50 searches/day per user (member).
+                             Sign up at https://podlens.net to get one.
+
+EXIT CODES:
+  0  success
+  1  usage error / invalid arguments / API key rejected
+  2  daily quota exhausted
+  3  network error / podlens.net unavailable
+
+EXAMPLES:
+  askaipods "what are people saying about test-time compute"
+  askaipods search "Anthropic safety research" --days 30
+  askaipods "GPU shortage" --format json | jq .results
+`;
+
+function usageError(message) {
+  const err = new AskaipodsError(`${message}\n\nRun 'askaipods --help' for usage.`, 1);
+  return err;
+}
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        format: { type: "string" },
+        days: { type: "string" },
+        "api-key": { type: "string" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (err) {
+    throw usageError(err?.message ?? "could not parse arguments");
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    process.stdout.write(HELP_TEXT);
+    return;
+  }
+  if (values.version) {
+    process.stdout.write(`askaipods ${VERSION}\n`);
+    return;
+  }
+
+  // Allow `askaipods search "query"` or `askaipods "query"`. The
+  // `search` subcommand is purely a usability hint — there is only one
+  // operation today and adding it as a flag-free first positional means
+  // future subcommands (e.g., `askaipods quota`) won't break the v0
+  // muscle memory.
+  let query;
+  if (positionals[0] === "search") {
+    query = positionals.slice(1).join(" ").trim();
+  } else {
+    query = positionals.join(" ").trim();
+  }
+
+  if (!query) {
+    throw usageError("missing query");
+  }
+
+  let days;
+  if (values.days !== undefined) {
+    const n = Number.parseInt(values.days, 10);
+    if (!Number.isFinite(n) || n < 0) {
+      throw usageError("--days must be a non-negative integer");
+    }
+    days = n;
+  }
+
+  const format = values.format ?? (process.stdout.isTTY ? "markdown" : "json");
+  if (format !== "json" && format !== "markdown") {
+    throw usageError(`--format must be 'json' or 'markdown', got '${format}'`);
+  }
+
+  const apiKey = values["api-key"] ?? process.env.ASKAIPODS_API_KEY;
+
+  const response = await search({ query, days, apiKey });
+
+  const output = format === "json" ? renderJson(query, response) : renderMarkdown(query, response);
+
+  process.stdout.write(output);
+  if (!output.endsWith("\n")) process.stdout.write("\n");
+}

package/src/client.js

@@ -0,0 +1,115 @@
+// Thin client for podlens.net /api/search/semantic.
+//
+// Lives in its own file so the CLI layer never has to know about HTTP
+// or status codes — it gets back either a parsed response object or a
+// thrown error carrying a stable exitCode (1=usage, 2=quota, 3=network).
+// That separation lets the test suite mock the network at this seam
+// instead of patching `fetch` globally.
+
+const PODLENS_ENDPOINT = "https://podlens.net/api/search/semantic";
+
+// Hard caps mirror the server's own validation in
+// functions/api/search/semantic.ts so the user gets a fast local error
+// instead of a confusing 400 round-trip.
+const MAX_QUERY_LEN = 300;
+const MIN_QUERY_LEN = 1;
+
+export class AskaipodsError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "AskaipodsError";
+    this.exitCode = exitCode;
+  }
+}
+
+function exitErr(code, message) {
+  return new AskaipodsError(message, code);
+}
+
+export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT }) {
+  if (typeof query !== "string" || query.trim().length < MIN_QUERY_LEN) {
+    throw exitErr(1, "query is required (1-300 characters)");
+  }
+  if (query.length > MAX_QUERY_LEN) {
+    throw exitErr(1, `query too long (max ${MAX_QUERY_LEN} characters)`);
+  }
+
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": "askaipods/0.1.0 (+https://github.com/Delibread0601/askaipods)",
+  };
+  if (apiKey) {
+    headers["X-PodLens-API-Key"] = apiKey;
+  }
+
+  const body = { q: query };
+  if (typeof days === "number" && days > 0) {
+    body.days = days;
+  }
+
+  let response;
+  try {
+    response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    // fetch() throws TypeError on DNS / connection failure / abort.
+    // Treat all of these as exit code 3 (transient/network) so the
+    // SKILL.md can advise "retry in a moment" instead of looking like
+    // a usage error.
+    throw exitErr(3, `network error contacting podlens.net: ${err?.message ?? err}`);
+  }
+
+  // The server always responds with JSON for both success and error
+  // paths (see jsonResponse() in functions/api/search/semantic.ts), so
+  // a non-JSON body means an upstream proxy/CDN is in the way.
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw exitErr(
+      3,
+      `unexpected non-JSON response from podlens.net (HTTP ${response.status}). ` +
+        "An upstream proxy may be interfering — retry in a moment.",
+    );
+  }
+
+  if (response.ok) {
+    return data;
+  }
+
+  // Distinguish 429 cases by inspecting the message: the server uses
+  // distinct strings for "burst limit hit" vs "daily quota exhausted",
+  // and only the latter warrants telling the user about API keys.
+  if (response.status === 429) {
+    const msg = String(data?.error ?? "").toLowerCase();
+    if (msg.includes("quota")) {
+      throw exitErr(
+        2,
+        "daily search quota exhausted. Anonymous tier resets at 00:00 UTC. " +
+          "For 50 searches/day, set ASKAIPODS_API_KEY (sign up at https://podlens.net).",
+      );
+    }
+    throw exitErr(3, "rate limited by podlens.net (too many requests in a short window). Retry in a minute.");
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    throw exitErr(1, `API key rejected: ${data?.error ?? response.statusText}`);
+  }
+
+  if (response.status === 413) {
+    throw exitErr(1, "request body too large (max 2 KB). Shorten the query.");
+  }
+
+  if (response.status === 503) {
+    throw exitErr(3, `podlens.net temporarily unavailable: ${data?.error ?? "service unavailable"}`);
+  }
+
+  if (response.status === 400) {
+    throw exitErr(1, `invalid request: ${data?.error ?? "bad request"}`);
+  }
+
+  throw exitErr(3, `podlens.net error (HTTP ${response.status}): ${data?.error ?? response.statusText}`);
+}

package/src/format.js

@@ -0,0 +1,125 @@
+// Output formatting for askaipods.
+//
+// Two render targets:
+//   - JSON  → consumed by host agents (Claude Code, Codex, etc.) that
+//             will parse the structured payload and reformat it per the
+//             instructions in SKILL.md
+//   - Markdown → consumed by humans running the CLI directly in a
+//                terminal; not used by the agent path
+//
+// Both share the same sort: time descending (newest first). The host
+// agent's job is to optionally split that into "Latest" and "Top
+// Relevant" sub-views — see SKILL.md.
+
+const ANONYMOUS_NOTE =
+  "Anonymous tier: 10 randomized results from top 20, text truncated by rank, " +
+  "dates fuzzed to month. Set ASKAIPODS_API_KEY for 50 searches/day with full text and dates.";
+
+// Lexical compare on YYYY-MM[-DD][THH:MM:SSZ] descending puts newest
+// first regardless of whether the date is a full ISO timestamp (member
+// tier) or a YYYY-MM month-prefix (anonymous tier). Nulls sort to the
+// end so absent-date results don't crowd out the dated ones.
+export function sortByDateDesc(items) {
+  return [...items].sort((a, b) => {
+    const ad = a?.published_at ?? "";
+    const bd = b?.published_at ?? "";
+    if (ad === bd) return 0;
+    if (!ad) return 1;
+    if (!bd) return -1;
+    return bd < ad ? -1 : 1;
+  });
+}
+
+// Build the structured payload an agent will parse. Each result keeps
+// its `api_rank` (1 = most semantically relevant in API order) so the
+// SKILL.md can tell the agent to derive a "Top Relevant" sub-view for
+// member tier without re-querying. For anonymous tier api_rank reflects
+// only the relative order within a randomized subset, not the corpus
+// rank — `render_hint` flags that distinction.
+//
+// `tier` defaults to "anonymous" rather than "unknown" if the upstream
+// response is missing the field, so the SKILL.md tier branch (which
+// only documents `anonymous` and `member`) always lands on a documented
+// path. Anonymous is the safer default because it disables the
+// "Top Relevant" view — better to under-promise relevance ranking than
+// to render a misleading section based on randomized data.
+export function toStructured(query, response) {
+  const tier = response?.meta?.tier ?? "anonymous";
+  const apiResults = Array.isArray(response?.results) ? response.results : [];
+
+  const withRank = apiResults.map((r, idx) => ({ ...r, api_rank: idx + 1 }));
+  const sorted = sortByDateDesc(withRank);
+
+  return {
+    tier,
+    query,
+    fetched_at: new Date().toISOString(),
+    render_hint: tier === "member" ? "dual_view" : "single_view",
+    results: sorted.map((r) => ({
+      podcast: r.podcast_name ?? null,
+      episode: r.episode_title ?? null,
+      date: r.published_at ?? null,
+      text: r.text ?? "",
+      api_rank: r.api_rank,
+    })),
+    meta: {
+      total_returned: typeof response?.total === "number" ? response.total : apiResults.length,
+      quota: response?.meta?.quota ?? null,
+      restrictions: response?.meta?.restrictions ?? null,
+      query_hash: response?.meta?.query_hash ?? null,
+    },
+  };
+}
+
+export function renderJson(query, response) {
+  return JSON.stringify(toStructured(query, response), null, 2);
+}
+
+export function renderMarkdown(query, response) {
+  const data = toStructured(query, response);
+  const lines = [];
+
+  lines.push(`# askaipods · "${query}"`);
+  lines.push("");
+
+  const quota = data.meta.quota;
+  const tierLabel = data.tier;
+  const quotaLabel = quota
+    ? `${quota.used}/${quota.limit} ${quota.period ?? "daily"}`
+    : "unknown";
+  lines.push(`*Tier: ${tierLabel} · Results: ${data.results.length} · Quota: ${quotaLabel}*`);
+  lines.push("");
+
+  if (data.results.length === 0) {
+    lines.push("No results found. Try a different phrasing or broader topic.");
+    if (data.tier === "anonymous") {
+      lines.push("");
+      lines.push(`> ${ANONYMOUS_NOTE}`);
+    }
+    return lines.join("\n");
+  }
+
+  lines.push("## Results — newest first");
+  lines.push("");
+
+  for (let i = 0; i < data.results.length; i++) {
+    const r = data.results[i];
+    const title = r.episode ?? "Untitled episode";
+    const podcast = r.podcast ?? "Unknown podcast";
+    const date = r.date ?? "date unknown";
+    lines.push(`### ${i + 1}. ${podcast} — ${title}`);
+    lines.push(`*${date}*`);
+    lines.push("");
+    // Quote-block the text and collapse newlines so the markdown stays compact.
+    const text = (r.text ?? "").replace(/\s+/g, " ").trim();
+    lines.push(`> ${text}`);
+    lines.push("");
+  }
+
+  if (data.tier === "anonymous") {
+    lines.push("---");
+    lines.push(`*${ANONYMOUS_NOTE}*`);
+  }
+
+  return lines.join("\n");
+}