
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.
Contents
Discovered from sourceSkills 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.
| Command | Answers |
|---|---|
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.
| Need | Source |
|---|---|
| Records of a known repo | That repo's PDS |
| Who interacted with a URI | Constellation (constellation.microcosm.blue) |
| handle ↔ DID ↔ PDS, and its history | plc.directory, entryway resolveHandle |
| Which collections are active network-wide | UFOs (ufos-api.microcosm.blue) |
| Search, feed generators, chat | AppView 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
- Create an app password at Bluesky: Settings → Privacy and Security → App Passwords
- 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:
| Pair | Identity |
|---|---|
MUNINN_BSKY_HANDLE / MUNINN_BSKY_APP_PASSWORD | muninn — preferred |
BSKY_HANDLE / BSKY_APP_PASSWORD | owner — 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_IDENTITYis 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.ukor useauthor=param - Date filter:
since:2025-01-01or usesince=param - Hashtags, mentions, domain links:
#python mentions:user domain:github.com
Combine query syntax with function params for complex searches.
Monitor a User
- Fetch profile with
get_profile(handle)for context (bio, follower count, post count) - Get recent posts with
get_user_posts(handle, limit=N) - 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:
| Alias | Model | Latency | $/image | Token recall |
|---|---|---|---|---|
gemini-lite | gemini-3.5-flash-lite | ~2s | ~$0.0009 | 100% |
gemini-flash | gemini-4-hydrogen | ~6s | ~$0.007 | 100% |
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:
| Alias | Measured on | Latency | $/image | Token recall |
|---|---|---|---|---|
haiku | Haiku 4.5 | ~7s | ~$0.008 | 18% (summarizes) |
opus | Opus 4.7 | ~20s | ~$0.12 | 91% |
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) andapp.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 identifiertext: Post contentcreated_at: ISO timestampauthor_handle: User handleauthor_name: Display namelikes,reposts,replies: Engagement countslinks: Full URLs extracted from post facets (post text truncates URLs with "...")image_alts: Alt text from embedded imagesurl: 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:
-
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)
-
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
- Following list → use
-
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
-
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 -
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 purposeai: AI/ML domain stopwords (1357 terms) - tech-focused accountsls: 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 purposeai: AI/ML domain (1357 terms) - filters technical noise, ML boilerplatels: 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:
- Fetch account data (bio + posts)
- Extract keywords to compress context
- Output bio + keywords in simple format
Claude's role:
- Read bio + keywords for each account
- Intelligently categorize by topic (no hardcoded rules)
- 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
--postsparameter
Rate limit errors
- Reduce
--accountsparameter - 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
-
Create Spotify Developer Application
- Go to https://developer.spotify.com/dashboard/
- Create an app and note the Client ID and Client Secret
- Add redirect URI:
http://127.0.0.1:8888/callback
-
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
- User must run the helper script locally (see
-
Configure Credentials
- Add three credentials to this skill:
SPOTIFY_CLIENT_ID: From Spotify Developer DashboardSPOTIFY_CLIENT_SECRET: From Spotify Developer DashboardSPOTIFY_REFRESH_TOKEN: From helper script output
Alternative: Credentials can also be provided via a Project Knowledge file. Ensure the file contains a
.envstyle block with the keys above. - Add three credentials to this skill:
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
-
searchSpotify - Search for tracks, albums, artists, or playlists
result = await client.call_tool("searchSpotify", { "query": "bohemian rhapsody", "type": "track", "limit": 10 }) -
getNowPlaying - Get currently playing track information
result = await client.call_tool("getNowPlaying", {}) -
getMyPlaylists - List user's playlists
result = await client.call_tool("getMyPlaylists", { "limit": 20, "offset": 0 }) -
getPlaylistTracks - Get tracks from a playlist
result = await client.call_tool("getPlaylistTracks", { "playlistId": "37i9dQZEVXcJZyENOWUFo7" }) -
getRecentlyPlayed - Get recently played tracks
result = await client.call_tool("getRecentlyPlayed", { "limit": 10 }) -
getUsersSavedTracks - Get user's liked songs
result = await client.call_tool("getUsersSavedTracks", { "limit": 50, "offset": 0 })
Playback Control
-
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" }) -
pausePlayback - Pause current playback
result = await client.call_tool("pausePlayback", {}) -
skipToNext - Skip to next track
result = await client.call_tool("skipToNext", {}) -
skipToPrevious - Skip to previous track
result = await client.call_tool("skipToPrevious", {}) -
addToQueue - Add track/album to playback queue
result = await client.call_tool("addToQueue", { "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
Playlist Management
-
createPlaylist - Create new playlist
result = await client.call_tool("createPlaylist", { "name": "My Workout Mix", "description": "High energy tracks", "public": False }) -
addTracksToPlaylist - Add tracks to existing playlist
result = await client.call_tool("addTracksToPlaylist", { "playlistId": "3cEYpjA9oz9GiPac4AsH4n", "trackUris": [ "spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" ] })
Album Operations
-
getAlbums - Get album details
result = await client.call_tool("getAlbums", { "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"] }) -
getAlbumTracks - Get tracks from album
result = await client.call_tool("getAlbumTracks", { "albumId": "4aawyAB9vmqN3uQ7FjRGTy" }) -
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:
- Open Spotify on any device (web, desktop, mobile)
- Start playing something (can pause immediately)
- 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
- Always search before playing - Don't assume URIs, search for content first
- Check playback state - Use
getNowPlayingto verify device availability - Handle errors gracefully - Provide helpful messages when operations fail
- Batch operations - When adding multiple tracks, use single call with array
- Respect rate limits - Add delays for bulk operations
References
- Setup Guide:
references/setup-guide.md - API Documentation: https://developer.spotify.com/documentation/web-api/
- MCP Specification: https://modelcontextprotocol.io/
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:
| Category | What to identify |
|---|---|
| Emotional scope | Extremes, permanence, or intensity not claimed |
| Universality | Generalizations the author isn't making |
| Policy/advocacy | Positions not being endorsed |
| Judgments | Evaluations not being rendered |
| Temporal claims | Timelines or permanence not asserted |
| Adjacent hot-takes | Related controversial positions not implied |
| Inverses | Opposite claims also not being made |
| Meta-claims | Authority 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:
- 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").
- 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:
| Zone | Typical items |
|---|---|
| Produce | Fresh fruits, vegetables, herbs, salad mixes |
| Deli | Sliced meats, prepared foods, rotisserie chicken |
| Bakery | Fresh bread, cakes, pastries (distinct from packaged bread aisle) |
| Dairy | Milk, cheese, yogurt, butter, eggs |
| Meat & Seafood | Fresh/frozen meat, poultry, fish |
| Frozen | Frozen 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- web-and-retrievalv1.0.4
- ai-and-reasoningv2.9.1
- code-intelligencev2.6.0
- data-and-visualizationv1.0.0
- deciding-with-confidencev0.4.0
- declaudingv0.14.0
- delegating-with-contextv0.3.0
- development-toolsv1.2.1
- environment-and-configv2.0.0
- github-and-gitv2.0.1
- knowledge-and-memoryv1.3.0
- media-processingv2.3.0
- skill-developmentv2.6.0