oaustegard avatar

social-and-lifestyle

Social media browsing, content analysis, music control, and everyday utility tools.

version
1.0.0
GitHub stars
404

Install

/plugin install social-and-lifestyle@oaustegard-claude-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.

Contents

Discovered from source

Skills 6

ATProtoing

Reads the atmosphere from sources that stay up when Bluesky PLC's AppView does not. On 2026-08-16 the AppView timed out and Jetstream returned 503 while PDSes and Constellation served every request — this skill is built around that split.

Invoke

python3 <skill>/scripts/atproto.py <command> [--json]

Digest output is the default and is what belongs in a transcript. Reach for --json only when the result will be transformed programmatically; raw records are large and re-reading them into context defeats the purpose.

CommandAnswers
feed [actor] [--hours 3] [--html PATH]The Following timeline, threaded
status [--actor X]Which layer is broken right now
interactions <actor> [--hours 8] [--scan 100]Who liked/replied/reposted/quoted recent posts
thread <at-uri>Replies to a post
posts <actor> [--limit]An actor's posts, from their own PDS
records <actor> <collection>Any collection in any repo
resolve <actor>DID, handle, PDS host
backlinks <target> [--collection C --path P]What references a record or account, in ANY lexicon
identity <actor>Handle renames and PDS migrations, from the PLC audit log
lexicons [query] [--hours N] [--others] [--schema NSID]Which collections are active network-wide

Source model

Each read targets the cheapest source that survives independently. Prefer the PDS for anything a repo owns — it is authoritative and had no outage.

NeedSource
Records of a known repoThat repo's PDS
Who interacted with a URIConstellation (constellation.microcosm.blue)
handle ↔ DID ↔ PDS, and its historyplc.directory, entryway resolveHandle
Which collections are active network-wideUFOs (ufos-api.microcosm.blue)
Search, feed generators, chatAppView only — no substitute; say so

feed is the one composite read: there is no AppView-free getTimeline, so it rebuilds the Following timeline from follows → PLC → each followee's PDS, then hydrates what the AppView would have inlined — facet byte-ranges to character ranges, blob CIDs to cdn.bsky.app URLs, quote and parent URIs to fetched records — and threads the result by reply root. --html writes a self-contained Preact reader (same components as austegard.com/bsky/thread-reader.html), so a feed request is one call, not a fan-out the caller re-derives by hand. Ranking, mutes, and blocks live in the AppView and are absent by construction: this is the raw follow graph.

Constellation is the persistent index. Do not rebuild one locally: it already indexes the whole network, is operated independently of Bluesky PLC, and is reachable when the AppView is not.

interactions walks the five Bluesky paths in LINK_PATHS. backlinks walks whatever Constellation has indexed — tangled issues, vouches, list membership, lexicons nobody here has heard of — so reach for it when the question is "who references this, anywhere" rather than "who liked this post". Both are two-phase for the same reason: links/all reports which sources are non-empty, and only then does enumeration cost anything.

lexicons answers a different question from sample_firehose in browsing-bluesky: UFOs consumes Jetstream and rolls it up per NSID, so a single call reports what is running across the whole network without sampling anything here. --others drops app.bsky., chat.bsky. and com.atproto., which is what turns the leaderboard from "Bluesky is large" into a list of the other apps. --schema NSID fetches the published lexicon document from the publisher's own repo, deriving the publisher by the reverse-DNS convention (com.whtwnd.blog.entry → whtwnd.com); publishing that record is optional and plenty of busy collections skip it, so a miss is a fact about the publisher, not a failure.

Cost shape

State is a /tmp SQLite scratch (ATPROTO_CACHE to relocate), session-scoped by design. Cold start is the only start, and that is fine because wall-clock and token cost are decoupled — the script absorbs the HTTP fan-out and returns a digest. Measured: interactions --hours 8 over 100 posts ≈ 18s and ~30 output lines, against ~15 tool calls doing it by hand.

interactions is two-phase on purpose: one cheap links/all per post reports which link paths are non-empty, so per-path enumeration only runs where something exists. Preserve that when extending.

Handling failure

Unavailable is raised for egress blocks, 4xx, and exhausted retries; the CLI exits 2 with the reason on stderr. Report which layer failed rather than retrying blindly — "the AppView is down" and "atproto is down" are different facts and the distinction is usually the answer the user wants.

Two known limits worth stating plainly when they bite:

  • Third-party PDSes may be egress-blocked. ~3% of a typical follow graph self-hosts (eurosky.social, blacksky.app, personal PDSes). Those reads fail with a clear allowlist message; add the host to project egress settings.
  • Times come from TIDs, decoded from the record key rather than fetched. Client-generated, so treat them as approximate ordering, not attestation.

Overlap with the Atmosphere MCP

aturi.to/api/mcp (hosted, keyless, read-only, beta) covers the same three areas and about 30 more. It was measured on 2026-08-28 at 38 tools / ~8.6k tokens of schema resident per session, returning pretty-printed JSON rather than digests, with every read routed through one host. These commands go straight to plc.directory, Constellation and UFOs, which is the point of this skill — the 2026-08-16 split is exactly the case a single upstream reintroduces. Use the MCP for what it alone has: the waypoint catalog and the atproto docs search. Do not route these three through it.

