docs: introduce Skills system

skills.mdx

@@ -0,0 +1,66 @@
+---
+title: "Skills"
+description: "Markdown playbooks that teach AI agents how to do music industry work. The other half of the agent equation."
+---
+
+*An agent asked to "help me grow my new artist past 1,000 monthly listeners" finds the `streaming-growth` skill, loads it, and follows the playbook — playlist pitching benchmarks, Spotify Showcase thresholds, decision frameworks.*
+
+The API tells an agent **how** to take action. Skills tell it **when** and **why**.
+
+A Skill is a markdown file an agent reads to get domain-specific instructions for a task. They live in a separate repo so any agent (Claude Code, Cursor, or your own) can install them without coupling to a specific platform.
+
+The sidebar lists every skill, grouped by purpose. Each docs page summarizes when the agent uses the skill, what it produces, and which API endpoints it depends on. The canonical instructions stay in the source repo on GitHub.
+
+---
+
+## Install
+
+### Claude Code
+
+```bash
+/plugin marketplace add recoupable/skills
+```
+
+### Any other agent
+
+```bash
+git clone https://github.com/recoupable/skills.git
+```
+
+Point your agent at the resulting `skills/` directory. The agent loads each `SKILL.md` and uses its `description` field to decide when the skill applies.
+
+---
+
+## How a Skill is structured
+
+Every skill is a directory with a `SKILL.md` at the root. The `description` field in the YAML frontmatter is what the agent reads to decide when to invoke the skill — write it as a trigger, not a summary.
+
+```text
+skills/
+└── my-skill/
+    ├── SKILL.md       ← required (frontmatter + instructions)
+    ├── references/    ← optional — docs the agent loads on demand
+    ├── scripts/       ← optional — executable helpers
+    └── assets/        ← optional — templates, fonts, icons
+```
+
+Minimum viable `SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: One-line trigger that tells the agent when to use this. Include the kinds of phrases users say — "playlist push," "release plan," "growth strategy."
+---
+
+# My Skill
+
+Step-by-step instructions the agent follows.
+```
+
+---
+
+## Writing your own
+
+Add a directory under `skills/` in [recoupable/skills](https://github.com/recoupable/skills), follow the structure above, and open a PR. See [contributing.md](https://github.com/recoupable/skills/blob/main/contributing.md) for the full guidelines.
+
+The bar: a skill should be specific enough that an agent would correctly invoke it without your help, and complete enough that it can finish the task without asking the user follow-ups it could have answered itself.

skills/artist-workspace.mdx

@@ -0,0 +1,25 @@
+---
+title: "artist-workspace"
+description: "Manage artist directories — identity, brand, voice, audience, songs, face guides."
+---
+
+Every managed artist has a workspace at `orgs/{org}/artists/{artist-slug}/`. This skill teaches the agent the conventions for what files belong where, when to create them, and how to read existing context before overwriting anything.
+
+## When to use it
+
+Adding or updating any artist-specific context — identity, brand, voice, audience, songs, face guides — or the user mentions an artist by name and the task touches their files. Also runs implicitly before research, content, or release work that needs to be artist-scoped.
+
+## What it produces
+
+Updates inside the artist directory: `RECOUP.md` (workspace anchor), `context/artist.md` (source of truth for who the artist is), `brand/`, `audience/`, `songs/`, `face-guide/` — populated only when there's real content for them.
+
+## Endpoints it uses
+
+- [`GET /api/artists`](/api-reference/artists/list)
+- [`POST /api/artists`](/api-reference/artists/create)
+- [`GET /api/artist-profile`](/api-reference/artist/profile)
+- [`GET /api/artists/{id}/socials`](/api-reference/artists/socials)
+
+## Source
+
+[`recoupable/skills/skills/artist-workspace`](https://github.com/recoupable/skills/tree/main/skills/artist-workspace)

skills/chart-metric.mdx

@@ -0,0 +1,22 @@
+---
+title: "chart-metric"
+description: "Query and analyze music data from the Chartmetric API directly."
+---
+
+The escape hatch when the Recoup `/api/research/*` endpoints don't expose the field you need. Hits Chartmetric's API directly via Python helper scripts.
+
+## When to use it
+
+You need a data point from Chartmetric that the Recoup research surface doesn't return — usually deeper historical series, raw chart history, or metadata fields the Recoup wrapper omits. For everything Recoup already exposes, use [`music-industry-research`](/skills/music-industry-research) instead.
+
+## What it produces
+
+A direct Chartmetric API response, usually fed back into the agent's reasoning or written to a file in the artist workspace.
+
+## Endpoints it uses
+
+None on the Recoup API. This skill calls Chartmetric directly using a `CHARTMETRIC_REFRESH_TOKEN` environment variable.
+
+## Source
+
+[`recoupable/skills/skills/chart-metric`](https://github.com/recoupable/skills/tree/main/skills/chart-metric)

skills/content-creation.mdx

@@ -0,0 +1,28 @@
+---
+title: "Content Creation"
+description: "Compose the content endpoints (image, video, caption, transcribe, edit, upscale, analyze) into short-form videos, Reels, TikToks, and lipsync clips."
+---
+
+Turns the seven content primitives into finished assets. Picks the right combination of generate, transcribe, edit, upscale, and analyze for the specific output the user asked for — and iterates on quality (regenerate, re-prompt, re-mux) when the first pass isn't right.
+
+## When to use it
+
+User asks to create content, make a video, generate an image, produce a TikTok or Reel, create a promotional clip, add captions, or create visual content for an artist. Also use when iterating on existing content — regenerating images, trying different audio, adjusting text, upscaling for higher quality.
+
+## What it produces
+
+A finished asset (image, video, captioned clip, lipsync, upscaled version) saved into the artist workspace, with the underlying generation parameters logged for reproducibility.
+
+## Endpoints it uses
+
+- [`POST /api/content/image`](/api-reference/content/generate-image)
+- [`POST /api/content/video`](/api-reference/content/generate-video)
+- [`POST /api/content/caption`](/api-reference/content/generate-caption)
+- [`POST /api/content/transcribe`](/api-reference/content/transcribe-audio)
+- [`PATCH /api/content`](/api-reference/content/edit)
+- [`POST /api/content/upscale`](/api-reference/content/upscale)
+- [`POST /api/content/analyze`](/api-reference/content/analyze-video)
+
+## Source
+
+[`recoupable/skills/skills/content-creation`](https://github.com/recoupable/skills/tree/main/skills/content-creation)

skills/getting-started.mdx

@@ -0,0 +1,23 @@
+---
+title: "getting-started"
+description: "Set up Recoup from scratch — get an API key, verify it, and make the first call via REST or MCP."
+---
+
+The agent's bootstrap. Walks through getting an API key, picking REST or MCP, and confirming the key works before any other skill runs.
+
+## When to use it
+
+User says "set up Recoup", "install Recoup", "get an API key", "connect to Recoup", "onboard to Recoup", or an agent needs to configure itself before it can call anything else.
+
+## What it produces
+
+A working `RECOUP_API_KEY` environment variable, the chosen base URL (REST or MCP), and a verified first response.
+
+## Endpoints it uses
+
+- [`POST /api/agents/signup`](/api-reference/agents/signup)
+- [`POST /api/agents/verify`](/api-reference/agents/verify)
+
+## Source
+
+[`recoupable/skills/skills/getting-started`](https://github.com/recoupable/skills/tree/main/skills/getting-started)

skills/music-industry-research.mdx

@@ -0,0 +1,24 @@
+---
+title: "music-industry-research"
+description: "Use the /api/research/* endpoints for analytics, audience demographics, playlists, charts, and people search."
+---
+
+The decision tree for picking the right `/api/research/*` endpoint based on what the user actually asked. Includes a routing table from natural-language questions to specific endpoint combinations.
+
+## When to use it
+
+User asks about an artist's analytics, streaming numbers, audience demographics, playlist placements, similar artists, charts, tour or venue data, or any music industry research. Also triggers on "find me people in [function]," "tell me about [entity]," or "what does this page say."
+
+Common phrasings: "Spotify followers," "monthly listeners," "TikTok trends," "Instagram audience," "playlist pitching," "competitive analysis," "how is [artist] doing," "research [artist]," "find me [people]."
+
+## What it produces
+
+A structured research output answering the user's question — usually a synthesis across multiple `/research/*` calls (e.g. profile + metrics + audience + similar artists), formatted for either the agent's continued reasoning or direct delivery to the user.
+
+## Endpoints it uses
+
+All of [Research](/api-reference/research/search) (31 endpoints). The skill's decision tree picks the minimal set per query.
+
+## Source
+
+[`recoupable/skills/skills/music-industry-research`](https://github.com/recoupable/skills/tree/main/skills/music-industry-research)

skills/release-management.mdx

@@ -0,0 +1,27 @@
+---
+title: "release-management"
+description: "Plan a release end to end — RELEASE.md documents, DSP pitches, press one-sheets, production specs, tour coordination."
+---
+
+A release campaign — album, EP, single, project — managed via a single `RELEASE.md` document inside the artist workspace. The skill creates, updates, and pulls data from these documents, and generates the deliverables a real release needs (DSP pitches, press one-sheets, production specs, tour coordination notes).
+
+## When to use it
+
+User mentions an artist's album, EP, single, or project, or asks about release planning, DSP pitches, metadata, marketing, press materials, physical production, or tour coordination. The skill first infers which artist and release the user means, then finds or creates the corresponding `RELEASE.md`.
+
+## What it produces
+
+A `RELEASE.md` at `orgs/{org}/artists/{artist-slug}/releases/{release-slug}/` that holds the canonical release plan, plus any of the standard deliverables — DSP one-pager, press release, production spec, tour brief — generated from it.
+
+## Endpoints it uses
+
+- [`POST /api/songs`](/api-reference/songs/create)
+- [`GET /api/songs`](/api-reference/songs/songs)
+- [`GET /api/research/playlists`](/api-reference/research/playlists)
+- [`GET /api/research/curator`](/api-reference/research/curator)
+- [`GET /api/research/festivals`](/api-reference/research/festivals)
+- [`GET /api/research/venues`](/api-reference/research/venues)
+
+## Source
+
+[`recoupable/skills/skills/release-management`](https://github.com/recoupable/skills/tree/main/skills/release-management)

skills/setup-sandbox.mdx

@@ -0,0 +1,24 @@
+---
+title: "setup-sandbox"
+description: "Scaffold the workspace for an account's orgs and artists when a sandbox has no existing file system."
+---
+
+The first run inside a fresh sandbox. Fetches the account's organizations and artists, then creates the directory layout the rest of the skills assume.
+
+## When to use it
+
+A sandbox has just been created and has no existing file system. If the sandbox already has an `orgs/` directory at the root, this skill is a no-op — skip it.
+
+## What it produces
+
+A scaffolded `orgs/{org}/artists/{artist-slug}/` folder tree mirroring the account's actual roster, plus the root `RECOUP.md` files that downstream skills (`artist-workspace`, `release-management`) read to orient themselves.
+
+## Endpoints it uses
+
+- [`GET /api/accounts`](/api-reference/accounts/get)
+- [`GET /api/organizations`](/api-reference/organizations/list)
+- [`GET /api/artists`](/api-reference/artists/list)
+
+## Source
+
+[`recoupable/skills/skills/setup-sandbox`](https://github.com/recoupable/skills/tree/main/skills/setup-sandbox)

skills/song-writing.mdx

@@ -0,0 +1,22 @@
+---
+title: "song-writing"
+description: "Write and evaluate songs using the 7 C's framework — hook, clarity, character, and the rest."
+---
+
+A structured framework for writing and evaluating song lyrics and concepts. The 7 C's check whether a song is memorable, clear, and authentic before it ships.
+
+## When to use it
+
+Brainstorming song ideas, writing lyrics, evaluating song drafts, refining hooks, or improving existing songs. Use it both as a generation guide and as a critique tool when reviewing a draft.
+
+## What it produces
+
+A song or lyric set scored against the 7 C's, with specific revision suggestions for whichever C's are weak. Output is usually written to the artist's `songs/` directory.
+
+## Endpoints it uses
+
+None. Pure methodology — the agent's LLM does the work.
+
+## Source
+
+[`recoupable/skills/skills/song-writing`](https://github.com/recoupable/skills/tree/main/skills/song-writing)

skills/streaming-growth.mdx

@@ -0,0 +1,25 @@
+---
+title: "streaming-growth"
+description: "Grow a new artist past the streaming milestones that unlock Spotify Showcase, Marquee, and algorithmic boosting."
+---
+
+A playbook for getting an early-stage artist past the listener thresholds that unlock platform tools — once you're past them, growth compounds. Includes real cost benchmarks (playlist push pricing, ad CPCs, click-to-listen rates) and a decision framework for which path to invest in.
+
+## When to use it
+
+User asks about getting more streams, unlocking Spotify Showcase or Marquee, increasing Spotify Popularity score, playlist pitching, DSP advertising, or growing an artist from near-zero. Triggers: "how do we get more streams," "unlock Spotify ads," "playlist push," "get to a thousand listeners," "artist growth strategy," "Spotify Popularity score."
+
+## What it produces
+
+A growth plan tailored to the artist's current monthly listeners, with a recommended path (playlist pitching vs. paid ads vs. organic) and concrete benchmarks for cost, conversion, and time to threshold.
+
+## Endpoints it uses
+
+- [`GET /api/research/metrics`](/api-reference/research/metrics)
+- [`GET /api/research/audience`](/api-reference/research/audience)
+- [`GET /api/research/playlists`](/api-reference/research/playlists)
+- [`GET /api/research/similar`](/api-reference/research/similar)
+
+## Source
+
+[`recoupable/skills/skills/streaming-growth`](https://github.com/recoupable/skills/tree/main/skills/streaming-growth)

skills/trend-to-song.mdx

@@ -0,0 +1,25 @@
+---
+title: "trend-to-song"
+description: "Reverse the traditional workflow — start from a cultural moment and build a song + distribution plan around it."
+---
+
+Flips the usual music workflow. Instead of song-first, then marketing — you start from a trend, viral moment, or cultural event and reverse-engineer a song and distribution strategy that lands inside that moment's window.
+
+## When to use it
+
+Someone identifies a trending topic, viral moment, reality TV drama, meme, or cultural event and wants to turn it into a song with a campaign. Triggers: "make a song about this trend," "capitalize on this moment," "reverse engineer from the market," "cultural moment to song," "trend-jack," "burner page strategy."
+
+## What it produces
+
+A trend brief (what the moment is, why it's resonating, who's reacting), a song concept that fits inside it, and a distribution plan — usually involving burner pages, paid promotion, and a tight shipping window before the moment fades.
+
+## Endpoints it uses
+
+- [`POST /api/research/web`](/api-reference/research/web)
+- [`GET /api/research/audience`](/api-reference/research/audience)
+- [`POST /api/content/image`](/api-reference/content/generate-image)
+- [`POST /api/content/video`](/api-reference/content/generate-video)
+
+## Source
+
+[`recoupable/skills/skills/trend-to-song`](https://github.com/recoupable/skills/tree/main/skills/trend-to-song)