Setup Sandbox
Bootstrap a fresh Recoup sandbox workspace with org and artist folders pulled from the Recoup CLI so an agent can work on royalty workflows without manual directory setup.
Overview
Setup Sandbox is an agent skill for the Build phase that scaffolds org and artist directories from Recoup CLI JSON and seeds RECOUP.md markers in a new sandbox.
Install
npx skills add https://github.com/recoupable/setup-sandbox --skill setup-sandboxWhat is this skill?
- Skips automatically when orgs/ already exists so reruns do not clobber an initialized sandbox
- Lists organizations and per-org artists via recoup orgs list and recoup artists list with --json
- Uses artistSlug from CLI responses as the exact directory name—no UUID or ID suffixes
- Writes a RECOUP.md marker from a per-artist template under orgs/{org}/artists/{artist-slug}/
- Ends with git add, commit, and push so the scaffold is versioned
- 5 numbered workflow steps from environment check through git commit and push
Adoption & trust: 1.4k installs on skills.sh; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You spun up a Recoup-connected sandbox but have no orgs/ layout or markers, so agents cannot safely start file-based Recoup work.
Who is it for?
Developers onboarding a brand-new Recoup sandbox who already have the Recoup CLI and API key configured.
Skip if: Sandboxes that already contain an orgs/ directory or anyone who only needs one-off API calls without persisting a repo layout.
When should I use this skill?
A sandbox has just been created with no existing file system and no orgs/ directory; skip if orgs/ already exists.
What do I get? / Deliverables
After the run, orgs/{org}/artists/{artist-slug}/ exists for each fetched artist with RECOUP.md in place and the structure committed to git.
- orgs/{org}/artists/{artist-slug}/ directory tree from live CLI data
- Per-artist RECOUP.md marker files
- Git commit and push of the scaffold
Recommended Skills
Journey fit
First-time environment scaffolding happens when you are wiring product tooling and external services into a build workspace, not during launch or growth campaigns. The skill is entirely about integrating the Recoup CLI and API-backed account data into a reproducible filesystem layout—classic integrations work on the build shelf.
How it compares
Use this structured bootstrap instead of manually creating folders from dashboard screenshots or stale spreadsheets.
Common Questions / FAQ
Who is setup-sandbox for?
Solo and indie builders (and small teams) who automate Recoup workflows in git-backed sandboxes and want the correct org/artist tree before deeper agent tasks.
When should I use setup-sandbox?
Right after a new sandbox is created with no orgs/ folder—during Build integrations setup—before tasks that read or write per-artist paths under orgs/.
Is setup-sandbox safe to install?
It runs shell, git, and network calls against your Recoup account; review the Security Audits panel on this Prism page and treat API keys and RECOUP_ACCOUNT_ID as secrets.
SKILL.md
READMESKILL.md - Setup Sandbox
# Setup Sandbox Create the folder structure for the connected account's organizations and artists. ## Environment - `RECOUP_ACCOUNT_ID` — The account ID to fetch data for. Only needed when using an Org API Key. When using a Personal API Key, omit the `--account` flag and the CLI will use the authenticated account automatically. ## Steps 1. Check if `RECOUP_ACCOUNT_ID` is set. If set, use `--account $RECOUP_ACCOUNT_ID` on all CLI commands below. If not set, omit the `--account` flag. 2. Run `recoup orgs list --json [--account $RECOUP_ACCOUNT_ID]` to get all organizations 3. For each organization, run `recoup artists list --org {organization_id} --json [--account $RECOUP_ACCOUNT_ID]` to get its artists 4. Create the folder structure and a `RECOUP.md` marker in each artist folder: - Use `artistSlug` from the CLI response as the exact directory name — never append UUIDs, IDs, or suffixes - If `orgs/{org}/artists/{artist-slug}/` already exists, skip it - `mkdir -p orgs/{org}/artists/{artist-slug}` for each new artist - Write a `RECOUP.md` using the template below 5. Commit and push: - `git add -A && git commit -m "setup: create org and artist folders" && git push origin main` ## `RECOUP.md` Every artist directory has a `RECOUP.md` at its root. This is the **identity file** — it connects the workspace to the Recoupable platform. The existence of this file means the workspace is active. Fill it with data from the CLI response: ```markdown --- artistName: {Artist Name} artistSlug: {artist-slug} artistId: {uuid-from-recoupable} --- ``` **Fields:** - `artistName` — display name from the CLI (e.g. `Gatsby Grace`) - `artistSlug` — lowercase-kebab-case folder name (e.g. `gatsby-grace`) - `artistId` — the UUID from Recoup