Writing

This skill reads. For posting, use muninn_utils.bsky_card — it already writes straight to the PDS (facets, blobs, embeds, create_session) and therefore works during an AppView outage. muninn_utils.bsky_limit enforces the 300-grapheme cap, which len() gets wrong on emoji and combining marks.

Browsing Bluesky

Access Bluesky content through public APIs and real-time firehose. Supports optional authentication for personalized feeds. Includes account analysis for categorization.

Implementation

Add skill directory to path and import:

import sys
sys.path.insert(0, '/path/to/skills/browsing-bluesky')  # or use .claude/skills symlink path
from browsing_bluesky import (
    # Core browsing
    search_posts, get_user_posts, get_profile, get_feed_posts, sample_firehose,
    get_thread, get_quotes, get_likes, get_reposts,
    get_followers, get_following, search_users,
    # Trending
    get_trending, get_trending_topics,
    # Account analysis
    get_all_following, get_all_followers, extract_post_text,
    extract_keywords, analyze_account, analyze_accounts,
    # Authentication utilities
    is_authenticated, get_authenticated_user, authenticated_identity,
    clear_session
)

Authentication (Optional)

Authentication enables personalized feeds (like Paper Skygest) that require knowing who's asking.

Setup

  1. Create an app password at Bluesky: Settings → Privacy and Security → App Passwords
  2. Set environment variables:
    export BSKY_HANDLE="yourhandle.bsky.social"
    export BSKY_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
    

Which account reads

Two credential pairs are recognised, and the prefix is the only difference:

PairIdentity
MUNINN_BSKY_HANDLE / MUNINN_BSKY_APP_PASSWORDmuninn — preferred
BSKY_HANDLE / BSKY_APP_PASSWORDowner — used when no Muninn pair is set

BSKY_IDENTITY=muninn|owner picks one outright, and a pair named that way is never substituted for: asking for muninn with no Muninn pair set reads as public rather than quietly reading as the owner. An unrecognised value raises.

This matters because a booted container holds both pairs. Until 2026-08-28 the unprefixed one won, so every authenticated read — the following timeline, and the mutes, blocks and labelers that shape all of them — came back as the account owner with nothing in the output saying so, from a skill documented as read-only that was nonetheless holding an app password carrying write scope on his account. On a machine with only the documented BSKY_* pair, nothing changes.

Behavior

  • Transparent: All functions work identically with or without credentials
  • Automatic: Auth headers are added opportunistically when credentials exist
  • Graceful: Failed auth silently falls back to public access. A misspelled BSKY_IDENTITY is configuration, not auth failure, and raises instead
  • Secure: Tokens cached in memory only, never logged or persisted

Check Auth Status

if is_authenticated():
    print(f"Logged in as: {get_authenticated_user()}")
else:
    print("Using public access")

# Which pair answered — a handle alone does not say whether it was chosen
# or simply the only one set.
authenticated_identity()   # {'identity': 'muninn', 'handle': ..., 'did': ...}

# Clear session if needed (e.g., switching accounts or identities)
clear_session()

Research Workflows

Investigate a Topic

Use search_posts() with query syntax matching bsky.app advanced search:

  • Basic terms: event sourcing
  • Exact phrases: "event sourcing"
  • User filter: from:acairns.co.uk or use author= param
  • Date filter: since:2025-01-01 or use since= param
  • Hashtags, mentions, domain links: #python mentions:user domain:github.com

Combine query syntax with function params for complex searches.

Monitor a User

  1. Fetch profile with get_profile(handle) for context (bio, follower count, post count)
  2. Get recent posts with get_user_posts(handle, limit=N)
  3. For topic-specific user content, use search_posts(query, author=handle)

Discover What's Trending

Recommended workflow — trending API first, firehose for deep dives:

1. Quick scan with trending topics (~500 tokens)
topics = get_trending_topics(limit=10)
# Returns: {topics: [{topic, display_name, description, link}, ...],
#           suggested: [...]}
2. Rich trends with post counts and actors
trends = get_trending(limit=10)
for t in trends:
    print(f"{t['display_name']} — {t['post_count']} posts ({t['status']})")
# Each trend includes: topic, display_name, link, started_at,
#   post_count, status, category, actors
3. Targeted exploration of selected trends
posts = search_posts(trend["topic"], limit=25)
4. Optional: Firehose for velocity monitoring or long-tail discovery

Prerequisites: Install Node.js dependencies once per session:

cd /home/claude && npm install ws https-proxy-agent 2>/dev/null
data = sample_firehose(duration=30)  # Full firehose sample
data = sample_firehose(duration=20, filter="python")  # Filtered sample

