podcast-discovery

Podcast discovery skill for Wherever.Audio. Given a natural-language query, find the right podcast show or episode and return a playable wherever.audio link.

Do NOT use this skill for non-podcast queries (general web search, music, etc.).

Trigger phrases

Use this skill immediately when the user message includes podcast lookup language such as:

• "find podcast", "find the podcast", "look up podcast", "search podcasts"
• "find episode", "podcast episode about", "interview episode", "latest episodes"
• "give me a wherever link", "wherever link", "wherever.audio link", "listen link", "show link"
• named show/host requests like "Radiolab", "Lex Fridman", "Hard Fork", or "Joe Rogan"

When triggered, prioritize link construction over metadata reporting.

Primary Objective (Highest Priority)

Your job is to produce a working Wherever link (

/show

/listen

Success condition:

1. Resolve a valid RSS URL from Clawsica.
2. If

   contentScope = podcast-show

   , immediately return a show link.
3. If

   contentScope = podcast-episode

   and a matching item is found, immediately return an episode link.

Do not stop at metadata, search summaries, or candidate lists if a valid link can be constructed.

Link Templates

Episode (contentScope = podcast-episode):

https://wherever.audio/listen?rssUrl={rss_url}&itemGuid={guid}&fallbackLink={fallback}

Show (contentScope = podcast-show):

https://wherever.audio/show?rssUrl={rss_url}

All

{placeholder}

Action Policy: Link-First, Ask-Last

Default behavior is to execute and return a link in the same response.

Only ask a follow-up question when one of these is true:

• You cannot determine whether the user wants a show vs episode.
• Clawsica returns no plausible show/RSS result after retries.
• Multiple episode candidates are similarly strong and no clear best match exists.

If none of the above apply, do not ask for confirmation. Return the link.

Token Budget Policy

• Run local tooling first and send only compact result fields to the model.
• Never send raw RSS XML, full feed dumps, or large metadata blobs to the model.
• For episode matching, pass only top-ranked candidate rows needed for decision-making and link construction.

Workflow

Step 1 — Classify the query

Before searching, classify the user's query along two dimensions:

intentType — what kind of request?

• specific-podcaster

  — user names a host or show (e.g. "Lex Fridman", "Radiolab")

• specific-topic

  — user describes a topic or guest (e.g. "Geoffrey Hinton interview about AI")

• discovery

  — broad exploration (e.g. "best science podcasts", "podcasts about space")

contentScope — what are they looking for?

• podcast-show

  — a show/feed (e.g. "find the Radiolab podcast")

• podcast-episode

  — a specific episode (e.g. "the Radiolab episode about colors")

Step 2 — Resolve the show

If intentType is

specific-podcaster

If intentType is

specific-topic

discovery

Step 3 — Clawsica show search

Search for podcast shows using the public Clawsica endpoint. This returns show metadata including RSS feed URLs.

curl -s "https://clawsica.wherever.audio/p?q=radiolab"

Returns a JSON array of show objects. Each object includes a

url

Important: Only use the

url

If Clawsica returns no results, try alternate spellings or broader terms. See

references/CLAWSICA_API.md

Step 4 — Branch by contentScope

If contentScope is

podcast-show

Example:

https://wherever.audio/show?rssUrl=https%3A%2F%2Ffeeds.feedburner.com%2Fradiolab

If contentScope is

podcast-episode

Step 5 — Run local feed tooling (required for episode lookup)

For episode lookup, use local tooling instead of manual XML parsing:

python scripts/search_feed_episodes.py --mode search --rss-url "https://feeds.feedburner.com/radiolab" --query "space stories" --limit 5

Optional semantic rerank:

python scripts/search_feed_episodes.py --mode search --rss-url "https://feeds.feedburner.com/radiolab" --query "space stories" --limit 5 --semantic

Compact

search

• top-level keys:

  mode

  ,

  rssUrl

  ,

  query

  ,

  semanticUsed

  ,

  candidateCount

  ,

  candidates

• candidate keys:

  guid

  ,

  title

  ,

  pubDate

  ,

  fallbackLink

  ,

  score

Use these candidate rows to select the best episode. Do not return feed-level metadata unless explicitly requested.

Selection policy:

• Auto-pick when the top

  score

  is clearly stronger than the second candidate.
• If top candidates are near-tied, ask one disambiguation question.

Step 6 — Construct the episode link

Build a wherever.audio episode link using values from the selected

search

• rss_url

  — the feed URL from step 3

• guid

  — candidate

  guid

• fallback

  — candidate

  fallbackLink

Example:

https://wherever.audio/listen?rssUrl=https%3A%2F%2Ffeeds.feedburner.com%2Fradiolab&itemGuid=some-guid-value&fallbackLink=https%3A%2F%2Fradiolab.org%2Fepisode

Present the link to the user along with the episode title and publish date.

Optional utilities — newest and overview

If the user asks for latest episodes from a known feed:

python scripts/search_feed_episodes.py --mode newest --rss-url "https://feeds.feedburner.com/radiolab" --limit 10

Compact

newest

• top-level keys:

  mode

  ,

  rssUrl

  ,

  count

  ,

  items

• item keys:

  guid

  ,

  title

  ,

  pubDate

  ,

  fallbackLink

If the user asks for feed-level metadata:

python scripts/search_feed_episodes.py --mode overview --rss-url "https://feeds.feedburner.com/radiolab"

Compact

overview

• mode

  ,

  rssUrl

  ,

  feedTitle

  ,

  feedDescriptionShort

  ,

  author

  ,

  language

  ,

  lastBuildDate

  ,

  itemCount

Use these utility modes to answer the request directly while keeping payloads compact.

Run the local feed tool (for developers/testing)

Path: scripts/search_feed_episodes.py (relative to the skill directory) Requirements: scripts/requirements.txt (feedparser, rapidfuzz, pytest) Quick start (recommended, cross-platform):

1. Create and activate a virtual environment in the skill folder: python3 -m venv .venv source .venv/bin/activate # macOS / Linux.venv\Scripts\activate # Windows (PowerShell)
2. Install dependencies: pip install -r scripts/requirements.txt
3. Run the tool (examples): python scripts/search_feed_episodes.py --mode overview --rss-url "<RSS_URL>" python scripts/search_feed_episodes.py --mode newest --rss-url "<RSS_URL>" --limit 10 python scripts/search_feed_episodes.py --mode search --rss-url "<RSS_URL>" --query "attack on Iran" --limit 5 --semantic Notes: The tool prints compact JSON matching the skill's expected contracts. Make the script executable (chmod +x scripts/search_feed_episodes.py) for direct execution. Use the venv if system pip is restricted.

Response Format

When a link is available, respond in this order:

1. The Wherever URL (first line).
2. One short line identifying the resolved show/episode.
3. Optional one-line note only if there was ambiguity.

Keep responses concise. Do not include raw metadata dumps unless explicitly requested.

Prohibited Behavior

• Do not return only webpage metadata when a Wherever link can be built.
• Do not ask "Should I proceed?" if required link parameters are already known.
• Do not present candidate options unless disambiguation is truly required.

Privacy

• Do NOT expose internal Clawsica infrastructure details beyond what is documented here.
• The Clawsica search endpoint does not require authentication.
• See

  references/CLAWSICA_API.md

  for the full API reference.
• See

  references/LOCAL_EPISODE_SEARCH.md

  for local feed-tool commands and schema details.

Example prompts

• "Find a Geoffrey Hinton interview episode and give me a wherever.audio link."
• "What episodes cover Radiolab's space stories?"
• "Search for BBC science podcasts about AI."
• "Give me the Lex Fridman podcast."
• "Find the podcast Hard Fork."