Skip to content

docs: fix skill naming and refresh getting-started #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
recoupableorg wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: fix skill naming and refresh getting-started #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
73a7ac3
docs: fix skill naming and refresh getting-started
sidneyswift Apr 18, 2026
2ed072e
docs: clarify agent+ signup creates a separate account
sidneyswift Apr 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,12 @@ git clone https://github.com/recoupable/skills.git
| [getting-started](skills/getting-started) | Install CLI, get API key, connect via MCP/REST — start here |
| [artist-workspace](skills/artist-workspace) | Manage artist directories — context, songs, brand, audience |
| [streaming-growth](skills/streaming-growth) | Grow a new artist past streaming milestones that unlock platform tools |
| [brand-guidelines](skills/brand-guidelines) | Apply Recoupable's brand identity to agent outputs |
| [chartmetric](skills/chartmetric) | Query and analyze music data from the Chartmetric API |
| [chart-metric](skills/chart-metric) | Query and analyze music data from the Chartmetric API |
| [content-creation](skills/content-creation) | Create social videos, TikToks, Reels, and visual content using AI primitives |
| [music-industry-research](skills/music-industry-research) | Music industry research — artist analytics, people search, competitive analysis, web intelligence |
| [release-management](skills/release-management) | Plan and execute release campaigns |
| [setup-sandbox](skills/setup-sandbox) | Scaffold the workspace for an account's orgs and artists |
| [songwriting](skills/songwriting) | Structured songwriting using the 7 C's method |
| [song-writing](skills/song-writing) | Structured songwriting using the 7 C's method |
| [trend-to-song](skills/trend-to-song) | Turn cultural moments into songs and campaign strategies |

## Creating a Skill
Expand Down
103 changes: 69 additions & 34 deletions skills/getting-started/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,35 @@
---
name: getting-started
description: Set up Recoupable from scratch — install the CLI, get an API key, and make your first call. Use this skill when the user says "set up Recoupable", "install Recoup", "get an API key", "connect to Recoup", "use Recoupable", "onboard to Recoup", "how do I start", or when an agent needs to configure itself to use the Recoupable platform.
description: Set up Recoupable from scratch — get an API key, verify it, and make your first call via REST or MCP. Use this skill when the user says "set up Recoupable", "install Recoup", "get an API key", "connect to Recoup", "use Recoupable", "onboard to Recoup", "how do I start", or when an agent needs to configure itself to use the Recoupable platform.
---

# Getting Started with Recoupable

From zero to your first API call in under 2 minutes. Three steps: install, authenticate, use.
From zero to your first API call in under 2 minutes. Two steps: authenticate, call. No install needed — everything is HTTP.

## Step 1 — Install the CLI
- **Base URL:** `https://recoup-api.vercel.app/api`
- **MCP URL:** `https://recoup-api.vercel.app/mcp`
- **Auth header (REST):** `x-api-key: YOUR_RECOUP_API_KEY`
- **Auth header (MCP):** `Authorization: Bearer YOUR_RECOUP_API_KEY`
- **Full docs:** <https://developers.recoupable.com>

```bash
npm install -g @recoupable/cli
```

Requires Node.js 18+. The CLI wraps the REST API with convenient commands.

## Step 2 — Get an API key
## Step 1 — Get an API key

Two paths depending on who is doing this.

### Path A: Agent (instant, no verification)

POST to the signup endpoint with an `agent+` email. Key comes back immediately.
POST to the signup endpoint with a fresh `agent+` email. The key comes back immediately and is exported for the rest of the session.

```bash
export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
-d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
```

The `agent+{unique}@recoupable.com` pattern always returns a key with no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees unique addresses.
A new `agent+{unique}@recoupable.com` address skips email verification and returns a key on the first call. Combining `$(date +%s)` with `$RANDOM` guarantees uniqueness so you never collide with an existing account.

@cubic-dev-ai cubic-dev-ai Bot Apr 18, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This documentation claims $(date +%s) + $RANDOM “guarantees uniqueness,” but that combination only reduces collision risk and does not guarantee it.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/getting-started/SKILL.md, line 30:

<comment>This documentation claims `$(date +%s)` + `$RANDOM` “guarantees uniqueness,” but that combination only reduces collision risk and does not guarantee it.</comment>

<file context>
@@ -19,15 +19,17 @@ Two paths depending on who is doing this.

-The agent+{unique}@recoupable.com pattern always returns a key with no verification step. Combining $(date +%s) with $RANDOM guarantees a unique address.
+A new agent+{unique}@recoupable.com address skips email verification and returns a key on the first call. Combining $(date +%s) with $RANDOM guarantees uniqueness so you never collide with an existing account.
+
+> ⚠️ agent+ emails create a separate account. agent+sid@recoupable.com is not linked to sid@recoupable.com — it's a brand-new sandboxed account with no roster, no orgs, and no history. To work on behalf of an existing human, use Path B with their real email.
</file context>


</details>

```suggestion
A new `agent+{unique}@recoupable.com` address skips email verification and returns a key on the first call. Combining `$(date +%s)` with `$RANDOM` makes collisions unlikely in practice.
Fix with Cubic


> ⚠️ **`agent+` emails create a separate account.** `agent+sid@recoupable.com` is **not** linked to `sid@recoupable.com` — it's a brand-new sandboxed account with no roster, no orgs, and no history. To work on behalf of an existing human, use **Path B** with their real email.

### Path B: Human (email verification)

Expand All @@ -41,7 +41,7 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-d '{"email": "user@example.com"}'
```

This sends a verification code to their email. Ask the user for the code, then:
This sends a verification code to the user's email. Ask the user for the code, then:

```bash
curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \
Expand All @@ -51,39 +51,55 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \

The response contains the `api_key`.

### Path C: Dashboard (humans only, optional)

Prefer clicking over scripting? Create a key at [chat.recoupable.com/keys](https://chat.recoupable.com/keys).

1. Sign in
2. Enter a descriptive name (e.g. "Production Server")
3. Click **Create API Key** and copy it immediately — it's only shown once.

### Save the key

Add to shell profile so it persists:
Add it to the shell profile so it survives new sessions:

```bash
echo 'export RECOUP_API_KEY="recoup_sk_..."' >> ~/.zshrc
source ~/.zshrc
```

## Step 3 — Verify it works
## Step 2 — Verify it works

Hit the "whoami" endpoint. It echoes the account ID the key belongs to:

```bash
recoup whoami
curl -s "https://recoup-api.vercel.app/api/accounts/id" \
-H "x-api-key: $RECOUP_API_KEY"
```

Should print your account ID and email. If it does, you're ready.
A `200` with an `accountId` in the body means you're ready. `401` means the key is missing or wrong.

## First useful command
## First useful call — research any artist

Research any artist:
Research runs entirely over REST. Everything sits under `/api/research/*`.

```bash
recoup research "Drake"
curl -s "https://recoup-api.vercel.app/api/research?q=Drake&type=artists&beta=true" \
-H "x-api-key: $RECOUP_API_KEY" | jq
```

Returns structured data: streaming metrics, audience demographics, social traction, career history — pulled from 14 platforms.
That returns ranked matches with Chartmetric IDs. To get a full profile:

## Connect via MCP
```bash
curl -s "https://recoup-api.vercel.app/api/research/profile?artist=Drake" \
-H "x-api-key: $RECOUP_API_KEY" | jq
```

For the full research surface — metrics, audience, cities, similar artists, playlists, charts, people search, deep research, URL extraction, structured enrichment — use the `music-industry-research` skill.

For AI tools that support MCP (Claude, Cursor, etc.):
## Connect via MCP

- **URL:** `https://recoup-api.vercel.app/mcp`
- **Auth:** Bearer token — use your API key as the token
For AI tools that speak MCP (Claude, Cursor, etc.), point them at the Recoup MCP server and pass the API key as a Bearer token:

```json
{
Expand All @@ -98,30 +114,49 @@ For AI tools that support MCP (Claude, Cursor, etc.):
}
```

This gives your AI tool access to 40+ music intelligence tools.
This gives the tool access to Recoup's MCP tools — sandbox execution, research, and more. See the [MCP docs](https://developers.recoupable.com/mcp) for the current tool list and schemas.

## Connect via REST API

Base URL: `https://recoup-api.vercel.app/api`

Auth header: `x-api-key: YOUR_RECOUP_API_KEY`
Every endpoint follows the same pattern: `https://recoup-api.vercel.app/api/<resource>` with `x-api-key` for auth. A minimal REST client in any language:

```bash
curl "https://recoup-api.vercel.app/api/research?q=Drake" \
curl -s "https://recoup-api.vercel.app/api/tasks" \
-H "x-api-key: $RECOUP_API_KEY"
```

Full API reference: https://developers.recoupable.com
```python
import os, requests
headers = {"x-api-key": os.environ["RECOUP_API_KEY"]}
r = requests.get("https://recoup-api.vercel.app/api/tasks", headers=headers)
print(r.json())
```

```javascript
const r = await fetch("https://recoup-api.vercel.app/api/tasks", {
headers: { "x-api-key": process.env.RECOUP_API_KEY },
});
console.log(await r.json());
```

Full reference (all resources, request/response shapes, auth rules): <https://developers.recoupable.com>

## Auth gotchas

- Use `x-api-key` for server-to-server, or `Authorization: Bearer <privy_jwt>` for frontend sessions via Privy. **Never both in the same request** — the API returns `401`.
- API keys are personal by default. If your account is in an organization, you can pass `account_id` on supported endpoints to access other accounts in that org.
- Keys are hashed (HMAC-SHA256) on save — if you lose the key, you rotate it, not recover it. Rotate at [chat.recoupable.com/keys](https://chat.recoupable.com/keys).

## What's next

After setup, use these skills for specific workflows:

| Skill | What it does |
|-------|-------------|
| ----- | ------------ |
| music-industry-research | Deep artist analytics, people search, charts, competitive analysis, web intelligence |
| content-creation | Generate videos, images, captions from artist catalogs |
| industry-research | Deep artist analytics, people search, competitive analysis |
| release-management | Plan and execute release campaigns |
| setup-sandbox | Scaffold workspace for an account's orgs and artists |
| setup-sandbox | Scaffold the workspace for an account's orgs and artists |
| streaming-growth | Grow artists past streaming milestones |
| songwriting | Structured songwriting using the 7 C's method |
| artist-workspace | Manage artist directories — context, songs, brand, audience |
Comment on lines +155 to +162

@coderabbitai coderabbitai Bot Apr 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use the canonical skill name consistently in “What’s next.”

Line 161 still says songwriting, while the repo/docs now use song-writing. Please align this entry to avoid confusion when users map names to folders/skills.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/getting-started/SKILL.md` around lines 155 - 162, Update the "What's
next." table entry that currently reads "songwriting" to use the canonical skill
name "song-writing" so it matches the repo/docs naming; locate the table rows
(entries like music-industry-research, content-creation, release-management,
setup-sandbox, streaming-growth, songwriting, artist-workspace) in SKILL.md and
replace the "songwriting" identifier with "song-writing" to ensure folder/skill
name mapping is consistent.