Returns dict with keys:

  • window: {startTime, endTime, durationSeconds} — sampling time range
  • stats: {totalReceived, totalPosts, postsPerSecond, filter, languages} — volume metrics and language breakdown
  • topWords: [[word, count], ...] — top 50 words (count >= 3)
  • topPhrases: [[bigram, count], ...] — top 30 bigrams (count >= 2)
  • topTrigrams: [[trigram, count], ...] — top 20 trigrams (count >= 2)
  • entities: [[entity, count], ...] — top 25 handles/hashtags (count >= 2)
  • samplePosts: [{text, altTexts, hasImages}, ...] — first 50 matching posts

Read Feeds and Lists

get_feed_posts() accepts:

  • List URLs: https://bsky.app/profile/austegard.com/lists/3lankcdrlip2f
  • Feed URLs: https://bsky.app/profile/did:plc:xxx/feed/feedname
  • AT-URIs: at://did:plc:xxx/app.bsky.graph.list/xyz

The function extracts the AT-URI from URLs automatically.

Explore a Thread

Fetch full thread context for a post with parents and replies:

thread = get_thread("https://bsky.app/profile/user/post/xyz", depth=10)
# Returns: {post: {...}, parent: {...}, replies: [...]}

Find Quote Posts

Discover posts that quote a specific post:

quotes = get_quotes("https://bsky.app/profile/user/post/xyz")
for q in quotes:
    print(f"@{q['author_handle']}: {q['text'][:80]}")

Analyze Engagement

Get users who engaged with a post:

likes = get_likes(post_url)
reposts = get_reposts(post_url)

# Accepts both URLs and AT-URIs
likes = get_likes("at://did:plc:.../app.bsky.feed.post/...")

Read Embed Images

Every parsed post carries an images field — a list of {alt, url, transcription} dicts, one per embed image. The legacy image_alts: list[str] field is preserved (non-empty alts only).

When alt text is missing and the image content matters, opt in to model transcription via the transcribe parameter on any post-fetch function (get_user_posts, search_posts, get_feed_posts, get_thread, get_quotes):

# Routine/bulk work (zeitgeist, inbox review, news scans) —
# gemini-lite (gemini-3.5-flash-lite) is the recommended default,
# ~$0.0009 per image:
posts = get_user_posts("ayourtch.bsky.social", limit=40, transcribe="gemini-lite")

# gemini-flash runs Gemini 4 Hydrogen (Google's current default model) at
# thinking_level='low' — for images whose content needs reasoning, not just
# reading (~8x lite):
posts = get_user_posts(..., transcribe="gemini-flash")

# Anthropic single-vendor option (note: empirically weaker prompt-following
# than Gemini on dense transcription — Haiku tends to summarize rather
# than transcribe):
posts = get_user_posts(..., transcribe="haiku")

# Interactive sessions where image is part of the active task and you want
# conversation context to inform interpretation (only available on Anthropic):
thread = get_thread(post_url, transcribe="opus")

# Default: no transcription
posts = get_user_posts("ayourtch.bsky.social", limit=40)

Policy is invariant across all callers: images with non-empty alt text are never transcribed (the author already described the image; trust it). Only images with missing or empty alt are sent to the model. Network or API failures leave transcription as None; callers degrade silently.

Cost/quality empirics. "Token recall" is the share of the text tokens in the image that appear in the transcription. The two tables come from different test sets, so compare rows within a table, not across them.

Gemini, measured 2026-11-20 on 3 synthetic terminal and table screenshots, one run each. Both models read every token, so this set separates them on cost and speed, not accuracy:

AliasModelLatency$/imageToken recall
gemini-litegemini-3.5-flash-lite~2s~$0.0009100%
gemini-flashgemini-4-hydrogen~6s~$0.007100%

Anthropic, measured May 2026 on 3 real dense terminal screenshots, one run each. The aliases call claude-haiku-5-5 and claude-opus-5-5, which have not been measured; the figures are for the models named here:

AliasMeasured onLatency$/imageToken recall
haikuHaiku 4.5~7s~$0.00818% (summarizes)
opusOpus 4.7~20s~$0.1291%

transcribe="gemini-3.5-flash" also runs gemini-4-hydrogen: the 3.5 Flash model is retired, and the name is kept so existing callers do not break.

Requires either ANTHROPIC_API_KEY (or API_KEY in /mnt/project/claude.env) for the haiku / opus aliases, or CF AI Gateway credentials in /mnt/project/proxy.env for the gemini-* aliases. Transcription only fires when the parameter is set, so callers without the relevant credentials can simply pick a different alias or leave the feature off.

Explore Social Graph

Navigate follower/following relationships:

followers = get_followers("handle.bsky.social")
following = get_following("handle.bsky.social")

# Returns list of actor dicts with handle, display_name, did, description, etc.

Find Users

Search for users by name, handle, or bio:

users = search_users("machine learning researcher")
for u in users:
    print(f"{u['display_name']} (@{u['handle']}): {u['description'][:100]}")

API Endpoint Notes

  • Public AppView: https://api.bsky.app/xrpc/ for unauthenticated reads
  • PDS: https://bsky.social/xrpc/ for authenticated requests
  • Trending: app.bsky.unspecced.getTrends (rich) and app.bsky.unspecced.getTrendingTopics (lightweight)
  • Firehose: wss://jetstream1.us-east.bsky.network/subscribe
  • Endpoint routing is automatic - authenticated requests go to PDS, public requests go to AppView
  • Rate limits exist but are generous for read operations

