feat(marketplace): add unified marketplace machinery (2/3)

.agents/plugins/marketplace.json

@@ -0,0 +1,51 @@
+{
+  "name": "recoup",
+  "description": "Recoup's marketplace of AI agent skills and plugins for the music industry.",
+  "owner": {
+    "name": "Recoup",
+    "email": "agent@recoupable.com",
+    "url": "https://recoupable.com"
+  },
+  "interface": {
+    "displayName": "Recoup"
+  },
+  "plugins": [
+    {
+      "name": "recoup-skills",
+      "description": "Music-industry skills for AI agents — artist management, songwriting, analytics, release campaigns, research, content creation.",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Music",
+      "keywords": [
+        "music",
+        "artist-management",
+        "songwriting",
+        "music-marketing",
+        "analytics",
+        "release-management",
+        "chartmetric",
+        "content-creation",
+        "agent-skills"
+      ],
+      "interface": {
+        "displayName": "Recoup Skills",
+        "shortDescription": "Music industry skills for AI agents",
+        "longDescription": "Teach your coding agent how to manage artists, write songs, analyze music analytics, plan releases, and create content. General skills work for anyone; platform skills integrate with the Recoup platform.",
+        "developerName": "Recoup",
+        "category": "Music",
+        "capabilities": [
+          "Read",
+          "Write"
+        ],
+        "websiteURL": "https://recoupable.com",
+        "brandColor": "#345A5D"
+      }
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -0,0 +1,47 @@
+{
+  "name": "recoup",
+  "owner": {
+    "name": "Recoup",
+    "email": "agent@recoupable.com",
+    "url": "https://recoupable.com"
+  },
+  "metadata": {
+    "description": "Recoup's marketplace of AI agent skills and plugins for the music industry.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "recoup-skills",
+      "description": "Music-industry skills for AI agents — artist management, songwriting, analytics, release campaigns, research, content creation.",
+      "version": "1.0.0",
+      "source": "./",
+      "category": "Music",
+      "keywords": [
+        "music",
+        "artist-management",
+        "songwriting",
+        "music-marketing",
+        "analytics",
+        "release-management",
+        "chartmetric",
+        "content-creation",
+        "agent-skills"
+      ],
+      "strict": false,
+      "skills": [
+        "./skills/artist-workspace",
+        "./skills/chart-metric",
+        "./skills/content-creation",
+        "./skills/create-artist",
+        "./skills/getting-started",
+        "./skills/music-industry-research",
+        "./skills/recoup-api",
+        "./skills/release-management",
+        "./skills/setup-sandbox",
+        "./skills/song-writing",
+        "./skills/streaming-growth",
+        "./skills/trend-to-song"
+      ]
+    }
+  ]
+}

.cursor-plugin/marketplace.json

@@ -0,0 +1,37 @@
+{
+  "name": "recoup",
+  "owner": {
+    "name": "Recoup",
+    "email": "agent@recoupable.com"
+  },
+  "metadata": {
+    "description": "Recoup's marketplace of AI agent skills and plugins for the music industry."
+  },
+  "plugins": [
+    {
+      "name": "recoup-skills",
+      "source": ".",
+      "description": "Music-industry skills for AI agents — artist management, songwriting, analytics, release campaigns, research, content creation.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Recoup",
+        "email": "agent@recoupable.com"
+      },
+      "homepage": "https://recoupable.com",
+      "repository": "https://github.com/recoupable/skills",
+      "license": "Apache-2.0",
+      "category": "Music",
+      "keywords": [
+        "music",
+        "artist-management",
+        "songwriting",
+        "music-marketing",
+        "analytics",
+        "release-management",
+        "chartmetric",
+        "content-creation",
+        "agent-skills"
+      ]
+    }
+  ]
+}

.github/workflows/validate.yml

@@ -0,0 +1,22 @@
+name: validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate-manifests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Check marketplace files are in sync with source
+        run: python3 scripts/generate-marketplaces.py --check
+
+      - name: Validate all manifests + skills
+        run: python3 scripts/validate-manifests.py

AGENTS.md

@@ -1,70 +1,85 @@
-# Agent Instructions — Recoupable Skills
+# Agent Instructions — Recoup Skills Marketplace
 
-This file provides context for any AI agent operating within this repository.
+Context for any AI agent operating within this repository.
 
 ## Repository Purpose
 
-Public skills for AI agents working in the music industry. Skills teach agents how to complete specific tasks — from songwriting to analytics to release campaigns.
+Recoup's unified marketplace of agent skills and plugins for the music industry. It is simultaneously a **skill collection** (broad skills under `skills/`), a **plugin marketplace** (manifests at the repo root), and a **plugin host** (self-contained plugins under `plugins/`).
+
+Supported agents: **Claude Code**, **OpenAI Codex**, **Cursor**.
 
 ## Structure
 
 ```text
 recoupable/skills/
-├── .claude-plugin/           ← plugin manifest for Claude Code
-├── .codex-plugin/            ← plugin manifest for OpenAI Codex
-├── skills/                   ← all skills live here
-│   ├── chart-metric/
-│   ├── content-creation/
-│   ├── music-industry-research/
-│   ├── song-writing/
-│   └── ...
-├── README.md
-├── contributing.md
-└── AGENTS.md                 ← this file
+├── .claude-plugin/marketplace.json       ← Claude Code marketplace (generated)
+├── .agents/plugins/marketplace.json      ← Codex marketplace (generated)
+├── .cursor-plugin/marketplace.json       ← Cursor marketplace (generated)
+│
+├── marketplace.source.json               ← SINGLE SOURCE OF TRUTH — edit this
+│
+├── skills/                               ← Broad music skills
+│   └── {skill-name}/
+│       ├── SKILL.md          ← required — instructions + YAML frontmatter
+│       ├── references/       ← optional — docs loaded on-demand
+│       ├── scripts/          ← optional — executable code
+│       └── assets/           ← optional — templates, fonts, icons
+│
+├── plugins/                              ← Self-contained vertical plugins
+│   └── {plugin-name}/
+│       ├── .claude-plugin/plugin.json
+│       ├── .codex-plugin/plugin.json
+│       ├── .cursor-plugin/plugin.json
+│       ├── skills/
+│       ├── agents/
+│       ├── commands/
+│       ├── scripts/
+│       ├── templates/
+│       └── references/
+│
+└── scripts/
+    ├── generate-marketplaces.py          ← Regenerate platform marketplace JSONs
+    └── validate-manifests.py             ← Validate every manifest + skill
 ```
 
-## How Skills Load
-
-Skills use progressive disclosure:
-
-1. **Frontmatter** (`name` + `description`) — always in context. This is how you decide whether to load a skill.
-2. **SKILL.md body** — loaded when you determine the skill is relevant.
-3. **Linked files** (`references/`, `scripts/`, `assets/`) — loaded on-demand as needed.
-
-The `description` field is the trigger. If it's vague, the skill won't activate.
+A new vertical plugin earns its own folder under `plugins/` when it has **at least 3 related skills** AND needs commands, agents, scripts, templates, or MCP integrations.
 
 ## Rules
 
 1. **Read before you act.** Always read a skill's `SKILL.md` before executing or referencing it.
-2. **Respect boundaries.** Each skill is self-contained. No cross-dependencies between skills.
+2. **Respect boundaries.** Skills are self-contained. No cross-dependencies between skills.
 3. **Design for composability.** Multiple skills may be loaded at once. Never assume yours is the only one active.
 4. **Keep it simple.** Prefer the simplest working solution.
 5. **One skill, one job.** Each skill does one thing well.
-6. **No secrets in skills.** Reference environment variables — never hardcode credentials.
+6. **Description is the trigger.** Vague descriptions don't activate the skill — include trigger phrases users would say.
+7. **No secrets in skills.** Reference environment variables — never hardcode credentials.
+8. **`marketplace.source.json` is the source of truth.** Never hand-edit the three generated marketplace files. Edit the source and run `python3 scripts/generate-marketplaces.py`.
 
 ## Skill Format
 
-Every skill directory must contain a `SKILL.md`:
-
-```text
-my-skill/
-├── SKILL.md          ← required — instructions + YAML frontmatter
-├── references/       ← optional — docs loaded on-demand
-├── scripts/          ← optional — executable code
-└── assets/           ← optional — templates, fonts, icons
-```
-
-### Frontmatter
+Every skill directory must contain a `SKILL.md` with YAML frontmatter:
 
 ```yaml
 ---
 name: skill-name
-description: What it does and when to use it
+description: What it does and when to use it. Include trigger phrases.
 ---
 ```
 
-### Writing the description
+## Validation
+
+Before committing changes:
+
+```bash
+python3 scripts/validate-manifests.py
+```
+
+Checks performed:
+
+1. Generated marketplace files match `marketplace.source.json`.
+2. Every plugin's `source` path exists and is a directory.
+3. Every skill listed in a virtual plugin is a directory with valid `SKILL.md` frontmatter.
+4. Every plugin folder under `plugins/` has `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and `.cursor-plugin/plugin.json`.
+5. Every `SKILL.md` has `name` and `description` frontmatter.
 
-- Start with **what** the skill does
-- Include **when** to use it — mention trigger phrases users would say
-- Be specific — vague descriptions won't trigger
+Validation runs on every PR via CI.