Metadata-Version: 2.5
Name: supercmo-skills
Version: 0.1.8
Summary: SuperCMO media client (image, video, audio): stdlib-only routing over BYO-direct vendor keys or one managed SuperCMO key.
Project-URL: Homepage, https://github.com/SupercmoHQ/superCMO-skills
Project-URL: Repository, https://github.com/SupercmoHQ/superCMO-skills
Project-URL: Issues, https://github.com/SupercmoHQ/superCMO-skills/issues
Author-email: Kshitiz Kumar <founder@getsupercmo.ai>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,byo-keys,image-generation,marketing,media,tts,video-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown

<div align="center">

<img src="assets/logo.png" alt="SuperCMO" width="120" />

# SuperCMO Skills

</div>

### Creative production skills for AI agents

<!-- mcp-name: io.github.SupercmoHQ/supercmo -->

A collection of AI agent skills to research, plan, create, and ship full creative campaigns.

Describe what you want to make - like a UGC video, a product launch campaign, or a week of content. It plans the work, picks the best AI image/video/audio models, edits and delivers the finished, campaign-ready assets.

*The open-source alternative to closed AI marketing agents.*

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/SupercmoHQ/superCMO-skills/validate.yml?branch=main&label=CI)](https://github.com/SupercmoHQ/superCMO-skills/actions)

### Why SuperCMO Skills?

| | |
| --- | --- |
| **No tool hopping** | Making one video ad today means jumping between tools: script in one, images in another, voice in a third, video in a fourth, then stitching it in an editor. SuperCMO does it all from one brief. And it's not a black box — you can review, edit, or change direction at any step. |
| **Pay per use, no subscription** | Most marketing tools charge a monthly fee whether you use them or not. SuperCMO doesn't — you pay only for what you generate. Bring your own vendor keys (free), or generate on SuperCMO's keys and pay per use. No lock-in. |
| **The right model, picked for you** | Every AI image/video model works differently and needs different prompting. SuperCMO's skills already know which model fits each job and how to prompt it. You write the brief; it handles the rest. |
| **Editing included** | It doesn't just hand back a raw 10-second clip. It generates the media, splits long clips, trims footage, adds voiceover, and stitches everything into a finished asset. |
| **Runs where you already work** | It runs inside the agents you already use. Your keys and files stay on your machine. It works inside Claude Code, Cursor, OpenAI Codex, Hermes, Openclaw, or any agent that supports the Agent Skills spec. |

---

## Quick start

**Paste this to your coding agent** (Claude Code, Cursor, Codex, …):

```
Run `npx --yes github:SupercmoHQ/superCMO-skills --all`. Tell me whether it succeeded, then follow the next steps it prints to set up a key.
```

Prefer to run it yourself:

```bash
npx --yes github:SupercmoHQ/superCMO-skills --all   # every detected host
```

Prefer a preview before spending? Every generation supports `dry_run` — the exact request and cost, no API call.

## How the skills work together

You act as the creative director, and your agent uses SuperCMO skills to orchestrate the entire production pipeline.

Here is an example of how the skills chain together behind the scenes to execute a complex brief like: *"Make a 1-minute video ad for this product [URL] with a voiceover."*

```text
[Brief] "Make a 1-minute video ad for this product [URL] with a voiceover."
   │
   ├── 1. Analyze ──> Scrapes the URL to understand the product and fetch product images.
   │
   ├── 2. Plan    ──> Breaks the 60s brief into four 15-second shots.
   │                  Writes the script and shot list.
   │
   ├── 3. Image  ──> Generates master reference images of the product 
   │                 using the best image models.
   │
   ├── 4. Video  ──> Generates the 4 video clips. Locks the anchor reference 
   │                  into every shot so the product doesn't shape-shift.
   │
   ├── 5. Audio   ──> Adds a voiceover, budgeting the script to match the 
   │                  exact length of the video.
   │
   └── 6. Stitch  ──> Stitches the finished clips together to create one 
                      continuous 1-minute video file.

```

## Skills

These are the discrete capabilities installed into your agent.

<!-- SKILLS:START — auto-generated by scripts/sync_skills.py; do not edit by hand -->
| Skill | Description |
|-------|-------------|
| [analyzing-products](skills/analyzing-products/) | Reads a product URL or raw photo to extract exact visual details, materials, and labels. Grounds every generation in reality to maintain strict product consistency across your campaign. |
| [generating-audio](skills/generating-audio/) | Converts scripts into natural speech. Generates voiceovers, ad reads, and character dialogue, automatically handling pacing and voice selection. |
| [generating-images](skills/generating-images/) | Produces campaign-ready images from a text brief or edits existing photos. Uses reference images to lock in specific styles, characters, or products. |
| [generating-videos](skills/generating-videos/) | Turns text briefs or still images into videos. Generates everything from cinematic b-roll to animated product shots, automatically structuring the complex prompts required by top video models. |
<!-- SKILLS:END -->

## Install

Every host loads the **same skills** + the **same local MCP server** - only the wiring differs.
**Prerequisite:** [`uv`](https://docs.astral.sh/uv/getting-started/installation/) on PATH — the MCP
server runs via `uvx`, which provisions Python and the server for you (nothing to `pip install`). The
root `pyproject.toml` / `package.json` are packaging scaffolding — you don't build anything by hand to
run or contribute to the skills.

**npx installer** - registers the MCP server via each host's own mechanism (`codex`/`claude mcp add` where a CLI exists; a `.cursor/mcp.json` for Cursor) and places the skills. One command does every detected host:

```bash
npx --yes github:SupercmoHQ/superCMO-skills --claude               # Claude Code
npx --yes github:SupercmoHQ/superCMO-skills --cursor --project-dir .  # Cursor (per project)
npx --yes github:SupercmoHQ/superCMO-skills --codex                # Codex
npx --yes github:SupercmoHQ/superCMO-skills --all                  # every detected host
```

**Claude Code plugin** - an alternative to `npx … --claude` (use one, not both): the whole repo installs as one plugin, managed by Claude Code:

```
/plugin marketplace add SupercmoHQ/superCMO-skills
/plugin install supercmo@superCMO-skills
```

**Codex plugin** - an alternative to `npx … --codex` (use one, not both): installs the skills + MCP server as one plugin, managed by Codex:

```bash
codex plugin marketplace add SupercmoHQ/superCMO-skills
codex plugin add supercmo@superCMO-skills
```

**Claude Cowork / Claude desktop** - download `supercmo-plugin.zip` from the
[latest release](https://github.com/SupercmoHQ/superCMO-skills/releases), then
**Settings → Plugins → Upload local plugin**.

**Standalone** - the media skills call the bundled **MCP server**, so install the whole repo (or the
plugin). Copying a single `skills/<name>/` folder gives you the instructions but **not** the
generation tools.

## Set up a key

Generation needs a key. **Two ways — pick one:**

### Option A · Managed — one command

Generate on **SuperCMO's keys, pay per use** — no vendor signups, nothing to paste.

```bash
npx --yes github:SupercmoHQ/superCMO-skills login
```

Opens SuperCMO in your browser to **sign in and authorize this device**; the key is written to
`~/.supercmo/.env` automatically. Buy credits in the web app when you're ready.

### Option B · Bring your own keys — free

Bring your own vendor keys — requests go **directly to the model vendor; nothing routes through SuperCMO**.

**One file, every host.** The installer creates `~/.supercmo/.env`; the MCP server loads your keys from
there on any host (Claude Code, Cursor, Codex, …). Open it, add a key, restart your host:

```bash
# ~/.supercmo/.env
FAL_KEY=your-fal-key       # image + video (start here) — https://fal.ai
ELEVENLABS_API_KEY=        # voiceover (optional)        — https://elevenlabs.io
GEMINI_API_KEY=            # image/video analysis (opt.) — https://aistudio.google.com
FIRECRAWL_API_KEY=         # url extraction (optional)   — https://firecrawl.dev
```

* **One key to start:** `FAL_KEY` covers image + video. The others are optional — add one when you want
  that capability (voiceover, analysis, extraction).
* **Prefer environment variables?** Exporting the key (or putting it in your host's MCP config `env`
  block) also works and **takes precedence** — `~/.supercmo/.env` is just the reliable default that also
  works for GUI-launched hosts that don't inherit your shell.
* **Check what's set:** ask your agent to run the `setup_status` tool (host-agnostic, no path needed).

## Security & trust

These skills run inside your agent. Exactly what happens:

* **Open source & inspectable.** Every skill, script, and the MCP server lives in this repo under
  Apache-2.0 — read, diff, or pin before you run it.
* **Your keys stay local (BYOK).** With your own vendor keys, they live in `~/.supercmo/.env` (or your
  host's MCP config `env` / your shell); the server reads them from its process environment and requests
  go **directly to the vendor — nothing routes through SuperCMO**. With the **managed** key, requests go
  to SuperCMO's proxy (billed to your credits) — you never hand us a vendor key.
* **The MCP server is local + minimal.** A stdlib-only Python package (`supercmo-skills` on PyPI, source
  in `scripts/supercmo_skills/mcp/`), fetched and run on demand via `uvx supercmo-skills@<version>` — it
  runs on your machine, launched by your host, and starts only when your host enables the plugin.
* **Dry-run everything.** Generation tools support `dry_run` - a free preview of the exact request
  (keys masked), no API call.

Found something off? [Open an issue](https://github.com/SupercmoHQ/superCMO-skills/issues).

## Telemetry

SuperCMO sends **anonymous, opt-out** usage counts from the MCP server so we can see which tools get
used and prioritize. Full details in [`TELEMETRY.md`](TELEMETRY.md).

* **What we send:** the tool name, whether it succeeded, how long it took, versions (OS / Python /
  SuperCMO), and a random install id. Nothing else.
* **What we NEVER send:** your prompts, tool arguments, generated media, file paths, keys, hostname,
  username, or IP address.
* **Turn it off** (any one): `SUPERCMO_TELEMETRY=false`, `DO_NOT_TRACK=1`, or `DISABLE_TELEMETRY=1`.
  It also honors Claude Code's `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`.
* **See what would be sent:** run with `SUPERCMO_TELEMETRY=log` - prints each payload instead of
  sending.
* Events go to our own endpoint (`api.getsupercmo.ai`), never a third-party analytics host. The
  random install id is **never** linked to any account.

## Community

Questions, ideas, or something you built? [Open an issue or discussion](https://github.com/SupercmoHQ/superCMO-skills/issues).

## Contributing

New skills and improvements welcome - see [`CONTRIBUTING.md`](CONTRIBUTING.md). In short:

1. Create `skills/<your-skill>/` (folder name = the `name` in frontmatter), using
   `skills/generating-images/` as the reference layout.
2. Keep `SKILL.md` short; push detail into `references/`, deterministic work into `scripts/`
   (stdlib-only where possible, BYO-keys from env, `--dry-run` on anything that mutates).
3. Validate - CI runs the same on every PR:

```bash
python3 scripts/quick_validate.py       # structural + strict-YAML frontmatter (blocking)
python3 scripts/listing_gate.py         # scripts compile + --dry-run gates (blocking)
python3 scripts/check_shared_client.py  # no raw vendor HTTP - the brokering seam (blocking)
python3 scripts/check_catalog_sync.py   # provider-key catalog single-sourced (blocking)
```

## License

Apache-2.0 - see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

The skill files, scripts, and MCP server in this repository are Apache-2.0. The hosted SuperCMO
product (`getsupercmo.ai`) is a separate service governed by its own terms.

<div align="center">

If SuperCMO saved you time, a ⭐ helps others find it.

Built by [SuperCMO](https://getsupercmo.ai) · [Report an issue](https://github.com/SupercmoHQ/superCMO-skills/issues)

</div>