Return Format

All API functions return structured dicts with:

  • uri: AT protocol identifier
  • text: Post content
  • created_at: ISO timestamp
  • author_handle: User handle
  • author_name: Display name
  • likes, reposts, replies: Engagement counts
  • links: Full URLs extracted from post facets (post text truncates URLs with "...")
  • image_alts: Alt text from embedded images
  • url: Direct link to post on bsky.app

Profile function returns: handle, display_name, description, followers, following, posts, did

Account Analysis

Analyze accounts for categorization by topic. Fetches profile and posts, extracts keywords, and returns structured data for Claude to categorize.

Analyze a User's Network

# Analyze accounts you follow
results = analyze_accounts(following="yourhandle.bsky.social", limit=50)

# Analyze your followers
results = analyze_accounts(followers="yourhandle.bsky.social", limit=50)

# Analyze specific handles
results = analyze_accounts(handles=["user1.bsky.social", "user2.bsky.social"])

Single Account Analysis

analysis = analyze_account("user.bsky.social")
# Returns: {handle, display_name, description, keywords, post_count, followers, following}

Keyword Extraction Options

Stopwords parameter filters domain-specific noise:

  • "en": English (general purpose, default)
  • "ai": AI/ML domain (filters tech boilerplate)
  • "ls": Life Sciences (filters research methodology)
results = analyze_accounts(following="handle", stopwords="ai")

Requires: extracting-keywords skill with YAKE venv for keyword extraction.

Filtering Accounts

results = analyze_accounts(
    following="handle",
    exclude_patterns=["bot", "spam", "promo"]  # Skip accounts matching these
)

Paginated Following/Followers

For large account lists beyond the 100 limit of get_following/get_followers:

all_following = get_all_following("handle", limit=500)  # Handles pagination
all_followers = get_all_followers("handle", limit=500)

Account Analysis Output

Each analyzed account returns:

{
    "handle": "user.bsky.social",
    "display_name": "User Name",
    "description": "Bio text here",
    "keywords": ["keyword1", "keyword2", "keyword3"],
    "post_count": 20,
    "followers": 1234,
    "following": 567
}

Claude uses bio + keywords to categorize accounts by topic without hardcoded rules

Categorizing Bluesky Accounts

Fetch Bluesky account data and extract keywords for Claude to categorize by topic. The script compresses account context (bio + posts) into bio + keywords, then Claude performs intelligent categorization.

Prerequisites

Requires: extracting-keywords skill (provides YAKE venv + domain stopwords)

The analyzer delegates keyword extraction to the extracting-keywords skill, which provides:

  • Optimized YAKE installation with minimal dependencies
  • Domain-specific stopwords: English (574), AI/ML (1357), Life Sciences (1293)
  • Support for 34 languages

Core Workflow

When users request Bluesky account analysis:

  1. Ensure keyword extraction is set up - Invoke the extracting-keywords skill using the Skill tool to ensure YAKE venv exists (skip if already invoked in this session)

  2. Determine input mode based on user's request:

    • Following list → use --following handle
    • Followers → use --followers handle
    • List of handles → use --handles "h1,h2,h3"
    • File provided → use --file accounts.txt
  3. Configure parameters:

    • --accounts N - Number to analyze (default: 100, max: 100)
    • --posts N - Posts per account (default: 20, max: 100)
    • --stopwords [en|ai|ls] - Choose domain-specific stopwords:
      • en: English (general purpose)
      • ai: AI/ML domain (recommended for tech accounts)
      • ls: Life Sciences (for biomedical/research accounts)
    • --exclude "pattern1,pattern2" - Skip spam/bot accounts
  4. Run script - Outputs simple text format to stdout:

    @handle1.bsky.social (Display Name)
    Bio text here
    Keywords: keyword1, keyword2, keyword3
    
    @handle2.bsky.social (Another Name)
    Bio text here
    Keywords: keyword4, keyword5, keyword6
    
  5. Categorize accounts - Claude analyzes bio + keywords to categorize by topic

Quick Start

Analyze following list with AI/ML stopwords:

python scripts/bluesky_analyzer.py --following austegard.com --stopwords ai

Analyze followers:

python scripts/bluesky_analyzer.py --followers austegard.com

Analyze specific handles:

python scripts/bluesky_analyzer.py --handles "user1.bsky.social,user2.bsky.social,user3.bsky.social"

From file:

python scripts/bluesky_analyzer.py --file accounts.txt --stopwords ai

Filter out bot accounts:

python scripts/bluesky_analyzer.py --following handle --exclude "bot,spam,promo" --stopwords ai

Parameters

Input Modes (choose one)

--handles "h1,h2,h3" Comma-separated list of Bluesky handles

--following HANDLE Analyze accounts followed by HANDLE

--followers HANDLE Analyze accounts following HANDLE

--file PATH Read handles from file (one per line)

Analysis Options

--accounts N Number of accounts to analyze (1-100, default: 100)

--posts N Posts to fetch per account (1-100, default: 20)

