pocketcast - SKILL.md Agent Skill

name: pocketcast description: This skill should be used when the user asks to "list starred episodes", "check my podcasts", "what am I listening to", "podcast history", "show notes", "podcast info", "search podcasts", "pocketcasts", "pocket casts", or mentions Pocket Casts integration. Provides read-only access to starred episodes, listening history, show notes, and podcast metadata. version: 1.0.0 user-invokable: true

Pocket Casts Integration

This skill provides read-only access to Pocket Casts data through their API. View starred episodes, listening history, show notes, and podcast metadata.

Script Location

The CLI script is located at:

${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts

Run commands using:

npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts <command> [options]

First-Time Setup

Using 1Password (Recommended)

No setup required if you have a "pocketcasts.com" item in 1Password with username/email and password fields.

Using a Credentials File

Create .claude/pocketcast-skill.local.json in your project directory:

{
  "email": "you@example.com",
  "password": "your-pocket-casts-password"
}

Or create a global credentials file at ~/.config/pocketcast-skill/credentials.json with the same format.

Project-local credentials are automatically added to .gitignore.

Available Commands

Starred Episodes

# List all starred episodes
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts starred

Response fields:

count: Total number of starred episodes
episodes: Array of episode objects

Recent Listening History

# Get recent episodes (default: 50)
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts recent

# Get last 10 episodes
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts recent --limit=10

Response fields:

count: Number of episodes returned
limit: Requested limit
episodes: Array of episode objects

Show Notes

# Get show notes for a specific episode
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts shownotes <episode-uuid>

Response fields:

episodeId: The episode UUID
showNotes: HTML content of the show notes

Podcast Info

# Get podcast metadata
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts podcast <podcast-uuid>

Returns full podcast metadata including title, author, description, and episode list.

Episode Metadata

# Get detailed episode metadata
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts episode <episode-uuid>

Returns detailed episode metadata including download URL.

Search

# Search starred and recent episodes by title or podcast name
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts search "search terms"

Searches across both starred and recent episodes. Matches against episode title and podcast name.

Response fields:

query: The search query
count: Number of matching episodes
episodes: Array of matching episode objects

Episode Object Fields

All episode lists return objects with these fields:

id: Episode UUID (use with shownotes, episode commands)
title: Episode title
podcastTitle: Name of the podcast
podcastUuid: Podcast UUID (use with podcast command)
publishedAt: ISO 8601 publish date
duration: Human-readable duration (e.g., "1h 23m")
durationSeconds: Duration in seconds
starred: Whether the episode is starred
played: Whether the episode has been fully played
playedUpTo: How far the user has listened (if partially played)

Response Format

All commands output JSON with a consistent structure:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error responses:

{
  "success": false,
  "error": "Error message here"
}

Common Workflows

See What's Starred

Run: starred
Present the list of starred episodes to the user

Check Recent Listening

Run: recent --limit=10
Summarize what the user has been listening to recently

Get Episode Details

Start with starred or recent to find episodes
Use shownotes <uuid> to get full show notes
Use episode <uuid> for detailed metadata

Find a Specific Episode

Run: search "topic or podcast name"
Present matching episodes

Explore a Podcast

Get podcast UUID from any episode listing
Run: podcast <podcast-uuid>
Present podcast details and episode list

Credential Lookup Order

Project-local: .claude/pocketcast-skill.local.json
Global: ~/.config/pocketcast-skill/credentials.json
1Password: Item named "pocketcasts.com"

Troubleshooting

"Login failed" error

Verify your Pocket Casts email and password are correct
Check that your credentials file has the right format

"No credentials found" error

Create a credentials file (see First-Time Setup) or ensure 1Password CLI is installed and authenticated

Empty results

Ensure you have starred episodes or recent listening history in Pocket Casts