From 3297432b5b059d76ac07cc949cd11efd7e7b7d33 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Fri, 27 Mar 2026 13:27:49 -0400 Subject: [PATCH 1/5] feat: add artist-research skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Multi-source research pipeline for music artists — produces intelligence reports with bio, metrics, fan personas, competitive positioning, and revenue opportunities. Uses WebSearch as the backbone, Chartmetric for verified analytics, last30days for social pulse, and MCP tools when available in sandbox. Made-with: Cursor --- artist-research/SKILL.md | 193 ++++++++++++++ artist-research/references/report-template.md | 191 ++++++++++++++ .../references/research-queries.md | 242 ++++++++++++++++++ setup-sandbox | 2 +- 4 files changed, 627 insertions(+), 1 deletion(-) create mode 100644 artist-research/SKILL.md create mode 100644 artist-research/references/report-template.md create mode 100644 artist-research/references/research-queries.md diff --git a/artist-research/SKILL.md b/artist-research/SKILL.md new file mode 100644 index 0000000..aca7f9b --- /dev/null +++ b/artist-research/SKILL.md @@ -0,0 +1,193 @@ +--- +name: artist-research +description: Deep research on a music artist — bio, metrics, fan personas, competitive positioning, and revenue opportunities. Use when setting up a new artist, building an artist knowledge base, researching an artist for the first time, or when the user says "research [artist name]," "deep dive on [artist]," "who is [artist]," "analyze [artist]," or "build a profile for [artist]." Also use when onboarding an artist to the platform and you need comprehensive context before strategizing. This is the go-to skill for any artist intelligence gathering — not just a bio, but the full picture a music manager needs to make decisions. +--- + +# Research Artist + +Deep research on a music artist. Produces a comprehensive intelligence report that any agent can use as a knowledge base when strategizing about campaigns, fan growth, partnerships, and content. + +You are a music manager working with the artist. Your role is to oversee releases, grow the audience, and unlock revenue. Research with that lens — surface what's actionable, not what's obvious. + +## Before You Start + +1. Read the artist's `RECOUP.md` to get their name, slug, and ID (if in a workspace). +2. Read `context/artist.md` if it exists — understand what's already known before researching. +3. Determine your environment — this affects which research tools you use. + +## Research Pipeline + +The skill runs a multi-source pipeline. Every source is optional — the skill works with just WebSearch alone but gets richer with each additional source. Before starting, detect what's available and use the best combination. + +### Detect Available Sources + +Check for each of these before starting. Use whatever you find — don't block if something is missing. + +| Source | How to Check | What It Gives You | +|--------|-------------|-------------------| +| **WebSearch** | Always available | Bio, narrative, cultural context, press coverage, estimated metrics | +| **Chartmetric** | Check for `CHARTMETRIC_REFRESH_TOKEN` env var and `skills/chartmetric/scripts/` | Real streaming metrics across 14 platforms, audience demographics, city-level data, playlist placements, similar artists, career timeline | +| **last30days** | Check for `~/.claude/skills/last30days/scripts/last30days.py` or `.cursor/skills/last30days/scripts/last30days.py` | Reddit and X fan conversations, sentiment, community buzz | +| **MCP tools** | Check if `web_deep_research`, `spotify_search`, `youtube_channels` etc. are available | Perplexity deep research, Spotify/YouTube API data, platform social data | + +### Phase 1: Web Research (Always Runs) + +This is the backbone. It fills in the narrative that numbers alone can't tell — origin story, cultural context, brand identity, industry positioning. + +**If `web_deep_research` MCP tool is available:** +Send a single comprehensive research prompt. Read `references/research-queries.md` for the exact message. Perplexity deep research browses extensively and returns cited results. + +**Otherwise, use WebSearch:** +Run 8-12 targeted searches covering bio, metrics, fans, competition, business, and cultural context. Read `references/research-queries.md` for the full query list. Run searches in parallel when possible. + +WebSearch alone produces a solid report. The phases below add verified data on top. + +### Phase 2: Chartmetric Data (If Available) + +Chartmetric is the richest data source for music analytics. If the `CHARTMETRIC_REFRESH_TOKEN` is configured and the chartmetric skill scripts exist, run this sequence: + +```bash +# 1. Find the artist's Chartmetric ID +python scripts/search_artist.py "{ARTIST_NAME}" + +# 2. Pull core profile and career data +python scripts/get_artist.py {CM_ID} +python scripts/get_artist_career.py {CM_ID} +python scripts/get_artist_insights.py {CM_ID} + +# 3. Streaming metrics (the KPI Dashboard section) +python scripts/get_artist_metrics.py {CM_ID} --source spotify +python scripts/get_artist_metrics.py {CM_ID} --source instagram +python scripts/get_artist_metrics.py {CM_ID} --source tiktok +python scripts/get_artist_metrics.py {CM_ID} --source youtube_channel + +# 4. Audience and geography (the Fan Persona section) +python scripts/get_artist_audience.py {CM_ID} +python scripts/get_artist_audience.py {CM_ID} --platform tiktok +python scripts/get_artist_cities.py {CM_ID} + +# 5. Competitive landscape (the White-Space section) +python scripts/get_similar_artists.py {CM_ID} --by-config --audience high --genre high --limit 10 + +# 6. Playlist presence +python scripts/get_artist_playlists.py {CM_ID} --editorial --limit 20 + +# 7. Complete discography and tracks +python scripts/get_artist_albums.py {CM_ID} +python scripts/get_artist_tracks.py {CM_ID} +``` + +Run these from the chartmetric skill directory. Mark all data from Chartmetric as `[confirmed]` — these are authoritative numbers, not estimates. + +When Chartmetric data contradicts web research, trust Chartmetric and note the discrepancy. The web number is probably stale. + +**If Chartmetric is NOT available:** The report still works. Web research can surface most metrics through press articles, public Chartmetric pages, and social posts. Just mark those numbers as `[estimated]` instead of `[confirmed]`. + +### Phase 3: Social Pulse (last30days — If Available) + +If the last30days skill is installed, run it for the artist name: + +```bash +python3 /last30days.py "{ARTIST_NAME} music" --emit=compact +``` + +What you're looking for: +- Fan conversations and sentiment +- Press coverage reactions +- Community-driven opinions +- Recent momentum or controversy + +This data feeds into Fan Persona Segmentation and Cultural Adjacency Map. If last30days is not available, note it as a data gap. Don't block on this. + +### Phase 4: MCP Platform Data (Sandbox Only — If Available) + +If MCP tools are connected (sandbox environment), supplement with: + +1. **`web_deep_research`** — Deep Perplexity research (if not already used in Phase 1) +2. **`spotify_search`** / **`spotify_artist_top_tracks`** / **`spotify_artist_albums`** — Real-time Spotify data +3. **`youtube_channels`** / **`youtube_channel_video_list`** — YouTube metrics +4. **`artist_deep_research`** — Connected social accounts from the platform + +If you already have Chartmetric data for the same metrics, use Chartmetric as the primary source and note if MCP data differs. Both are authoritative but Chartmetric usually has deeper historical data. + +### Phase 5: Synthesis + +After all available phases complete, synthesize into the report. Read `references/report-template.md` for the full output template. Note which sources you used in the report's YAML frontmatter so future agents know the data quality. + +## Output Architecture + +The research produces two types of output. This distinction matters because agents reading the workspace need to know whether something is a durable fact or a time-bound snapshot. + +### Dynamic Output (The Report) + +Save the full research report as: + +``` +research/artist-intel-YYYY-MM-DD.md +``` + +This is a point-in-time document. It contains metrics, trends, fan personas, competitive analysis, and revenue opportunities. These change. The report should be timestamped and eventually archived when it goes stale. + +If a `research/` directory doesn't exist, create it. + +### Static Context Updates + +After generating the report, check what static context files exist: + +**If `context/artist.md` does NOT exist:** +Create it using the artist-workspace template format (read `references/artist-template.md` from the artist-workspace skill). Populate it with the identity, brand, and voice information extracted from the research. Only include sections where you have real data. + +**If `context/artist.md` DOES exist:** +Do NOT overwrite it. Instead, at the end of the research report, add a "Suggested Context Updates" section that flags any new information that might warrant updating the static profile. The human decides whether to apply those updates. + +**If `context/audience.md` does NOT exist and you have fan data:** +Create it using the audience template from the artist-workspace skill. Populate with the fan persona data from the research. + +**If `context/audience.md` DOES exist:** +Same as artist.md — suggest updates, don't overwrite. + +### Knowledge Base (Sandbox Only) + +If the `create_knowledge_base` MCP tool is available and the artist has an account ID, save the research report to the artist's permanent knowledge base. This makes it accessible to the AI in future conversations. + +## Quality Rules + +1. **No obvious advice.** "Post TikToks" and "run pre-saves" are noise. Every recommendation should be specific to THIS artist's data. +2. **Explain who they are.** A reader with zero context should understand the artist after reading the overview. +3. **Deep metrics over vanity metrics.** Save-to-listener ratios matter more than raw follower counts. Engagement rate matters more than total followers. +4. **Surface unique fan insights.** Psychographics, subculture overlaps, and super-fan behaviors — not just "18-24 year olds." +5. **Cite sources.** Every metric and claim should reference where it came from so future agents can verify. +6. **Flag confidence levels.** Mark data points as `[confirmed]` (from Chartmetric, platform APIs, or official sources), `[estimated]` (from web research — numbers may be outdated), or `[inferred]` (pattern-based conclusions). This helps downstream agents know what to trust. +7. **No NFTs, crypto, or web3** unless the artist has explicitly expressed interest OR their fan base demonstrably aligns. Don't suggest these by default. + +## Report Structure + +Read `references/report-template.md` for the complete output template. The sections are: + +1. **Artist Overview** — Bio, origin, sound, milestones +2. **Career-Stage Assessment** — Where they are and what metrics matter at this stage +3. **Fan-Persona Segmentation** — 3-5 named behavioral archetypes +4. **Platform-Native KPI Dashboard** — Deep metrics most dashboards hide +5. **Cultural Adjacency Map** — Adjacent micro-scenes and overlap signals +6. **Competitive White-Space Snapshot** — Top 5 sonic peers and where this artist under-indexes +7. **Hyper-Niche Revenue Opportunities** — 3-5 specific ideas with ROI logic +8. **Suggested Context Updates** — What should be added to static artist/audience files (if they already exist) + +## Working With the Artist Workspace + +This skill respects the artist-workspace skill's conventions: + +- **Static context** (`artist.md`, `audience.md`) only gets created, never blindly overwritten +- **Dynamic context** (the research report) goes in `research/` with a date stamp +- **Data lives in one place** — the report references the artist.md by path, it doesn't duplicate identity info +- **Git commits** follow the pattern: `research: deep dive on {artist-name} — initial intel report` + +## After Research + +Once the report is generated, tell the user what you found. Highlight: +- The career stage and what it means for strategy +- The 2-3 most actionable insights +- Any data gaps that need filling (e.g., no Chartmetric data, thin social pulse) +- Whether you created or updated any static context files + +Then ask what they want to do with the research — campaign planning, content strategy, partnership outreach, or something else. The report is designed to feed into any of these downstream workflows. diff --git a/artist-research/references/report-template.md b/artist-research/references/report-template.md new file mode 100644 index 0000000..3e711d1 --- /dev/null +++ b/artist-research/references/report-template.md @@ -0,0 +1,191 @@ +# Artist Intelligence Report Template + +Use this template for the `research/artist-intel-YYYY-MM-DD.md` output. Fill every section where you have real data. Leave a section out entirely if you have nothing substantive — a section with guesses is worse than no section. + +## Frontmatter + +```yaml +--- +artist: "{Artist Name}" +date: YYYY-MM-DD +career_stage: emerging | breakout | established | legacy +sources: [list of sources used, e.g., perplexity, spotify-api, youtube-api, web, reddit, x] +confidence: high | medium | low +data_gaps: [list of things you couldn't find or verify] +--- +``` + +The `confidence` rating reflects overall research quality: +- **high** — Chartmetric data + web research + social pulse (or MCP APIs + Perplexity) +- **medium** — Web research only, metrics are estimated from press/public pages +- **low** — Limited public information available, significant data gaps + +--- + +## Section 1: Artist Overview + +Bio snapshot, origin story, signature sound, key milestones. + +Write this so someone with zero context understands who this artist is in 2-3 paragraphs. Include: +- Real name (if publicly known), age, hometown +- How they got started, when they broke through +- What their music sounds like — be specific (not just "hip-hop" but "sample-heavy boom-bap with jazz piano loops and confessional storytelling") +- Key milestones: chart positions, award nominations, notable features, viral moments, label signings +- Where they are right now — current release cycle, tour status, public narrative + +--- + +## Section 2: Career-Stage Assessment + +Identify the artist's career stage and pull the metrics that matter at that stage: + +| Stage | Metrics to Pull | Why These Matter | +|-------|-----------------|------------------| +| **Emerging** (less than 3 years active, under 100K monthly listeners) | Follower growth rate (month-over-month), playlist adds per week, first tour/show sell-through percentage, save-to-listener ratio | Early momentum signals — are people discovering AND retaining? | +| **Breakout** (1-2 songs with real traction, 100K-1M monthly listeners) | Market-share gains vs. peers in same lane, international listener uptake curves, editorial playlist presence | Scaling levers — where is the growth coming from and can it be amplified? | +| **Established** (50+ tracks released, 1M+ monthly listeners, multiple release cycles) | Catalog half-life (how long tracks stay above X streams/day), royalty source diversification (streaming vs sync vs merch vs live), back-catalog performance | Long-tail levers — is the catalog appreciating or depreciating? | +| **Legacy / Revival** (5+ years since peak, catalog-driven revenue) | Re-engagement metrics on reissues or anniversary releases, sync licensing CAGR, estate or catalog management structure | Nostalgia monetization — where are the untapped cash hooks? | + +After identifying the stage, write: +1. **Current stage** and why you classified them there (cite the metrics) +2. **Next-stage risks** — what could stall their progression +3. **Next-stage opportunities** — what levers can accelerate the transition + +--- + +## Section 3: Fan-Persona Segmentation + +Create 3-5 named fan archetypes. Build these from behavioral data, not just demographics. Each persona should feel like a real person you could describe to a marketing team. + +For each persona: + +**[Persona Name]** (e.g., "The Loop Queen," "The Vinyl Purist," "The TikTok Discoverer") + +- **Who they are:** Age range, location tendency, one-sentence identity sketch +- **Motivation triggers:** Why they listen — emotional need, identity expression, social currency, nostalgia +- **Preferred platforms and content formats:** Where they spend time and what they engage with (short-form video, long-form podcasts, vinyl unboxings, live streams, lyric breakdowns) +- **Price elasticity:** Low (won't pay for anything beyond streaming), Medium (will buy merch or concert tickets if the moment is right), High (will buy limited drops, VIP, collectors editions) +- **Brand affinities outside music:** What other brands, products, subcultures, or interests overlap with this persona? Be specific — not "fashion" but "Carhartt WIP, New Balance 550, vintage Japanese denim" +- **Signal behaviors:** What do super-fans in this persona actually DO? (Save every song, share to stories, comment lyrics, attend multiple shows, buy physical formats, create fan art, participate in Discord) + +--- + +## Section 4: Platform-Native KPI Dashboard + +Provide the deep metrics most dashboards don't surface. Use real numbers when you have them. When estimating, mark with `~` and note the source. + +| Platform | Metric | Value | Source | Notes | +|----------|--------|-------|--------|-------| +| **Spotify** | Monthly listeners | | | | +| | Followers | | | | +| | Save-to-listener ratio | | | Higher than 3% = strong retention | +| | Top track popularity score (0-100) | | | | +| | Active vs passive stream ratio | | | Algorithmic (passive) vs user-initiated (active) | +| | Editorial playlist count | | | | +| | Algorithmic playlist count | | | | +| **Apple Music** | Shazam count (if available) | | | Leading indicator of organic discovery | +| **TikTok** | Creator account followers | | | | +| | Sounds created using their music | | | | +| | Top-performing sound (uses) | | | | +| **YouTube** | Channel subscribers | | | | +| | Avg view count (last 10 videos) | | | | +| | Avg view duration as % of video length | | | Above 50% = strong retention | +| | Music video vs other content ratio | | | | +| **Instagram** | Followers | | | | +| | Avg engagement rate (last 10 posts) | | | | +| | Story view rate (if observable) | | | | +| **Twitter/X** | Followers | | | | +| | Avg engagement per post | | | | +| **Live** | Recent tour/show capacity and sell-through | | | | +| | Primary markets (top DMAs) | | | | +| | Ticket price range | | | | + +Add any other platforms where the artist has meaningful presence. + +### Key Ratios + +Calculate and highlight these if you have the underlying data: +- **Save-to-Listener:** Spotify saves / monthly listeners (above 3% = strong catalog stickiness) +- **Follower-to-Listener:** Spotify followers / monthly listeners (above 20% = dedicated base) +- **Engagement-to-Follower:** Instagram engagement / followers (above 3% for under 100K followers = healthy) +- **View-to-Subscriber:** YouTube views / subscribers (above 30% = content is reaching beyond the base) + +--- + +## Section 5: Cultural Adjacency Map + +Identify micro-scenes, subcultures, and adjacent communities where this artist's fans also participate. Rank by overlap strength. + +Format: +``` +[Artist's primary scene] ↔ [Adjacent scene] — Overlap signal: [what connects them] +``` + +Examples of overlap signals: +- Playlist co-occurrence (the artist appears on playlists with X genre/scene) +- Reddit cross-posts (fans post in both r/ArtistFans and r/AdjacentScene) +- Hashtag overlap on TikTok/Instagram +- Similar artist algorithms (Spotify "Fans Also Like") +- Fashion/brand overlap between fan bases +- Festival lineup proximity (appear at same festivals) + +Provide 5-8 adjacencies ranked from strongest to weakest overlap. + +--- + +## Section 6: Competitive White-Space Snapshot + +Identify the top 5 sonic peers — artists in the same lane competing for the same listeners. + +| Peer Artist | Monthly Listeners | Key Metric Where They Outperform | Key Metric Where Subject Under-Indexes | +|------------|------------------|----------------------------------|----------------------------------------| +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | + +After the table, identify the **biggest untouched white space** — the strategic opening none of the peers are exploiting. This is where the artist has the best chance to differentiate: a platform they're underweight on, a content format nobody in the lane is doing, a geographic market where the music is resonating but no one is investing in touring or localized marketing. + +--- + +## Section 7: Hyper-Niche Revenue Opportunities + +Provide 3-5 highly specific ideas. Each must reference the fan personas or cultural adjacencies from earlier sections. Generic merch or Zoom calls don't qualify. + +For each opportunity: + +**[Opportunity Title]** +- **What:** Specific description of the revenue play +- **Why it works for this artist:** Connect it to a fan persona or adjacency (e.g., "The Vinyl Purist persona has high price elasticity and the artist's jazz-sampling production style maps directly to the collector market") +- **Quick ROI logic:** Rough economics — unit cost, price point, addressable audience size from the fan base, expected conversion rate +- **Execution complexity:** Low / Medium / High +- **Time to revenue:** Immediate / 1-3 months / 3-6 months + +--- + +## Section 8: Suggested Context Updates + +Only include this section if `context/artist.md` or `context/audience.md` already exist. List specific pieces of new information from the research that might warrant updating the static profiles. + +Format: +``` +### artist.md +- [Section]: [What to update] — Source: [where this info came from] + +### audience.md +- [Section]: [What to update] — Source: [where this info came from] +``` + +The human decides whether to apply these. Don't overwrite static files based on research alone. + +--- + +## Data Confidence Legend + +Use these markers throughout the report: + +- `[confirmed]` — Data from platform APIs or official sources +- `[estimated]` — Data from web research, may be outdated or approximate +- `[inferred]` — Pattern-based conclusion, not directly observed +- `[gap]` — Data point you couldn't find — flag it so the next research pass knows what to look for diff --git a/artist-research/references/research-queries.md b/artist-research/references/research-queries.md new file mode 100644 index 0000000..3e95bac --- /dev/null +++ b/artist-research/references/research-queries.md @@ -0,0 +1,242 @@ +# Research Queries + +How to gather data depending on your environment. + +## Option A: Perplexity Deep Research (Sandbox — `web_deep_research` MCP tool) + +Send this as a single message to the `web_deep_research` tool. Replace `{ARTIST_NAME}` with the actual artist name: + +``` +Research the music artist {ARTIST_NAME} comprehensively. I need the following: + +1. BIOGRAPHY: Real name, age, hometown, origin story, how they got started in music, key career milestones (chart positions, awards, notable features, viral moments, label signings). Where are they right now — current release cycle, tour status, recent activity. + +2. STREAMING & PLATFORM METRICS: Spotify monthly listeners, follower count, top tracks and their popularity. YouTube subscribers, average views, most-viewed video. TikTok followers and any viral sounds. Instagram followers and engagement. Any other platform presence (SoundCloud, Bandcamp, Apple Music Shazam data). + +3. DISCOGRAPHY: Complete album/EP/single timeline with release dates. Most commercially successful releases. Critical reception. Collaborations and features. + +4. FAN BASE: Who listens to this artist? Age demographics, geographic concentration, psychographic traits. What subcultures or communities overlap with the fan base? How do fans behave — are they collectors, concert-goers, streamers, vinyl buyers? What brands or interests do the fans share? + +5. LIVE PERFORMANCE: Tour history, venue sizes, ticket price ranges, primary touring markets. Festival appearances. Sell-through rates if available. + +6. COMPETITIVE LANDSCAPE: Top 5 similar artists in the same lane. How does {ARTIST_NAME} compare on streaming numbers, social following, and live performance? Where does {ARTIST_NAME} outperform or underperform vs peers? + +7. CULTURAL CONTEXT: What micro-scenes or subgenres does {ARTIST_NAME} belong to? What adjacent music communities have fan overlap? What cultural moments, trends, or movements is {ARTIST_NAME} connected to? + +8. BUSINESS & PARTNERSHIPS: Current label situation (independent, signed, distribution deal). Known brand partnerships or sync placements. Revenue streams beyond streaming (merch, touring, sync, licensing). Management and team (if publicly known). + +Cite all sources. Include specific numbers where available. Note when data is estimated vs confirmed. +``` + +This single call replaces 8-12 individual web searches. Perplexity will browse extensively and return citations. + +## Option B: WebSearch (Cursor/Local — No MCP Tools) + +Run these searches. Batch independent searches in parallel when possible. + +### Core Identity (Run first — these inform everything else) + +1. `"{ARTIST_NAME}" musician biography discography` +2. `"{ARTIST_NAME}" artist interview origin story` + +### Streaming & Metrics + +3. `"{ARTIST_NAME}" spotify monthly listeners 2026` +4. `"{ARTIST_NAME}" streaming numbers charts` + +### Fan Base & Audience + +5. `"{ARTIST_NAME}" fan base demographics audience` +6. `"{ARTIST_NAME}" reddit fans community` (skip if last30days is handling this) + +### Competitive Landscape + +7. `"{ARTIST_NAME}" similar artists comparisons` +8. `"artists like {ARTIST_NAME}" OR "{ARTIST_NAME} compared to"` + +### Business & Industry + +9. `"{ARTIST_NAME}" label deal management brand partnership` +10. `"{ARTIST_NAME}" tour concerts live shows 2025 2026` + +### Cultural Context + +11. `"{ARTIST_NAME}" genre scene subculture movement` +12. `"{ARTIST_NAME}" sync placement TV film commercial` + +### Supplemental (if initial results are thin) + +13. `"{ARTIST_NAME}" press coverage interview profile` +14. `site:genius.com "{ARTIST_NAME}"` (for discography and lyrical context) + +### Search Tips + +- Put the artist name in quotes to avoid false matches +- If the artist name is common (e.g., "Jada"), add qualifiers: genre, label, city +- If initial searches return thin results, try variations: stage name vs real name, former group names, collaborator names +- For emerging artists with little press coverage, try SoundCloud, Bandcamp, and local music blogs +- When you get streaming numbers from web articles, note the date — these change fast + +## Option C: MCP Platform Data (Sandbox — Structured API Data) + +If these MCP tools are available, use them for authoritative data: + +### Spotify + +1. `spotify_search` — Search for the artist to get their Spotify ID +2. `spotify_artist_top_tracks` — Get top tracks with popularity scores +3. `spotify_artist_albums` — Get full discography with release dates +4. `spotify_album` — For specific album details (track listings, popularity) + +### YouTube + +1. `youtube_channels` — Get channel data (subscribers, total views) +2. `youtube_channel_video_list` — Get recent videos with view counts + +### Artist Platform Data + +1. `artist_deep_research` — Get all connected social accounts and follower data +2. `get_artist_socials` — Social media links and metrics + +### Data Priority + +When platform API data conflicts with web-scraped data, trust the API data. It's real-time and authoritative. Note the discrepancy in the report — it may indicate the web data is stale. + +## Option D: Chartmetric (Python Scripts — Requires CHARTMETRIC_REFRESH_TOKEN) + +Chartmetric provides the deepest music analytics data. If the token is configured, run these scripts from the chartmetric skill directory. Each script outputs JSON you can parse. + +### Discovery and Profile + +```bash +# Find the artist — get their Chartmetric ID +python scripts/search_artist.py "{ARTIST_NAME}" + +# Full profile (bio, genres, social links, label) +python scripts/get_artist.py {CM_ID} + +# Career timeline — key moments, trajectory +python scripts/get_artist_career.py {CM_ID} + +# AI-generated insights (Chartmetric's own analysis) +python scripts/get_artist_insights.py {CM_ID} +``` + +### Streaming Metrics (Feeds Section 4: KPI Dashboard) + +```bash +# Spotify: monthly listeners, followers, popularity scores +python scripts/get_artist_metrics.py {CM_ID} --source spotify + +# Instagram: followers, engagement +python scripts/get_artist_metrics.py {CM_ID} --source instagram + +# TikTok: followers, video performance +python scripts/get_artist_metrics.py {CM_ID} --source tiktok + +# YouTube: subscribers, views +python scripts/get_artist_metrics.py {CM_ID} --source youtube_channel + +# SoundCloud (for indie/underground artists) +python scripts/get_artist_metrics.py {CM_ID} --source soundcloud +``` + +All 14 valid sources: `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` + +### Audience and Geography (Feeds Section 3: Fan Personas) + +```bash +# Instagram audience demographics (age, gender, location) +python scripts/get_artist_audience.py {CM_ID} + +# TikTok audience demographics +python scripts/get_artist_audience.py {CM_ID} --platform tiktok + +# YouTube audience demographics +python scripts/get_artist_audience.py {CM_ID} --platform youtube + +# Top cities by listener concentration +python scripts/get_artist_cities.py {CM_ID} + +# Top Instagram posts/reels (what content resonates) +python scripts/get_artist_instagram_posts.py {CM_ID} +``` + +### Competitive Landscape (Feeds Section 6: White-Space) + +```bash +# Similar artists by audience and genre overlap +python scripts/get_similar_artists.py {CM_ID} --by-config --audience high --genre high --limit 10 + +# Compare metrics with a specific competitor +python scripts/get_artist_metrics.py {CM_ID} --source spotify +python scripts/get_artist_metrics.py {COMPETITOR_CM_ID} --source spotify +``` + +### Playlist Intelligence + +```bash +# Current editorial playlist placements +python scripts/get_artist_playlists.py {CM_ID} --editorial --limit 20 + +# Past placements (historical) +python scripts/get_artist_playlists.py {CM_ID} --status past --limit 20 + +# All platforms +python scripts/get_artist_playlists.py {CM_ID} --platform applemusic +``` + +### Discography + +```bash +# All albums/EPs/singles +python scripts/get_artist_albums.py {CM_ID} + +# All tracks with popularity data +python scripts/get_artist_tracks.py {CM_ID} + +# Deep dive on a specific track +python scripts/get_track.py {TRACK_CM_ID} +``` + +### What Chartmetric Data Maps to in the Report + +| Chartmetric Script | Report Section | +|-------------------|----------------| +| `get_artist.py` + `get_artist_career.py` | Section 1: Artist Overview | +| `get_artist_metrics.py` (all platforms) | Section 2: Career-Stage Assessment, Section 4: KPI Dashboard | +| `get_artist_audience.py` + `get_artist_cities.py` | Section 3: Fan Personas | +| `get_artist_playlists.py` | Section 4: KPI Dashboard (playlist presence) | +| `get_similar_artists.py` | Section 5: Cultural Adjacency, Section 6: Competitive White-Space | +| `get_artist_insights.py` | Cross-reference with your own analysis | + +--- + +## Combining Sources + +The best report comes from layering every available source: + +1. **Chartmetric** gives you authoritative, historical, multi-platform data you can trust +2. **Web research** gives you narrative context, cultural positioning, press coverage, and brand partnerships that APIs don't capture +3. **MCP Platform APIs** give you real-time platform data (Spotify/YouTube) if available in sandbox +4. **Social pulse** (last30days) gives you what fans are saying RIGHT NOW on Reddit and X + +### Data Priority When Sources Conflict + +If Chartmetric and a web article both cite Spotify monthly listeners: +- **Use Chartmetric's number** — it's pulled from the API, not a journalist's article from 3 months ago +- **Note the discrepancy** — the difference might be a growth signal worth mentioning + +If web research mentions something Chartmetric doesn't cover (brand deals, press narrative, cultural context): +- **Include it as `[estimated]`** — web research is the only source for qualitative insights + +### When You Have No Data Sources Beyond WebSearch + +The report is still valuable. Web research surfaces most of what you need: +- Chartmetric's public artist pages are indexed and appear in search results +- Press articles quote streaming numbers (mark as `[estimated]` and note the article date) +- Social media profiles show follower counts +- Interview quotes reveal personality, brand voice, and creative direction +- Fan forums and Reddit surface psychographic insights + +The report will have more `[estimated]` and `[gap]` markers, but that's honest and useful — it tells the next person exactly where to invest in better data. diff --git a/setup-sandbox b/setup-sandbox index 004e609..736a5a2 160000 --- a/setup-sandbox +++ b/setup-sandbox @@ -1 +1 @@ -Subproject commit 004e609a29beeda214622ebce11e46a09c1f7066 +Subproject commit 736a5a2b63b76744f09f6b4ba46152930ad56944 From 94739e81a1a766c365be156d349914318e4d0e89 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 19:17:20 -0400 Subject: [PATCH 2/5] =?UTF-8?q?feat:=20rename=20artist-research=20?= =?UTF-8?q?=E2=86=92=20recoup-research,=20rewrite=20for=20CLI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill now covers all 25 recoup research CLI commands, not just artist research. Renamed because the research tools handle artists, people, URLs, structured enrichment, and general web intelligence — not just artist data. - SKILL.md: full command reference with when-to-use guide - references/workflows.md: 10 strategic workflow chains - Removed old Python/Chartmetric references (report-template, research-queries) Made-with: Cursor --- artist-research/SKILL.md | 193 ------------ artist-research/references/report-template.md | 191 ------------ .../references/research-queries.md | 242 --------------- recoup-research/SKILL.md | 128 ++++++++ recoup-research/references/workflows.md | 283 ++++++++++++++++++ 5 files changed, 411 insertions(+), 626 deletions(-) delete mode 100644 artist-research/SKILL.md delete mode 100644 artist-research/references/report-template.md delete mode 100644 artist-research/references/research-queries.md create mode 100644 recoup-research/SKILL.md create mode 100644 recoup-research/references/workflows.md diff --git a/artist-research/SKILL.md b/artist-research/SKILL.md deleted file mode 100644 index aca7f9b..0000000 --- a/artist-research/SKILL.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -name: artist-research -description: Deep research on a music artist — bio, metrics, fan personas, competitive positioning, and revenue opportunities. Use when setting up a new artist, building an artist knowledge base, researching an artist for the first time, or when the user says "research [artist name]," "deep dive on [artist]," "who is [artist]," "analyze [artist]," or "build a profile for [artist]." Also use when onboarding an artist to the platform and you need comprehensive context before strategizing. This is the go-to skill for any artist intelligence gathering — not just a bio, but the full picture a music manager needs to make decisions. ---- - -# Research Artist - -Deep research on a music artist. Produces a comprehensive intelligence report that any agent can use as a knowledge base when strategizing about campaigns, fan growth, partnerships, and content. - -You are a music manager working with the artist. Your role is to oversee releases, grow the audience, and unlock revenue. Research with that lens — surface what's actionable, not what's obvious. - -## Before You Start - -1. Read the artist's `RECOUP.md` to get their name, slug, and ID (if in a workspace). -2. Read `context/artist.md` if it exists — understand what's already known before researching. -3. Determine your environment — this affects which research tools you use. - -## Research Pipeline - -The skill runs a multi-source pipeline. Every source is optional — the skill works with just WebSearch alone but gets richer with each additional source. Before starting, detect what's available and use the best combination. - -### Detect Available Sources - -Check for each of these before starting. Use whatever you find — don't block if something is missing. - -| Source | How to Check | What It Gives You | -|--------|-------------|-------------------| -| **WebSearch** | Always available | Bio, narrative, cultural context, press coverage, estimated metrics | -| **Chartmetric** | Check for `CHARTMETRIC_REFRESH_TOKEN` env var and `skills/chartmetric/scripts/` | Real streaming metrics across 14 platforms, audience demographics, city-level data, playlist placements, similar artists, career timeline | -| **last30days** | Check for `~/.claude/skills/last30days/scripts/last30days.py` or `.cursor/skills/last30days/scripts/last30days.py` | Reddit and X fan conversations, sentiment, community buzz | -| **MCP tools** | Check if `web_deep_research`, `spotify_search`, `youtube_channels` etc. are available | Perplexity deep research, Spotify/YouTube API data, platform social data | - -### Phase 1: Web Research (Always Runs) - -This is the backbone. It fills in the narrative that numbers alone can't tell — origin story, cultural context, brand identity, industry positioning. - -**If `web_deep_research` MCP tool is available:** -Send a single comprehensive research prompt. Read `references/research-queries.md` for the exact message. Perplexity deep research browses extensively and returns cited results. - -**Otherwise, use WebSearch:** -Run 8-12 targeted searches covering bio, metrics, fans, competition, business, and cultural context. Read `references/research-queries.md` for the full query list. Run searches in parallel when possible. - -WebSearch alone produces a solid report. The phases below add verified data on top. - -### Phase 2: Chartmetric Data (If Available) - -Chartmetric is the richest data source for music analytics. If the `CHARTMETRIC_REFRESH_TOKEN` is configured and the chartmetric skill scripts exist, run this sequence: - -```bash -# 1. Find the artist's Chartmetric ID -python scripts/search_artist.py "{ARTIST_NAME}" - -# 2. Pull core profile and career data -python scripts/get_artist.py {CM_ID} -python scripts/get_artist_career.py {CM_ID} -python scripts/get_artist_insights.py {CM_ID} - -# 3. Streaming metrics (the KPI Dashboard section) -python scripts/get_artist_metrics.py {CM_ID} --source spotify -python scripts/get_artist_metrics.py {CM_ID} --source instagram -python scripts/get_artist_metrics.py {CM_ID} --source tiktok -python scripts/get_artist_metrics.py {CM_ID} --source youtube_channel - -# 4. Audience and geography (the Fan Persona section) -python scripts/get_artist_audience.py {CM_ID} -python scripts/get_artist_audience.py {CM_ID} --platform tiktok -python scripts/get_artist_cities.py {CM_ID} - -# 5. Competitive landscape (the White-Space section) -python scripts/get_similar_artists.py {CM_ID} --by-config --audience high --genre high --limit 10 - -# 6. Playlist presence -python scripts/get_artist_playlists.py {CM_ID} --editorial --limit 20 - -# 7. Complete discography and tracks -python scripts/get_artist_albums.py {CM_ID} -python scripts/get_artist_tracks.py {CM_ID} -``` - -Run these from the chartmetric skill directory. Mark all data from Chartmetric as `[confirmed]` — these are authoritative numbers, not estimates. - -When Chartmetric data contradicts web research, trust Chartmetric and note the discrepancy. The web number is probably stale. - -**If Chartmetric is NOT available:** The report still works. Web research can surface most metrics through press articles, public Chartmetric pages, and social posts. Just mark those numbers as `[estimated]` instead of `[confirmed]`. - -### Phase 3: Social Pulse (last30days — If Available) - -If the last30days skill is installed, run it for the artist name: - -```bash -python3 /last30days.py "{ARTIST_NAME} music" --emit=compact -``` - -What you're looking for: -- Fan conversations and sentiment -- Press coverage reactions -- Community-driven opinions -- Recent momentum or controversy - -This data feeds into Fan Persona Segmentation and Cultural Adjacency Map. If last30days is not available, note it as a data gap. Don't block on this. - -### Phase 4: MCP Platform Data (Sandbox Only — If Available) - -If MCP tools are connected (sandbox environment), supplement with: - -1. **`web_deep_research`** — Deep Perplexity research (if not already used in Phase 1) -2. **`spotify_search`** / **`spotify_artist_top_tracks`** / **`spotify_artist_albums`** — Real-time Spotify data -3. **`youtube_channels`** / **`youtube_channel_video_list`** — YouTube metrics -4. **`artist_deep_research`** — Connected social accounts from the platform - -If you already have Chartmetric data for the same metrics, use Chartmetric as the primary source and note if MCP data differs. Both are authoritative but Chartmetric usually has deeper historical data. - -### Phase 5: Synthesis - -After all available phases complete, synthesize into the report. Read `references/report-template.md` for the full output template. Note which sources you used in the report's YAML frontmatter so future agents know the data quality. - -## Output Architecture - -The research produces two types of output. This distinction matters because agents reading the workspace need to know whether something is a durable fact or a time-bound snapshot. - -### Dynamic Output (The Report) - -Save the full research report as: - -``` -research/artist-intel-YYYY-MM-DD.md -``` - -This is a point-in-time document. It contains metrics, trends, fan personas, competitive analysis, and revenue opportunities. These change. The report should be timestamped and eventually archived when it goes stale. - -If a `research/` directory doesn't exist, create it. - -### Static Context Updates - -After generating the report, check what static context files exist: - -**If `context/artist.md` does NOT exist:** -Create it using the artist-workspace template format (read `references/artist-template.md` from the artist-workspace skill). Populate it with the identity, brand, and voice information extracted from the research. Only include sections where you have real data. - -**If `context/artist.md` DOES exist:** -Do NOT overwrite it. Instead, at the end of the research report, add a "Suggested Context Updates" section that flags any new information that might warrant updating the static profile. The human decides whether to apply those updates. - -**If `context/audience.md` does NOT exist and you have fan data:** -Create it using the audience template from the artist-workspace skill. Populate with the fan persona data from the research. - -**If `context/audience.md` DOES exist:** -Same as artist.md — suggest updates, don't overwrite. - -### Knowledge Base (Sandbox Only) - -If the `create_knowledge_base` MCP tool is available and the artist has an account ID, save the research report to the artist's permanent knowledge base. This makes it accessible to the AI in future conversations. - -## Quality Rules - -1. **No obvious advice.** "Post TikToks" and "run pre-saves" are noise. Every recommendation should be specific to THIS artist's data. -2. **Explain who they are.** A reader with zero context should understand the artist after reading the overview. -3. **Deep metrics over vanity metrics.** Save-to-listener ratios matter more than raw follower counts. Engagement rate matters more than total followers. -4. **Surface unique fan insights.** Psychographics, subculture overlaps, and super-fan behaviors — not just "18-24 year olds." -5. **Cite sources.** Every metric and claim should reference where it came from so future agents can verify. -6. **Flag confidence levels.** Mark data points as `[confirmed]` (from Chartmetric, platform APIs, or official sources), `[estimated]` (from web research — numbers may be outdated), or `[inferred]` (pattern-based conclusions). This helps downstream agents know what to trust. -7. **No NFTs, crypto, or web3** unless the artist has explicitly expressed interest OR their fan base demonstrably aligns. Don't suggest these by default. - -## Report Structure - -Read `references/report-template.md` for the complete output template. The sections are: - -1. **Artist Overview** — Bio, origin, sound, milestones -2. **Career-Stage Assessment** — Where they are and what metrics matter at this stage -3. **Fan-Persona Segmentation** — 3-5 named behavioral archetypes -4. **Platform-Native KPI Dashboard** — Deep metrics most dashboards hide -5. **Cultural Adjacency Map** — Adjacent micro-scenes and overlap signals -6. **Competitive White-Space Snapshot** — Top 5 sonic peers and where this artist under-indexes -7. **Hyper-Niche Revenue Opportunities** — 3-5 specific ideas with ROI logic -8. **Suggested Context Updates** — What should be added to static artist/audience files (if they already exist) - -## Working With the Artist Workspace - -This skill respects the artist-workspace skill's conventions: - -- **Static context** (`artist.md`, `audience.md`) only gets created, never blindly overwritten -- **Dynamic context** (the research report) goes in `research/` with a date stamp -- **Data lives in one place** — the report references the artist.md by path, it doesn't duplicate identity info -- **Git commits** follow the pattern: `research: deep dive on {artist-name} — initial intel report` - -## After Research - -Once the report is generated, tell the user what you found. Highlight: -- The career stage and what it means for strategy -- The 2-3 most actionable insights -- Any data gaps that need filling (e.g., no Chartmetric data, thin social pulse) -- Whether you created or updated any static context files - -Then ask what they want to do with the research — campaign planning, content strategy, partnership outreach, or something else. The report is designed to feed into any of these downstream workflows. diff --git a/artist-research/references/report-template.md b/artist-research/references/report-template.md deleted file mode 100644 index 3e711d1..0000000 --- a/artist-research/references/report-template.md +++ /dev/null @@ -1,191 +0,0 @@ -# Artist Intelligence Report Template - -Use this template for the `research/artist-intel-YYYY-MM-DD.md` output. Fill every section where you have real data. Leave a section out entirely if you have nothing substantive — a section with guesses is worse than no section. - -## Frontmatter - -```yaml ---- -artist: "{Artist Name}" -date: YYYY-MM-DD -career_stage: emerging | breakout | established | legacy -sources: [list of sources used, e.g., perplexity, spotify-api, youtube-api, web, reddit, x] -confidence: high | medium | low -data_gaps: [list of things you couldn't find or verify] ---- -``` - -The `confidence` rating reflects overall research quality: -- **high** — Chartmetric data + web research + social pulse (or MCP APIs + Perplexity) -- **medium** — Web research only, metrics are estimated from press/public pages -- **low** — Limited public information available, significant data gaps - ---- - -## Section 1: Artist Overview - -Bio snapshot, origin story, signature sound, key milestones. - -Write this so someone with zero context understands who this artist is in 2-3 paragraphs. Include: -- Real name (if publicly known), age, hometown -- How they got started, when they broke through -- What their music sounds like — be specific (not just "hip-hop" but "sample-heavy boom-bap with jazz piano loops and confessional storytelling") -- Key milestones: chart positions, award nominations, notable features, viral moments, label signings -- Where they are right now — current release cycle, tour status, public narrative - ---- - -## Section 2: Career-Stage Assessment - -Identify the artist's career stage and pull the metrics that matter at that stage: - -| Stage | Metrics to Pull | Why These Matter | -|-------|-----------------|------------------| -| **Emerging** (less than 3 years active, under 100K monthly listeners) | Follower growth rate (month-over-month), playlist adds per week, first tour/show sell-through percentage, save-to-listener ratio | Early momentum signals — are people discovering AND retaining? | -| **Breakout** (1-2 songs with real traction, 100K-1M monthly listeners) | Market-share gains vs. peers in same lane, international listener uptake curves, editorial playlist presence | Scaling levers — where is the growth coming from and can it be amplified? | -| **Established** (50+ tracks released, 1M+ monthly listeners, multiple release cycles) | Catalog half-life (how long tracks stay above X streams/day), royalty source diversification (streaming vs sync vs merch vs live), back-catalog performance | Long-tail levers — is the catalog appreciating or depreciating? | -| **Legacy / Revival** (5+ years since peak, catalog-driven revenue) | Re-engagement metrics on reissues or anniversary releases, sync licensing CAGR, estate or catalog management structure | Nostalgia monetization — where are the untapped cash hooks? | - -After identifying the stage, write: -1. **Current stage** and why you classified them there (cite the metrics) -2. **Next-stage risks** — what could stall their progression -3. **Next-stage opportunities** — what levers can accelerate the transition - ---- - -## Section 3: Fan-Persona Segmentation - -Create 3-5 named fan archetypes. Build these from behavioral data, not just demographics. Each persona should feel like a real person you could describe to a marketing team. - -For each persona: - -**[Persona Name]** (e.g., "The Loop Queen," "The Vinyl Purist," "The TikTok Discoverer") - -- **Who they are:** Age range, location tendency, one-sentence identity sketch -- **Motivation triggers:** Why they listen — emotional need, identity expression, social currency, nostalgia -- **Preferred platforms and content formats:** Where they spend time and what they engage with (short-form video, long-form podcasts, vinyl unboxings, live streams, lyric breakdowns) -- **Price elasticity:** Low (won't pay for anything beyond streaming), Medium (will buy merch or concert tickets if the moment is right), High (will buy limited drops, VIP, collectors editions) -- **Brand affinities outside music:** What other brands, products, subcultures, or interests overlap with this persona? Be specific — not "fashion" but "Carhartt WIP, New Balance 550, vintage Japanese denim" -- **Signal behaviors:** What do super-fans in this persona actually DO? (Save every song, share to stories, comment lyrics, attend multiple shows, buy physical formats, create fan art, participate in Discord) - ---- - -## Section 4: Platform-Native KPI Dashboard - -Provide the deep metrics most dashboards don't surface. Use real numbers when you have them. When estimating, mark with `~` and note the source. - -| Platform | Metric | Value | Source | Notes | -|----------|--------|-------|--------|-------| -| **Spotify** | Monthly listeners | | | | -| | Followers | | | | -| | Save-to-listener ratio | | | Higher than 3% = strong retention | -| | Top track popularity score (0-100) | | | | -| | Active vs passive stream ratio | | | Algorithmic (passive) vs user-initiated (active) | -| | Editorial playlist count | | | | -| | Algorithmic playlist count | | | | -| **Apple Music** | Shazam count (if available) | | | Leading indicator of organic discovery | -| **TikTok** | Creator account followers | | | | -| | Sounds created using their music | | | | -| | Top-performing sound (uses) | | | | -| **YouTube** | Channel subscribers | | | | -| | Avg view count (last 10 videos) | | | | -| | Avg view duration as % of video length | | | Above 50% = strong retention | -| | Music video vs other content ratio | | | | -| **Instagram** | Followers | | | | -| | Avg engagement rate (last 10 posts) | | | | -| | Story view rate (if observable) | | | | -| **Twitter/X** | Followers | | | | -| | Avg engagement per post | | | | -| **Live** | Recent tour/show capacity and sell-through | | | | -| | Primary markets (top DMAs) | | | | -| | Ticket price range | | | | - -Add any other platforms where the artist has meaningful presence. - -### Key Ratios - -Calculate and highlight these if you have the underlying data: -- **Save-to-Listener:** Spotify saves / monthly listeners (above 3% = strong catalog stickiness) -- **Follower-to-Listener:** Spotify followers / monthly listeners (above 20% = dedicated base) -- **Engagement-to-Follower:** Instagram engagement / followers (above 3% for under 100K followers = healthy) -- **View-to-Subscriber:** YouTube views / subscribers (above 30% = content is reaching beyond the base) - ---- - -## Section 5: Cultural Adjacency Map - -Identify micro-scenes, subcultures, and adjacent communities where this artist's fans also participate. Rank by overlap strength. - -Format: -``` -[Artist's primary scene] ↔ [Adjacent scene] — Overlap signal: [what connects them] -``` - -Examples of overlap signals: -- Playlist co-occurrence (the artist appears on playlists with X genre/scene) -- Reddit cross-posts (fans post in both r/ArtistFans and r/AdjacentScene) -- Hashtag overlap on TikTok/Instagram -- Similar artist algorithms (Spotify "Fans Also Like") -- Fashion/brand overlap between fan bases -- Festival lineup proximity (appear at same festivals) - -Provide 5-8 adjacencies ranked from strongest to weakest overlap. - ---- - -## Section 6: Competitive White-Space Snapshot - -Identify the top 5 sonic peers — artists in the same lane competing for the same listeners. - -| Peer Artist | Monthly Listeners | Key Metric Where They Outperform | Key Metric Where Subject Under-Indexes | -|------------|------------------|----------------------------------|----------------------------------------| -| | | | | -| | | | | -| | | | | -| | | | | -| | | | | - -After the table, identify the **biggest untouched white space** — the strategic opening none of the peers are exploiting. This is where the artist has the best chance to differentiate: a platform they're underweight on, a content format nobody in the lane is doing, a geographic market where the music is resonating but no one is investing in touring or localized marketing. - ---- - -## Section 7: Hyper-Niche Revenue Opportunities - -Provide 3-5 highly specific ideas. Each must reference the fan personas or cultural adjacencies from earlier sections. Generic merch or Zoom calls don't qualify. - -For each opportunity: - -**[Opportunity Title]** -- **What:** Specific description of the revenue play -- **Why it works for this artist:** Connect it to a fan persona or adjacency (e.g., "The Vinyl Purist persona has high price elasticity and the artist's jazz-sampling production style maps directly to the collector market") -- **Quick ROI logic:** Rough economics — unit cost, price point, addressable audience size from the fan base, expected conversion rate -- **Execution complexity:** Low / Medium / High -- **Time to revenue:** Immediate / 1-3 months / 3-6 months - ---- - -## Section 8: Suggested Context Updates - -Only include this section if `context/artist.md` or `context/audience.md` already exist. List specific pieces of new information from the research that might warrant updating the static profiles. - -Format: -``` -### artist.md -- [Section]: [What to update] — Source: [where this info came from] - -### audience.md -- [Section]: [What to update] — Source: [where this info came from] -``` - -The human decides whether to apply these. Don't overwrite static files based on research alone. - ---- - -## Data Confidence Legend - -Use these markers throughout the report: - -- `[confirmed]` — Data from platform APIs or official sources -- `[estimated]` — Data from web research, may be outdated or approximate -- `[inferred]` — Pattern-based conclusion, not directly observed -- `[gap]` — Data point you couldn't find — flag it so the next research pass knows what to look for diff --git a/artist-research/references/research-queries.md b/artist-research/references/research-queries.md deleted file mode 100644 index 3e95bac..0000000 --- a/artist-research/references/research-queries.md +++ /dev/null @@ -1,242 +0,0 @@ -# Research Queries - -How to gather data depending on your environment. - -## Option A: Perplexity Deep Research (Sandbox — `web_deep_research` MCP tool) - -Send this as a single message to the `web_deep_research` tool. Replace `{ARTIST_NAME}` with the actual artist name: - -``` -Research the music artist {ARTIST_NAME} comprehensively. I need the following: - -1. BIOGRAPHY: Real name, age, hometown, origin story, how they got started in music, key career milestones (chart positions, awards, notable features, viral moments, label signings). Where are they right now — current release cycle, tour status, recent activity. - -2. STREAMING & PLATFORM METRICS: Spotify monthly listeners, follower count, top tracks and their popularity. YouTube subscribers, average views, most-viewed video. TikTok followers and any viral sounds. Instagram followers and engagement. Any other platform presence (SoundCloud, Bandcamp, Apple Music Shazam data). - -3. DISCOGRAPHY: Complete album/EP/single timeline with release dates. Most commercially successful releases. Critical reception. Collaborations and features. - -4. FAN BASE: Who listens to this artist? Age demographics, geographic concentration, psychographic traits. What subcultures or communities overlap with the fan base? How do fans behave — are they collectors, concert-goers, streamers, vinyl buyers? What brands or interests do the fans share? - -5. LIVE PERFORMANCE: Tour history, venue sizes, ticket price ranges, primary touring markets. Festival appearances. Sell-through rates if available. - -6. COMPETITIVE LANDSCAPE: Top 5 similar artists in the same lane. How does {ARTIST_NAME} compare on streaming numbers, social following, and live performance? Where does {ARTIST_NAME} outperform or underperform vs peers? - -7. CULTURAL CONTEXT: What micro-scenes or subgenres does {ARTIST_NAME} belong to? What adjacent music communities have fan overlap? What cultural moments, trends, or movements is {ARTIST_NAME} connected to? - -8. BUSINESS & PARTNERSHIPS: Current label situation (independent, signed, distribution deal). Known brand partnerships or sync placements. Revenue streams beyond streaming (merch, touring, sync, licensing). Management and team (if publicly known). - -Cite all sources. Include specific numbers where available. Note when data is estimated vs confirmed. -``` - -This single call replaces 8-12 individual web searches. Perplexity will browse extensively and return citations. - -## Option B: WebSearch (Cursor/Local — No MCP Tools) - -Run these searches. Batch independent searches in parallel when possible. - -### Core Identity (Run first — these inform everything else) - -1. `"{ARTIST_NAME}" musician biography discography` -2. `"{ARTIST_NAME}" artist interview origin story` - -### Streaming & Metrics - -3. `"{ARTIST_NAME}" spotify monthly listeners 2026` -4. `"{ARTIST_NAME}" streaming numbers charts` - -### Fan Base & Audience - -5. `"{ARTIST_NAME}" fan base demographics audience` -6. `"{ARTIST_NAME}" reddit fans community` (skip if last30days is handling this) - -### Competitive Landscape - -7. `"{ARTIST_NAME}" similar artists comparisons` -8. `"artists like {ARTIST_NAME}" OR "{ARTIST_NAME} compared to"` - -### Business & Industry - -9. `"{ARTIST_NAME}" label deal management brand partnership` -10. `"{ARTIST_NAME}" tour concerts live shows 2025 2026` - -### Cultural Context - -11. `"{ARTIST_NAME}" genre scene subculture movement` -12. `"{ARTIST_NAME}" sync placement TV film commercial` - -### Supplemental (if initial results are thin) - -13. `"{ARTIST_NAME}" press coverage interview profile` -14. `site:genius.com "{ARTIST_NAME}"` (for discography and lyrical context) - -### Search Tips - -- Put the artist name in quotes to avoid false matches -- If the artist name is common (e.g., "Jada"), add qualifiers: genre, label, city -- If initial searches return thin results, try variations: stage name vs real name, former group names, collaborator names -- For emerging artists with little press coverage, try SoundCloud, Bandcamp, and local music blogs -- When you get streaming numbers from web articles, note the date — these change fast - -## Option C: MCP Platform Data (Sandbox — Structured API Data) - -If these MCP tools are available, use them for authoritative data: - -### Spotify - -1. `spotify_search` — Search for the artist to get their Spotify ID -2. `spotify_artist_top_tracks` — Get top tracks with popularity scores -3. `spotify_artist_albums` — Get full discography with release dates -4. `spotify_album` — For specific album details (track listings, popularity) - -### YouTube - -1. `youtube_channels` — Get channel data (subscribers, total views) -2. `youtube_channel_video_list` — Get recent videos with view counts - -### Artist Platform Data - -1. `artist_deep_research` — Get all connected social accounts and follower data -2. `get_artist_socials` — Social media links and metrics - -### Data Priority - -When platform API data conflicts with web-scraped data, trust the API data. It's real-time and authoritative. Note the discrepancy in the report — it may indicate the web data is stale. - -## Option D: Chartmetric (Python Scripts — Requires CHARTMETRIC_REFRESH_TOKEN) - -Chartmetric provides the deepest music analytics data. If the token is configured, run these scripts from the chartmetric skill directory. Each script outputs JSON you can parse. - -### Discovery and Profile - -```bash -# Find the artist — get their Chartmetric ID -python scripts/search_artist.py "{ARTIST_NAME}" - -# Full profile (bio, genres, social links, label) -python scripts/get_artist.py {CM_ID} - -# Career timeline — key moments, trajectory -python scripts/get_artist_career.py {CM_ID} - -# AI-generated insights (Chartmetric's own analysis) -python scripts/get_artist_insights.py {CM_ID} -``` - -### Streaming Metrics (Feeds Section 4: KPI Dashboard) - -```bash -# Spotify: monthly listeners, followers, popularity scores -python scripts/get_artist_metrics.py {CM_ID} --source spotify - -# Instagram: followers, engagement -python scripts/get_artist_metrics.py {CM_ID} --source instagram - -# TikTok: followers, video performance -python scripts/get_artist_metrics.py {CM_ID} --source tiktok - -# YouTube: subscribers, views -python scripts/get_artist_metrics.py {CM_ID} --source youtube_channel - -# SoundCloud (for indie/underground artists) -python scripts/get_artist_metrics.py {CM_ID} --source soundcloud -``` - -All 14 valid sources: `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` - -### Audience and Geography (Feeds Section 3: Fan Personas) - -```bash -# Instagram audience demographics (age, gender, location) -python scripts/get_artist_audience.py {CM_ID} - -# TikTok audience demographics -python scripts/get_artist_audience.py {CM_ID} --platform tiktok - -# YouTube audience demographics -python scripts/get_artist_audience.py {CM_ID} --platform youtube - -# Top cities by listener concentration -python scripts/get_artist_cities.py {CM_ID} - -# Top Instagram posts/reels (what content resonates) -python scripts/get_artist_instagram_posts.py {CM_ID} -``` - -### Competitive Landscape (Feeds Section 6: White-Space) - -```bash -# Similar artists by audience and genre overlap -python scripts/get_similar_artists.py {CM_ID} --by-config --audience high --genre high --limit 10 - -# Compare metrics with a specific competitor -python scripts/get_artist_metrics.py {CM_ID} --source spotify -python scripts/get_artist_metrics.py {COMPETITOR_CM_ID} --source spotify -``` - -### Playlist Intelligence - -```bash -# Current editorial playlist placements -python scripts/get_artist_playlists.py {CM_ID} --editorial --limit 20 - -# Past placements (historical) -python scripts/get_artist_playlists.py {CM_ID} --status past --limit 20 - -# All platforms -python scripts/get_artist_playlists.py {CM_ID} --platform applemusic -``` - -### Discography - -```bash -# All albums/EPs/singles -python scripts/get_artist_albums.py {CM_ID} - -# All tracks with popularity data -python scripts/get_artist_tracks.py {CM_ID} - -# Deep dive on a specific track -python scripts/get_track.py {TRACK_CM_ID} -``` - -### What Chartmetric Data Maps to in the Report - -| Chartmetric Script | Report Section | -|-------------------|----------------| -| `get_artist.py` + `get_artist_career.py` | Section 1: Artist Overview | -| `get_artist_metrics.py` (all platforms) | Section 2: Career-Stage Assessment, Section 4: KPI Dashboard | -| `get_artist_audience.py` + `get_artist_cities.py` | Section 3: Fan Personas | -| `get_artist_playlists.py` | Section 4: KPI Dashboard (playlist presence) | -| `get_similar_artists.py` | Section 5: Cultural Adjacency, Section 6: Competitive White-Space | -| `get_artist_insights.py` | Cross-reference with your own analysis | - ---- - -## Combining Sources - -The best report comes from layering every available source: - -1. **Chartmetric** gives you authoritative, historical, multi-platform data you can trust -2. **Web research** gives you narrative context, cultural positioning, press coverage, and brand partnerships that APIs don't capture -3. **MCP Platform APIs** give you real-time platform data (Spotify/YouTube) if available in sandbox -4. **Social pulse** (last30days) gives you what fans are saying RIGHT NOW on Reddit and X - -### Data Priority When Sources Conflict - -If Chartmetric and a web article both cite Spotify monthly listeners: -- **Use Chartmetric's number** — it's pulled from the API, not a journalist's article from 3 months ago -- **Note the discrepancy** — the difference might be a growth signal worth mentioning - -If web research mentions something Chartmetric doesn't cover (brand deals, press narrative, cultural context): -- **Include it as `[estimated]`** — web research is the only source for qualitative insights - -### When You Have No Data Sources Beyond WebSearch - -The report is still valuable. Web research surfaces most of what you need: -- Chartmetric's public artist pages are indexed and appear in search results -- Press articles quote streaming numbers (mark as `[estimated]` and note the article date) -- Social media profiles show follower counts -- Interview quotes reveal personality, brand voice, and creative direction -- Fan forums and Reddit surface psychographic insights - -The report will have more `[estimated]` and `[gap]` markers, but that's honest and useful — it tells the next person exactly where to invest in better data. diff --git a/recoup-research/SKILL.md b/recoup-research/SKILL.md new file mode 100644 index 0000000..77b78c1 --- /dev/null +++ b/recoup-research/SKILL.md @@ -0,0 +1,128 @@ +--- +name: recoup-research +description: Music industry research via `recoup research` CLI — streaming metrics, audience demographics, playlist placements, competitive analysis, people search, URL extraction, structured enrichment, and web intelligence. Use when the user needs artist analytics, streaming numbers, audience insights, playlist tracking, similar artists, collaboration targets, tour routing data, or any music industry research. Also use for finding people in the industry (managers, A&R), extracting data from URLs, or enriching entities with structured web research. Triggers on requests involving Spotify followers, monthly listeners, TikTok trends, Instagram audience, playlist pitching, competitive analysis, "how is [artist] doing," "research [artist]," "find me [people]," or any question about an artist's performance, market position, or industry contacts. +--- + +# Recoup Research + +Music industry research through the `recoup research` CLI. Covers artist analytics, web intelligence, people search, URL extraction, and structured data enrichment — all through one command with `RECOUP_API_KEY` auth. + +## Setup + +In sandboxes, the CLI is already installed and authenticated. Otherwise: + +```bash +npm install -g @recoupable/cli +export RECOUP_API_KEY=your-api-key +``` + +## Quick Start + +```bash +recoup research "Kaash Paige" --json # find artist +recoup research metrics "Kaash Paige" --source spotify --json # streaming data +recoup research cities "Kaash Paige" --json # where fans are +recoup research similar "Kaash Paige" --json # competitors +``` + +Every artist-scoped command accepts an **artist name** — the API resolves it internally. Always use `--json` when chaining commands. + +--- + +## Commands + +### Artist Data + +| Command | What It Returns | +|---------|----------------| +| `recoup research "Drake"` | Search results with name, ID, listeners, followers | +| `recoup research profile "Drake"` | Bio, genres, social URLs, label, career stage | +| `recoup research metrics "Drake" --source spotify` | Time-series streaming/social metrics (14 platforms) | +| `recoup research audience "Drake"` | Age, gender, country demographics (Instagram default) | +| `recoup research audience "Drake" --platform tiktok` | TikTok demographics | +| `recoup research cities "Drake"` | Top cities ranked by listener count | +| `recoup research similar "Drake"` | Peers with career stage, momentum, listener counts | +| `recoup research similar "Drake" --audience high --genre high` | Filtered by similarity dimensions | +| `recoup research urls "Drake"` | All social/streaming links | +| `recoup research instagram-posts "Drake"` | Top posts/reels by engagement | +| `recoup research playlists "Drake"` | Current playlist placements with follower counts | +| `recoup research playlists "Drake" --editorial` | Editorial playlists only | +| `recoup research albums "Drake"` | Full discography with release dates | +| `recoup research tracks "Drake"` | All tracks with popularity | +| `recoup research career "Drake"` | Career timeline and milestones | +| `recoup research insights "Drake"` | AI-generated observations and trends | + +### Non-Artist Data + +| Command | What It Returns | +|---------|----------------| +| `recoup research lookup "https://open.spotify.com/artist/..."` | Artist from platform URL | +| `recoup research track "God's Plan"` | Track metadata | +| `recoup research playlist spotify 1645080` | Playlist details | +| `recoup research curator spotify 1` | Curator profile | +| `recoup research discover --country US --spotify-listeners 100000,500000` | Find artists by criteria | +| `recoup research genres` | All genre IDs (use with discover) | +| `recoup research festivals` | Music festivals | + +### Web Intelligence + +| Command | What It Returns | +|---------|----------------| +| `recoup research web "Drake brand partnerships"` | Web search results (Perplexity) | +| `recoup research report "Tell me about Kaash Paige"` | Comprehensive cited research report | +| `recoup research people "A&R reps at Atlantic Records"` | LinkedIn profiles and summaries (Exa) | +| `recoup research extract "https://en.wikipedia.org/wiki/Drake_(musician)"` | Clean markdown from any URL (Parallel) | +| `recoup research enrich "Kaash Paige" --schema '{"properties":{"label":{"type":"string"}}}'` | Structured data with citations (Parallel) | + +### Platform Metrics Sources + +Valid `--source` values for the `metrics` command: `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` + +### Gotcha + +YouTube metrics use `youtube_channel` — not `youtube`. + +--- + +## When to Use Which Command + +| User asks... | Use | +|-------------|-----| +| "How's Drake doing on Spotify?" | `metrics --source spotify` | +| "Where are Drake's fans?" | `cities` + `audience` | +| "Who should I pitch to?" | `similar` → `playlists` on each peer | +| "Who manages this artist?" | `people` | +| "What does this website say?" | `extract` | +| "Give me structured data about X" | `enrich` | +| "Tell me everything about X" | `report` (deep) or chain multiple commands | +| "Find emerging artists in hip-hop" | `discover --genre ` | +| "Is TikTok translating to Spotify?" | `metrics --source tiktok` + `metrics --source spotify` | + +--- + +## Workflow Chains + +For strategic questions that require chaining multiple commands, read `references/workflows.md`. It covers 10 workflow chains: + +| Workflow | Question | +|----------|----------| +| Playlist Pitching | Which curators should I pitch to? | +| TikTok Pipeline | Is TikTok virality translating to Spotify? | +| Tour Routing | Where should this artist tour next? | +| A&R Discovery | Find emerging artists before they blow up | +| Catalog Optimization | Which songs should we push and where? | +| Competitive Roster | How does our roster compare? | +| Viral Autopsy | Why did this song go viral? | +| Market Expansion | Which new markets to focus on? | +| Collaboration Finder | Who should we collaborate with? | +| Release Timing | When should we release? | + +--- + +## Tips + +1. **Always use `--json`** when chaining — structured output is easier to parse. +2. **Run independent commands in parallel** — metrics, audience, cities don't depend on each other. +3. **YouTube uses `youtube_channel`** not `youtube` — the most common gotcha. +4. **Cross-reference for insights** — cities + audience = geographic strategy; similar + playlists = pitch targets. +5. **The `enrich` command is powerful** — define any JSON schema and get structured data back with citations. Use for anything web research can answer. diff --git a/recoup-research/references/workflows.md b/recoup-research/references/workflows.md new file mode 100644 index 0000000..ab93492 --- /dev/null +++ b/recoup-research/references/workflows.md @@ -0,0 +1,283 @@ +# Research Workflow Chains + +Multi-step workflows that chain `recoup research` commands to answer strategic questions. Each workflow tells you what to run, in what order, and what to look for in the results. + +--- + +## 1. Playlist Pitching Intelligence + +**Question:** "Which playlist curators should I pitch to?" + +```bash +# 1. Find similar artists who are slightly bigger (good benchmarks) +recoup research similar "{ARTIST}" --audience high --genre high --limit 50 --json + +# 2. For each similar artist, get their editorial playlist placements +recoup research playlists "{similar_artist}" --editorial --json + +# 3. Look for playlist overlap — curators who added multiple similar artists +# These curators are most likely to add your artist + +# 4. For promising playlists, get curator details +recoup research playlist spotify {playlist_id} --json +recoup research curator spotify {curator_id} --json + +# 5. Check if target artist was ever on these playlists before +recoup research playlists "{ARTIST}" --status past --json +``` + +**What to synthesize:** List of curators who already playlist similar artists but haven't added yours yet. Prioritize curators who've added 2+ similar artists — they're the warmest targets. + +--- + +## 2. TikTok-to-Spotify Pipeline Analysis + +**Question:** "Is TikTok virality translating to Spotify growth?" + +```bash +# 1. Get TikTok metrics over time +recoup research metrics "{ARTIST}" --source tiktok --json + +# 2. Get Spotify metrics over same period +recoup research metrics "{ARTIST}" --source spotify --json + +# 3. Get TikTok audience demographics +recoup research audience "{ARTIST}" --platform tiktok --json + +# 4. Get Spotify listener cities +recoup research cities "{ARTIST}" --json + +# 5. Get top Instagram posts (often cross-posted from TikTok) +recoup research instagram-posts "{ARTIST}" --json +``` + +**What to synthesize:** Correlation between TikTok follower spikes and Spotify listener growth. Geographic mismatch = opportunity (e.g., TikTok viral in Brazil but Spotify listeners mostly in US means Brazil is an untapped market). + +--- + +## 3. Tour Routing Intelligence + +**Question:** "Where should this artist tour next?" + +```bash +# 1. Get top listener cities +recoup research cities "{ARTIST}" --json + +# 2. Get festivals +recoup research festivals --json + +# 3. Find similar artists and their cities (for co-headlining opportunities) +recoup research similar "{ARTIST}" --audience high --limit 20 --json + +# 4. Get audience breakdown by platform and region +recoup research audience "{ARTIST}" --platform youtube --json +recoup research audience "{ARTIST}" --platform instagram --json + +# 5. Check playlist reach by geography +recoup research playlists "{ARTIST}" --sort followers --json +``` + +**What to synthesize:** Ranked cities by streaming engagement, cross-referenced with festival opportunities. Cities where similar artists tour successfully but this artist hasn't been = expansion opportunities. + +--- + +## 4. A&R Discovery + +**Question:** "Find emerging artists in [genre] before they blow up" + +```bash +# 1. Start with a breakout artist in the genre as anchor +recoup research "{ANCHOR_ARTIST}" --json + +# 2. Find artists similar by musicality (not audience — we want undiscovered) +recoup research similar "{ANCHOR_ARTIST}" --musicality high --genre high --limit 50 --json + +# 3. For promising candidates, check their trajectory +recoup research metrics "{candidate}" --source spotify --json +recoup research metrics "{candidate}" --source tiktok --json + +# 4. Check playlist traction (editorial placements = label interest signal) +recoup research playlists "{candidate}" --editorial --json + +# 5. Get AI insights +recoup research insights "{candidate}" --json +``` + +**What to synthesize:** Emerging artists with similar sound but smaller audience, sorted by growth velocity. Filter for career_stage "undiscovered" or "developing" in the similar artists response. + +--- + +## 5. Catalog Optimization + +**Question:** "Which songs should we push and where?" + +```bash +# 1. Get all tracks +recoup research tracks "{ARTIST}" --json + +# 2. Get playlist placements (which songs are playlisted?) +recoup research playlists "{ARTIST}" --json + +# 3. Get albums with release dates +recoup research albums "{ARTIST}" --json + +# 4. Get metrics to compare against release dates +recoup research metrics "{ARTIST}" --source spotify --json +recoup research metrics "{ARTIST}" --source tiktok --json +``` + +**What to synthesize:** Track-by-track analysis. Look for: +- High playlist reach but low streams = discovery issue (content isn't converting) +- Low playlist but high TikTok = pitch opportunity (organic momentum, needs editorial support) +- Old songs suddenly getting playlisted = catalog momentum (amplify it) + +--- + +## 6. Competitive Roster Analysis + +**Question:** "How does our roster compare to a competitor label?" + +```bash +# For each artist on your roster: + +# 1. Get profile and metrics +recoup research profile "{your_artist}" --json +recoup research metrics "{your_artist}" --source spotify --json + +# 2. Find similar artists (potential competitor roster) +recoup research similar "{your_artist}" --audience high --genre high --json + +# 3. Compare playlist reach +recoup research playlists "{your_artist}" --sort followers --json +recoup research playlists "{competitor_artist}" --sort followers --json + +# 4. Compare audience demographics +recoup research audience "{your_artist}" --json +recoup research audience "{competitor_artist}" --json + +# 5. Compare where fans listen +recoup research cities "{your_artist}" --json +recoup research cities "{competitor_artist}" --json +``` + +**What to synthesize:** Side-by-side comparison. Identify where your roster under-indexes vs competitors on specific metrics — those are the gaps to close. + +--- + +## 7. Viral Song Autopsy + +**Question:** "Why did this song go viral? Can we replicate it?" + +```bash +# 1. Get track details +recoup research track "{SONG_NAME_OR_URL}" --json + +# 2. Get metrics around release date +recoup research metrics "{ARTIST}" --source spotify --json +recoup research metrics "{ARTIST}" --source tiktok --json + +# 3. Check playlist placements timeline +recoup research playlists "{ARTIST}" --since 2025-01-01 --sort followers --json + +# 4. Get AI insights (may mention the viral moment) +recoup research insights "{ARTIST}" --json + +# 5. Check if similar artists had similar trajectory +recoup research similar "{ARTIST}" --musicality high --json +``` + +**What to synthesize:** Timeline of the viral moment — what platform it started on, which playlists amplified it, which audience demographics drove sharing. Compare with similar artists' trajectories to identify if the pattern is replicable. + +--- + +## 8. Market Expansion Scouting + +**Question:** "Which new markets should we focus on?" + +```bash +# 1. Current listener geography +recoup research cities "{ARTIST}" --json + +# 2. Platform-specific audience breakdown +recoup research audience "{ARTIST}" --json +recoup research audience "{ARTIST}" --platform tiktok --json +recoup research audience "{ARTIST}" --platform youtube --json + +# 3. Find similar artists and their top cities +recoup research similar "{ARTIST}" --genre high --limit 10 --json +# For each similar artist: +recoup research cities "{similar_artist}" --json + +# 4. Check playlist coverage in potential markets +recoup research playlists "{ARTIST}" --json +``` + +**What to synthesize:** Cities where similar artists thrive but the target artist is weak = expansion opportunities. Cross-reference with playlist coverage — markets with fans but no playlist presence need pitching. + +--- + +## 9. Collaboration Finder + +**Question:** "Which artists should we collaborate with?" + +```bash +# 1. Find artists with shared fanbase +recoup research similar "{ARTIST}" --audience high --limit 30 --json + +# 2. Find artists with genre/sound overlap +recoup research similar "{ARTIST}" --genre high --musicality high --json + +# 3. Compare playlist placements (shared playlists = easy collab pitch) +recoup research playlists "{ARTIST}" --editorial --json +recoup research playlists "{collab_target}" --editorial --json + +# 4. Compare geographic overlap (shared cities = tour collab opportunity) +recoup research cities "{ARTIST}" --json +recoup research cities "{collab_target}" --json +``` + +**What to synthesize:** Ranked collaboration targets by audience overlap, career stage (slightly bigger = ideal), and playlist synergy. Shared playlists + shared cities = strongest collab case. + +--- + +## 10. Release Strategy Timing + +**Question:** "When should we release, and how should we roll it out?" + +```bash +# 1. Analyze past releases +recoup research albums "{ARTIST}" --json +recoup research career "{ARTIST}" --json + +# 2. Check what worked — playlist adds after previous releases +recoup research playlists "{ARTIST}" --status past --since 2024-01-01 --json + +# 3. Look at similar artists' successful releases +recoup research similar "{ARTIST}" --audience high --limit 10 --json +recoup research albums "{similar_artist}" --json +recoup research career "{similar_artist}" --json + +# 4. Check current playlist momentum +recoup research playlists "{ARTIST}" --editorial --json + +# 5. Identify which platforms are hottest right now +recoup research metrics "{ARTIST}" --source spotify --json +recoup research metrics "{ARTIST}" --source tiktok --json +recoup research metrics "{ARTIST}" --source youtube_channel --json +``` + +**What to synthesize:** Release timing recommendation based on historical patterns (when did past releases get the most playlist adds?), similar artists' release cycles, and which platform has the most momentum right now. + +--- + +## Building Your Own Workflows + +The power is in combining data types: + +| What You Need | Command | Use For | +|---------------|---------|---------| +| **Who** — peers, competitors, collaborators | `similar` | Finding benchmarks, pitch targets, collab opportunities | +| **Where** — geographic data | `cities`, `audience` | Tour routing, market expansion, geographic strategy | +| **What** — content and catalog | `playlists`, `tracks`, `albums` | Content strategy, playlist pitching, catalog optimization | +| **When** — timing and trajectory | `metrics`, `career` | Release timing, growth analysis, trend detection | +| **Why** — context and narrative | `insights`, `web`, `report` | Cultural positioning, press strategy, brand partnerships | From 040d2a591757bb97233d1cbae8fdc8cadb308360 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 19:23:56 -0400 Subject: [PATCH 3/5] feat: rewrite skill from command reference to strategic guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added: - Decision tree — routes user questions to the right commands - Response shapes — shows what each command returns as JSON - Data interpretation — what the numbers MEAN (ratios, thresholds) - Synthesis patterns — how to combine endpoints into insights - Workspace integration — where to save research results - Graceful degradation — what to do when Chartmetric has no data - What NOT to do — don't dump JSON, don't over-fetch, don't ignore existing context The skill now teaches agents HOW TO THINK about research, not just which commands to type. Made-with: Cursor --- recoup-research/SKILL.md | 216 +++++++++++++++++++++++---------------- 1 file changed, 128 insertions(+), 88 deletions(-) diff --git a/recoup-research/SKILL.md b/recoup-research/SKILL.md index 77b78c1..5aedc2d 100644 --- a/recoup-research/SKILL.md +++ b/recoup-research/SKILL.md @@ -5,124 +5,164 @@ description: Music industry research via `recoup research` CLI — streaming met # Recoup Research -Music industry research through the `recoup research` CLI. Covers artist analytics, web intelligence, people search, URL extraction, and structured data enrichment — all through one command with `RECOUP_API_KEY` auth. +Music industry research through the `recoup research` CLI. All commands use `RECOUP_API_KEY` for auth. In sandboxes, this is already configured. -## Setup +## Before You Research -In sandboxes, the CLI is already installed and authenticated. Otherwise: +1. Check if the artist has a workspace with `context/artist.md` — don't re-research what's already known. +2. Decide what the user actually needs. "How's Drake doing?" needs 2-3 commands, not 20. +3. Always use `--json` when you'll process the output programmatically. + +## Decision Tree + +Start here based on what the user asks: + +**"How is [artist] doing?"** → `metrics --source spotify` + `cities` + `insights` + +**"Research [artist] for me"** → Full chain: `profile` → parallel(`metrics`, `audience`, `cities`, `similar`, `playlists`) → `web` for narrative context → synthesize + +**"Who should I pitch to?"** → `similar --audience high --genre high` → `playlists` on each peer → find playlists that have peers but not your artist + +**"Where should we tour?"** → `cities` + `audience --platform youtube` + `festivals` + +**"Find me [people]"** → `people "A&R reps at [label]"` + +**"Tell me about [entity]"** → `enrich "[entity]" --schema '{...}'` for structured data, or `report "[entity]"` for a narrative + +**"What does this page say?"** → `extract "https://..."` + +**"Find emerging artists"** → `discover --country US --genre --spotify-listeners 50000,200000` + +If none of these match, start with `web "query"` for general research. + +--- + +## Commands Quick Reference + +### Artist Data (accept artist name, API resolves internally) ```bash -npm install -g @recoupable/cli -export RECOUP_API_KEY=your-api-key +recoup research "Drake" --json # search — returns { results: [{ name, id, sp_monthly_listeners, sp_followers }] } +recoup research profile "Drake" --json # full profile — { name, genres, country_code, cm_artist_score, ... } +recoup research metrics "Drake" --source spotify --json # time-series — { followers: [...], listeners: [...], popularity: [...] } +recoup research audience "Drake" --json # demographics — { audience_genders: [...], audience_genders_per_age: [...], top_countries: [...] } +recoup research cities "Drake" --json # geography — { cities: [{ name, country, listeners }] } +recoup research similar "Drake" --json # competitors — { artists: [{ name, career_stage, recent_momentum, sp_monthly_listeners }] } +recoup research playlists "Drake" --json # placements — { placements: [{ playlist: { name, followers }, track: { name } }] } +recoup research albums "Drake" --json # discography — { albums: [{ name, release_date }] } +recoup research tracks "Drake" --json # tracks — { tracks: [{ name, id }] } +recoup research career "Drake" --json # timeline — career milestones array +recoup research insights "Drake" --json # AI observations — { insights: [{ insight: "text" }] } +recoup research urls "Drake" --json # social links — { urls: [{ domain, url }] } +recoup research instagram-posts "Drake" --json # top posts/reels ``` -## Quick Start +### Non-Artist Data ```bash -recoup research "Kaash Paige" --json # find artist -recoup research metrics "Kaash Paige" --source spotify --json # streaming data -recoup research cities "Kaash Paige" --json # where fans are -recoup research similar "Kaash Paige" --json # competitors +recoup research lookup "https://open.spotify.com/artist/..." --json +recoup research track "God's Plan" --json +recoup research playlist spotify 1645080 --json +recoup research curator spotify 1 --json +recoup research discover --country US --spotify-listeners 100000,500000 --json +recoup research genres --json +recoup research festivals --json ``` -Every artist-scoped command accepts an **artist name** — the API resolves it internally. Always use `--json` when chaining commands. +### Web Intelligence ---- +```bash +recoup research web "Drake brand partnerships" --json # web search — { results: [{ title, url, snippet }] } +recoup research report "Tell me about Kaash Paige" --json # deep research — { content: "markdown report", citations: [...] } +recoup research people "A&R reps at Atlantic Records" --json # people search — { results: [{ title, url, summary }] } +recoup research extract "https://example.com" --json # URL scraping — { results: [{ title, url, excerpts: [...] }] } +recoup research enrich "Kaash Paige" --schema '{"properties":{"label":{"type":"string"}}}' --json # structured — { output: { label: "Rostrum Records" } } +``` -## Commands - -### Artist Data - -| Command | What It Returns | -|---------|----------------| -| `recoup research "Drake"` | Search results with name, ID, listeners, followers | -| `recoup research profile "Drake"` | Bio, genres, social URLs, label, career stage | -| `recoup research metrics "Drake" --source spotify` | Time-series streaming/social metrics (14 platforms) | -| `recoup research audience "Drake"` | Age, gender, country demographics (Instagram default) | -| `recoup research audience "Drake" --platform tiktok` | TikTok demographics | -| `recoup research cities "Drake"` | Top cities ranked by listener count | -| `recoup research similar "Drake"` | Peers with career stage, momentum, listener counts | -| `recoup research similar "Drake" --audience high --genre high` | Filtered by similarity dimensions | -| `recoup research urls "Drake"` | All social/streaming links | -| `recoup research instagram-posts "Drake"` | Top posts/reels by engagement | -| `recoup research playlists "Drake"` | Current playlist placements with follower counts | -| `recoup research playlists "Drake" --editorial` | Editorial playlists only | -| `recoup research albums "Drake"` | Full discography with release dates | -| `recoup research tracks "Drake"` | All tracks with popularity | -| `recoup research career "Drake"` | Career timeline and milestones | -| `recoup research insights "Drake"` | AI-generated observations and trends | +### Platform Sources (for `metrics` command) -### Non-Artist Data +`spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` -| Command | What It Returns | -|---------|----------------| -| `recoup research lookup "https://open.spotify.com/artist/..."` | Artist from platform URL | -| `recoup research track "God's Plan"` | Track metadata | -| `recoup research playlist spotify 1645080` | Playlist details | -| `recoup research curator spotify 1` | Curator profile | -| `recoup research discover --country US --spotify-listeners 100000,500000` | Find artists by criteria | -| `recoup research genres` | All genre IDs (use with discover) | -| `recoup research festivals` | Music festivals | +YouTube uses `youtube_channel` — not `youtube`. -### Web Intelligence +--- + +## Interpreting the Data -| Command | What It Returns | -|---------|----------------| -| `recoup research web "Drake brand partnerships"` | Web search results (Perplexity) | -| `recoup research report "Tell me about Kaash Paige"` | Comprehensive cited research report | -| `recoup research people "A&R reps at Atlantic Records"` | LinkedIn profiles and summaries (Exa) | -| `recoup research extract "https://en.wikipedia.org/wiki/Drake_(musician)"` | Clean markdown from any URL (Parallel) | -| `recoup research enrich "Kaash Paige" --schema '{"properties":{"label":{"type":"string"}}}'` | Structured data with citations (Parallel) | +Raw numbers are noise without interpretation. Here's what to look for: -### Platform Metrics Sources +**Metrics:** +- Follower-to-listener ratio above 20% = dedicated fan base (they follow, not just stream) +- Save-to-listener ratio above 3% = strong catalog stickiness +- Week-over-week listener growth above 5% = momentum +- Popularity score trending up = algorithmic favor -Valid `--source` values for the `metrics` command: `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` +**Cities:** +- If top cities are international but playlists are US-only = untapped international opportunity +- If a city has high listeners but the artist has never toured there = tour opportunity +- Compare with similar artists' cities to find geographic white space -### Gotcha +**Similar Artists:** +- `career_stage`: undiscovered → developing → mid-level → mainstream → superstar → legendary +- `recent_momentum`: decline → gradual decline → steady → growth → explosive growth +- If the artist's peers are all "mainstream" but they're "mid-level" = breakout potential +- Peers with playlists you're NOT on = pitch targets -YouTube metrics use `youtube_channel` — not `youtube`. +**Playlists:** +- 2 editorial playlists for 5M+ listeners = severely under-playlisted (pitch immediately) +- Follower count on playlists tells you reach potential +- Past placements (`--status past`) that dropped off = re-pitch opportunities + +**Audience:** +- Gender skew tells you content strategy (visual style, messaging) +- Age concentration tells you platform priority (Gen Z = TikTok, 25-34 = Instagram) +- Country mismatch between audience and cities = content localization opportunity --- -## When to Use Which Command +## Synthesis Patterns + +Don't dump raw data. Combine endpoints and draw conclusions: + +**Geographic Strategy:** `cities` + `audience` → "Sao Paulo is #1 (135K listeners) but audience is 80% US on Instagram. There's a massive Brazilian fan base that isn't being served with localized content." + +**Playlist Gap Analysis:** `similar` → `playlists` on each peer → "5 of your 10 peers are on 'R&B Rotation' (450K followers) but you're not. That's your top pitch target." + +**Platform Pipeline:** `metrics --source tiktok` + `metrics --source spotify` → "TikTok followers grew 40% last month but Spotify listeners are flat. The TikTok virality isn't converting. Need Spotify-specific CTAs on TikTok content." -| User asks... | Use | -|-------------|-----| -| "How's Drake doing on Spotify?" | `metrics --source spotify` | -| "Where are Drake's fans?" | `cities` + `audience` | -| "Who should I pitch to?" | `similar` → `playlists` on each peer | -| "Who manages this artist?" | `people` | -| "What does this website say?" | `extract` | -| "Give me structured data about X" | `enrich` | -| "Tell me everything about X" | `report` (deep) or chain multiple commands | -| "Find emerging artists in hip-hop" | `discover --genre ` | -| "Is TikTok translating to Spotify?" | `metrics --source tiktok` + `metrics --source spotify` | +**Career Positioning:** `similar` → compare career stages → "You're the only 'mainstream' artist in your peer group — everyone else is 'mid-level'. You have positioning leverage for brand deals and festival slots." --- -## Workflow Chains +## Saving Research -For strategic questions that require chaining multiple commands, read `references/workflows.md`. It covers 10 workflow chains: +If working in an artist workspace, save research results to `research/` with timestamps: -| Workflow | Question | -|----------|----------| -| Playlist Pitching | Which curators should I pitch to? | -| TikTok Pipeline | Is TikTok virality translating to Spotify? | -| Tour Routing | Where should this artist tour next? | -| A&R Discovery | Find emerging artists before they blow up | -| Catalog Optimization | Which songs should we push and where? | -| Competitive Roster | How does our roster compare? | -| Viral Autopsy | Why did this song go viral? | -| Market Expansion | Which new markets to focus on? | -| Collaboration Finder | Who should we collaborate with? | -| Release Timing | When should we release? | +``` +research/artist-intel-2026-03-27.md +``` + +Don't overwrite `context/artist.md` with research data. Static context (who the artist IS) is separate from dynamic research (how they're performing NOW). If the research reveals something that should update the static profile, suggest it to the user — don't auto-update. --- -## Tips +## What Not to Do + +- **Don't run 20 commands when 3 will answer the question.** Start small, expand if needed. +- **Don't dump raw JSON to the user.** Interpret the data and draw conclusions. +- **Don't re-research what `context/artist.md` already covers.** Read it first. +- **Don't ignore the `--json` flag when chaining.** Tables are for humans, JSON is for you. +- **Don't assume Chartmetric has every artist.** If search returns no results, fall back to `web` or `report`. + +--- + +## Graceful Degradation + +If `recoup research "Artist Name"` returns no results: +1. Try `recoup research web "Artist Name musician"` for web-based research +2. Try `recoup research enrich "Artist Name" --schema '{...}'` for structured extraction +3. For very emerging artists, Chartmetric may not have data yet — web research is the fallback + +## More Workflows -1. **Always use `--json`** when chaining — structured output is easier to parse. -2. **Run independent commands in parallel** — metrics, audience, cities don't depend on each other. -3. **YouTube uses `youtube_channel`** not `youtube` — the most common gotcha. -4. **Cross-reference for insights** — cities + audience = geographic strategy; similar + playlists = pitch targets. -5. **The `enrich` command is powerful** — define any JSON schema and get structured data back with citations. Use for anything web research can answer. +Read `references/workflows.md` for 10 complete multi-step workflow chains covering playlist pitching, competitive analysis, tour routing, A&R discovery, and more. From 8594403be2b1175098d950b039e5658e01ec0082 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:08:34 -0400 Subject: [PATCH 4/5] fix: replace Kaash Paige examples with Drake Made-with: Cursor --- recoup-research/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/recoup-research/SKILL.md b/recoup-research/SKILL.md index 5aedc2d..8b12bc5 100644 --- a/recoup-research/SKILL.md +++ b/recoup-research/SKILL.md @@ -73,10 +73,10 @@ recoup research festivals --json ```bash recoup research web "Drake brand partnerships" --json # web search — { results: [{ title, url, snippet }] } -recoup research report "Tell me about Kaash Paige" --json # deep research — { content: "markdown report", citations: [...] } +recoup research report "Tell me about Drake" --json # deep research — { content: "markdown report", citations: [...] } recoup research people "A&R reps at Atlantic Records" --json # people search — { results: [{ title, url, summary }] } recoup research extract "https://example.com" --json # URL scraping — { results: [{ title, url, excerpts: [...] }] } -recoup research enrich "Kaash Paige" --schema '{"properties":{"label":{"type":"string"}}}' --json # structured — { output: { label: "Rostrum Records" } } +recoup research enrich "Drake" --schema '{"properties":{"label":{"type":"string"}}}' --json # structured — { output: { label: "OVO Sound" } } ``` ### Platform Sources (for `metrics` command) From f10c32b288c78cd0abda8a15e1f1afc66e0a8722 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sun, 29 Mar 2026 21:23:44 -0400 Subject: [PATCH 5/5] fix: remove angle brackets, clarify youtube_channel vs youtube scope Made-with: Cursor --- recoup-research/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/recoup-research/SKILL.md b/recoup-research/SKILL.md index 8b12bc5..a5d04f9 100644 --- a/recoup-research/SKILL.md +++ b/recoup-research/SKILL.md @@ -31,7 +31,7 @@ Start here based on what the user asks: **"What does this page say?"** → `extract "https://..."` -**"Find emerging artists"** → `discover --country US --genre --spotify-listeners 50000,200000` +**"Find emerging artists"** → `discover --country US --genre GENRE_ID --spotify-listeners 50000,200000` (get IDs from `recoup research genres`) If none of these match, start with `web "query"` for general research. @@ -83,7 +83,7 @@ recoup research enrich "Drake" --schema '{"properties":{"label":{"type":"string" `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` -YouTube uses `youtube_channel` — not `youtube`. +For **`metrics` only**, YouTube uses `youtube_channel` (not plain `youtube`). The **`audience`** command is different: Chartmetric’s path is `youtube-audience-stats`, so there you pass `--platform youtube` (see examples above). Do not use `youtube_channel` for `audience`. ---