--stopwords [en|ai|ls] Stopwords to use for keyword extraction (default: en)

  • en: English stopwords (574 terms) - general purpose
  • ai: AI/ML domain stopwords (1357 terms) - tech-focused accounts
  • ls: Life Sciences stopwords (1293 terms) - biomedical/research accounts

--exclude "word1,word2" Skip accounts with these keywords in bio/posts

Output Format

The script outputs simple text format for Claude to process:

@alice.bsky.social (Alice Smith)
AI researcher working on LLM alignment and safety
Keywords: alignment, safety research, interpretability, llm evaluation

@bob.bsky.social (Bob Johnson)
Full-stack developer building web applications
Keywords: react, typescript, node.js, api design, postgresql

@carol.bsky.social (Carol Williams)
Biotech researcher studying CRISPR applications
Keywords: crispr, gene editing, therapeutics, clinical trials

Claude then categorizes accounts based on bio + keywords without hardcoded rules.

Common Workflows

Audit Your Following List

python scripts/bluesky_analyzer.py --following your-handle.bsky.social --stopwords ai

Claude will categorize accounts by topic and identify patterns in who you follow.

Find Experts in a Topic

python scripts/bluesky_analyzer.py --following alice.bsky.social --stopwords ai

Ask Claude: "Which of these accounts are ML researchers?" or "Who focuses on climate tech?"

Analyze a Curated List

cat > accounts.txt << 'EOF'
expert1.bsky.social
expert2.bsky.social
expert3.bsky.social
EOF

python scripts/bluesky_analyzer.py --file accounts.txt --stopwords ls

Filter Out Bot Accounts

python scripts/bluesky_analyzer.py --following handle --exclude "bot,spam,promo,follow back" --stopwords ai

Technical Details

Keyword Extraction

Delegates to extracting-keywords skill using YAKE venv:

  • Stopwords options (--stopwords):
    • en: English (574 terms) - general purpose
    • ai: AI/ML domain (1357 terms) - filters technical noise, ML boilerplate
    • ls: Life Sciences (1293 terms) - filters research methodology, clinical terms
  • N-grams: 1-3 words
  • Deduplication: 0.9 threshold
  • Top keywords: 10 per account
  • Performance: ~5% overhead with domain stopwords vs English

API Rate Limits

Bluesky API limits:

  • 3000 requests per 5 minutes
  • 5000 requests per hour

The analyzer respects these limits with built-in delays.

Categorization Algorithm

Script's role:

  1. Fetch account data (bio + posts)
  2. Extract keywords to compress context
  3. Output bio + keywords in simple format

Claude's role:

  1. Read bio + keywords for each account
  2. Intelligently categorize by topic (no hardcoded rules)
  3. Group accounts, identify patterns, answer user questions

This agentic pattern is more flexible than hardcoded keyword matching.

Troubleshooting

"No accounts to analyze"

  • Verify handle format (include domain: handle.bsky.social)
  • Check if account exists and has public following/followers

"Insufficient content for keyword extraction"

  • Account has few posts (<5)
  • Posts are very short
  • Try increasing --posts parameter

Rate limit errors

  • Reduce --accounts parameter
  • Add delays between batches
  • Check Bluesky API status

Import errors

  • Verify extracting-keywords skill is available
  • Check YAKE venv exists: /home/claude/yake-venv/bin/python -c "import yake"
  • Verify Python 3.8+: python3 --version

Integration with Other Skills

Built-in integration:

  • extracting-keywords: Automatically delegates keyword extraction to this skill's optimized YAKE venv with domain-specific stopwords

Categorizing Output

Group accounts by topic from their bio + keywords, using judgment rather than a fixed taxonomy — the categories and counts follow from what's actually in the data, not a template.

Controlling Spotify

Control Spotify playback, search for music, and manage playlists using the Spotify MCP Server with full user account access.

When to Use

Invoke this skill when users request:

  • Playing, pausing, or skipping music on Spotify
  • Searching for songs, albums, artists, or playlists
  • Creating or modifying playlists
  • Viewing currently playing track or playback status
  • Managing their Spotify library (saved tracks, albums)
  • Queuing songs or albums

Prerequisites

CRITICAL: This skill requires user-provided credentials. The user must complete a one-time setup:

One-Time User Setup

  1. Create Spotify Developer Application

  2. Obtain Refresh Token

    • User must run the helper script locally (see references/setup-guide.md)
    • Script exchanges OAuth code for a long-lived refresh token
    • Refresh token is saved as credential in skill configuration
  3. Configure Credentials

    • Add three credentials to this skill:
      • SPOTIFY_CLIENT_ID: From Spotify Developer Dashboard
      • SPOTIFY_CLIENT_SECRET: From Spotify Developer Dashboard
      • SPOTIFY_REFRESH_TOKEN: From helper script output

    Alternative: Credentials can also be provided via a Project Knowledge file. Ensure the file contains a .env style block with the keys above.

Without these credentials, the skill cannot function. If credentials are missing, guide the user through the setup process detailed in references/setup-guide.md.

MCP Server Installation

The Spotify MCP Server must be installed in the compute environment. Use the provided installation script which handles cloning, patching, and building the server.

# Run the installation script
bash scripts/install-mcp-server.sh

MCP Server Configuration

Configure the MCP client to connect to the Spotify MCP server. Note the logic to support credentials from Project Knowledge.

from mcp import Client
import asyncio
import re

# 1. Try to get credentials from skill configuration
env_vars = {
    "SPOTIFY_CLIENT_ID": credentials.get("SPOTIFY_CLIENT_ID"),
    "SPOTIFY_CLIENT_SECRET": credentials.get("SPOTIFY_CLIENT_SECRET"),
    "SPOTIFY_REFRESH_TOKEN": credentials.get("SPOTIFY_REFRESH_TOKEN")
}

# 2. If missing, look in Project Knowledge / Context for .env style block
if not all(env_vars.values()):
    # Heuristic: Scan context/files for VAR=VALUE patterns
    # (Pseudo-code: Implement based on available context access)
    pass

# Server configuration
mcp_config = {
    "command": "node",
    "args": ["/home/claude/spotify-mcp-server/build/index.js"],
    "env": env_vars
}

# Initialize client
async def initialize_spotify_mcp():
    client = Client()
    await client.connect_stdio(
        mcp_config["command"],
        mcp_config["args"],
        mcp_config["env"]
    )
    return client

Available Tools

Read Operations

  1. searchSpotify - Search for tracks, albums, artists, or playlists

    result = await client.call_tool("searchSpotify", {
        "query": "bohemian rhapsody",
        "type": "track",
        "limit": 10
    })
    
  2. getNowPlaying - Get currently playing track information

    result = await client.call_tool("getNowPlaying", {})
    
  3. getMyPlaylists - List user's playlists

    result = await client.call_tool("getMyPlaylists", {
        "limit": 20,
        "offset": 0
    })
    
  4. getPlaylistTracks - Get tracks from a playlist

    result = await client.call_tool("getPlaylistTracks", {
        "playlistId": "37i9dQZEVXcJZyENOWUFo7"
    })
    
  5. getRecentlyPlayed - Get recently played tracks

    result = await client.call_tool("getRecentlyPlayed", {
        "limit": 10
    })
    
  6. getUsersSavedTracks - Get user's liked songs

    result = await client.call_tool("getUsersSavedTracks", {
        "limit": 50,
        "offset": 0
    })
    

Playback Control

  1. playMusic - Start playing track/album/artist/playlist

    # Play by URI
    result = await client.call_tool("playMusic", {
        "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
    })
    
    # Or by type and ID
    result = await client.call_tool("playMusic", {
        "type": "track",
        "id": "6rqhFgbbKwnb9MLmUQDhG6"
    })
    
  2. pausePlayback - Pause current playback

    result = await client.call_tool("pausePlayback", {})
    
  3. skipToNext - Skip to next track

    result = await client.call_tool("skipToNext", {})
    
  4. skipToPrevious - Skip to previous track

    result = await client.call_tool("skipToPrevious", {})
    
  5. addToQueue - Add track/album to playback queue

    result = await client.call_tool("addToQueue", {
        "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
    })
    

Playlist Management

  1. createPlaylist - Create new playlist

    result = await client.call_tool("createPlaylist", {
        "name": "My Workout Mix",
        "description": "High energy tracks",
        "public": False
    })
    
  2. addTracksToPlaylist - Add tracks to existing playlist

    result = await client.call_tool("addTracksToPlaylist", {
        "playlistId": "3cEYpjA9oz9GiPac4AsH4n",
        "trackUris": [
            "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
            "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
        ]
    })
    

Album Operations

  1. getAlbums - Get album details

    result = await client.call_tool("getAlbums", {
        "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"]
    })
    
  2. getAlbumTracks - Get tracks from album

    result = await client.call_tool("getAlbumTracks", {
        "albumId": "4aawyAB9vmqN3uQ7FjRGTy"
    })
    
  3. saveOrRemoveAlbumForUser - Save/remove albums

    result = await client.call_tool("saveOrRemoveAlbumForUser", {
        "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"],
        "action": "save"
    })
    

Workflow Examples

Example 1: Play User's Favorite Song

# 1. Search for the song
search_result = await client.call_tool("searchSpotify", {
    "query": "user's favorite song name",
    "type": "track",
    "limit": 1
})

# 2. Extract track URI from results
track_uri = search_result["tracks"][0]["uri"]

# 3. Play the track
await client.call_tool("playMusic", {
    "uri": track_uri
})

Example 2: Create Playlist from Genre

# 1. Search for tracks in genre
search_result = await client.call_tool("searchSpotify", {
    "query": "genre:rock year:2020-2024",
    "type": "track",
    "limit": 20
})

# 2. Create new playlist
playlist_result = await client.call_tool("createPlaylist", {
    "name": "Modern Rock Mix",
    "description": "Recent rock tracks",
    "public": False
})

# 3. Extract track URIs
track_uris = [track["uri"] for track in search_result["tracks"]]

# 4. Add tracks to playlist
await client.call_tool("addTracksToPlaylist", {
    "playlistId": playlist_result["id"],
    "trackUris": track_uris
})

Example 3: Show What's Playing

# Get current playback state
now_playing = await client.call_tool("getNowPlaying", {})

# Format and display
print(f"Now Playing: {now_playing['track']['name']}")
print(f"Artist: {now_playing['track']['artists'][0]['name']}")
print(f"Album: {now_playing['track']['album']['name']}")
print(f"Progress: {now_playing['progress_ms']} / {now_playing['duration_ms']} ms")

Important Notes

Spotify Premium Required

Playback control operations (play, pause, skip, queue) require Spotify Premium. Read operations (search, get playlists, view tracks) work with free accounts.

Active Device Required

For playback commands to work, the user must have an active Spotify session (web player, desktop app, mobile app) with a device available. If no active device, playback commands will fail.

Rate Limits

Spotify API has rate limits (typically 180 requests per minute). For bulk operations, implement appropriate delays or batching.

Token Security

  • Refresh tokens grant full access to user's Spotify account
  • Never log or expose refresh tokens
  • Treat them with the same security as passwords
  • Users can revoke tokens from https://www.spotify.com/account/apps/

URI Format

Spotify uses URIs in the format:

  • Track: spotify:track:ID
  • Album: spotify:album:ID
  • Artist: spotify:artist:ID
  • Playlist: spotify:playlist:ID

Most tools accept either URIs or separate type + id parameters.

Troubleshooting

"Spotify configuration not found"

Cause: Missing environment variables

Solution: Verify credentials are properly configured:

import os
print(os.getenv("SPOTIFY_CLIENT_ID"))  # Should not be None
print(os.getenv("SPOTIFY_CLIENT_SECRET"))  # Should not be None
print(os.getenv("SPOTIFY_REFRESH_TOKEN"))  # Should not be None

"No active device"

Cause: No Spotify client is currently running/active

Solution: Guide user to:

  1. Open Spotify on any device (web, desktop, mobile)
  2. Start playing something (can pause immediately)
  3. Try the playback command again

"Premium required"

Cause: User has Spotify Free account

Solution: Playback control requires Spotify Premium. Only search and read operations available for free accounts.

MCP Server Won't Start

Cause: Missing dependencies or incorrect installation

Solution:

# Re-run installation script
bash scripts/install-mcp-server.sh

Best Practices

  1. Always search before playing - Don't assume URIs, search for content first
  2. Check playback state - Use getNowPlaying to verify device availability
  3. Handle errors gracefully - Provide helpful messages when operations fail
  4. Batch operations - When adding multiple tracks, use single call with array
  5. Respect rate limits - Add delays for bulk operations

References

Security

This skill requires sensitive credentials. Ensure:

  • Credentials are stored securely in skill configuration
  • Never expose credentials in responses to users
  • Never log credentials
  • Users understand they can revoke access anytime

See references/setup-guide.md for detailed security best practices.

WAFFLES Declaration Generator

Generate preemptive clarifications listing what a post explicitly does NOT say, helping low-context readers avoid misinterpretation.

Background

"WAFFLES" originated from Bluesky's October 2025 controversy. A meme satirized how users read hostile implications into innocuous posts: "(bluesky user bursts into Waffle House) OH SO YOU HATE PANCAKES??" CEO Jay Graber's reply of "WAFFLES!" to an off-topic comment sparked platform-wide debate. The term evolved into a declaration format pioneered by @gracekind.net — a preemptive list of things a post does NOT claim.

When Triggered

Generate a WAFFLES Declaration when user:

  • Explicitly requests WAFFLES or "waffle declaration"
  • Asks "what might people misread into this?"
  • Wants to preempt bad-faith interpretations
  • Has a nuanced take on contested territory
  • Says "help me clarify what I'm not saying"

Generation Process

Given post text, produce 12-20 declarations across these dimensions:

CategoryWhat to identify
Emotional scopeExtremes, permanence, or intensity not claimed
UniversalityGeneralizations the author isn't making
Policy/advocacyPositions not being endorsed
JudgmentsEvaluations not being rendered
Temporal claimsTimelines or permanence not asserted
Adjacent hot-takesRelated controversial positions not implied
InversesOpposite claims also not being made
Meta-claimsAuthority or expertise not asserted

Output Format

🧇 WAFFLES DECLARATION 🦋
aka things this post doesn't say:

— [declaration 1]
— [declaration 2]
...

Use varied phrasing:

  • "This post does not claim..."
  • "The author is not saying..."
  • "This is not an argument that..."
  • "Nothing here suggests..."

Quality Criteria

Declarations should be:

  • Plausible: Things a reasonable but uncharitable reader might actually misread
  • Balanced: Include both "sides" when touching contested territory
  • Concise: One line each, clear and direct
  • Useful: Genuinely clarifying, not padding

Prioritize likely misinterpretations over implausible ones. A good declaration makes the reader think "oh, I might have assumed that."

Sorting Groceries by Aisle

Sort a user's grocery list by aisle order so they can walk the store in one efficient pass, no backtracking.

When Triggered

Activate when user:

  • Uploads photos of grocery store aisle signs or markers
  • Provides a grocery/shopping list alongside store layout info
  • Asks to sort, organize, or optimize a shopping list by aisle
  • Mentions aisle numbers, store maps, or shopping routes

Inputs

Two inputs are needed. Prompt for whichever is missing:

  1. Aisle sign images — Photos of aisle markers, hanging signs, or endcap labels. Each typically shows an aisle number and category keywords (e.g., "Aisle 5: Coffee, Tea, Cocoa").
  2. Grocery list — Text, pasted note, or photo of a handwritten list. Any format.

Building the Aisle Map

Read each uploaded aisle sign image for its aisle number (or label, e.g. "A5") and category text exactly as printed (e.g., "Pasta, Sauces, Canned Vegetables"). Compile into a structured map:

Aisle 1: Bread, Bakery Items, Tortillas
Aisle 2: Cereal, Breakfast, Granola Bars
Aisle 3: Pasta, Sauces, Canned Goods
...

If an image is blurry or partially unreadable, note what was legible and flag uncertainty rather than guessing.

Perimeter Zones

Grocery stores also have unnumbered perimeter sections. Use the user's own signage wherever their photos cover it; otherwise fall back to this typical layout, run counterclockwise from the entrance:

ZoneTypical items
ProduceFresh fruits, vegetables, herbs, salad mixes
DeliSliced meats, prepared foods, rotisserie chicken
BakeryFresh bread, cakes, pastries (distinct from packaged bread aisle)
DairyMilk, cheese, yogurt, butter, eggs
Meat & SeafoodFresh/frozen meat, poultry, fish
FrozenFrozen meals, ice cream, frozen vegetables

Typical flow: Produce → Deli/Bakery → Meat/Seafood → Dairy → Frozen.

Matching Items to Aisles

Parse every item from the user's list, preserving their original wording alongside any normalized form (e.g. "parm" → parmesan cheese; "2 lbs chicken breast" → chicken breast, 2 lbs). Match each item to the aisle or perimeter zone its category text best fits. When an item could plausibly sit in more than one place (honey: baking vs. condiments), assign the most likely one and add a note rather than guessing silently — see Multi-Aisle Items below. An item that matches nothing goes to "couldn't place" rather than being forced into a guessed aisle.

Output

Present the final list grouped by aisle in store-walk order:

🛒 Sorted Shopping List — [Store Name if known]

PRODUCE
  □ bananas
  □ baby spinach
  □ 3 avocados

AISLE 1 — Bread, Bakery Items, Tortillas
  □ whole wheat bread
  □ flour tortillas

AISLE 2 — Cereal, Breakfast, Granola Bars
  □ oatmeal
  □ granola bars

AISLE 3 — Pasta, Sauces, Canned Goods
  □ spaghetti
  □ marinara sauce
  □ canned black beans

...

DAIRY
  □ 2% milk
  □ shredded mozzarella
  □ eggs (1 dozen)

⚠️ COULDN'T PLACE
  □ birthday candles — not enough aisle info to determine location

Output Formatting Rules

  • Use checkbox format (□) so the list is easy to use on a phone
  • Include the aisle's category description next to the aisle number for quick reference
  • Keep the user's quantities and notes attached to each item
  • Perimeter zones go in logical store-walk order (Produce first, Frozen/Dairy last)
  • Numbered aisles go in ascending order between the perimeter zones
  • Unmatched items go at the end under a clear "couldn't place" heading

Multi-Aisle Items

Some items legitimately live in multiple locations. When this occurs:

  • Place the item in the most common aisle for that store's layout
  • Add a parenthetical note: "(also check Aisle 7)"
  • Common examples: honey (baking vs condiments), tortilla chips (snacks vs Hispanic foods), butter (dairy vs baking)

Handling Ambiguity

  • Blurry/unreadable signs: Note which aisles had unclear text. Ask user to confirm if critical items might be affected.
  • Store-brand categories: Some stores use unusual groupings ("International Foods" might contain pasta in one store). Trust the sign text over assumptions.
  • Missing aisles: If user uploaded signs for aisles 1-5 and 8-12 but not 6-7, note the gap. Items that don't match any uploaded aisle go to "couldn't place" rather than being guessed into missing aisles.

Store Layout Reuse

If the user mentions they shop at this store regularly:

  • Present the aisle map as a clean reference they can save
  • Suggest they can reuse it in future conversations by pasting just the map text instead of re-uploading photos
  • Format the reusable map clearly:
📍 [Store Name] Aisle Map
Aisle 1: Bread, Bakery Items, Tortillas
Aisle 2: Cereal, Breakfast, Granola Bars
...
Produce | Deli/Bakery | Meat & Seafood | Dairy | Frozen

Sponsors

Details

Marketplace
oaustegard/claude-skills
Source
plugins/social-and-lifestyle
Category
Social And Lifestyle
License
MIT
Keywords
atprotoing, browsing-bluesky, categorizing-bsky-accounts, controlling-spotify, making-waffles, sorting-groceries

More from oaustegard/claude-skills

All 14