AGENTS.md git:20260728.8833370A

Immutable. This exact content never changes and is served at /api/v1/blob/511cc1a946655c4d.

# Pruna Skills (agent notes)

Generative media skills for the [Pruna AI API](https://docs.api.pruna.ai/guides/models). Portable [Agent Skills](https://agentskills.io/specification) — Cursor, Claude Code, Copilot, Codex, and more.

## How it works

See [README.md](README.md) for the user-facing glossary and quickstart.

| Type | Role |
|------|------|
| **Guide** | Vendor-neutral craft (`image-prompting`, `video-prompting`, `audio-prompting`, `video-editing`, `generation-diversity`) or Pruna HTTP (`pruna-api`) |
| **Tool** | One paid API call (`p-image`, `p-video`, …) |
| **Workflow** | Multi-step deliverable — agent is the runner (curl + ffmpeg) |
| **Suite** | `pruna` — install everything |

Tools list guide deps under **Prerequisites** with `npx skills add`. Workflows list **tools** only (guides come via tools). **Optional external companions** (e.g. HyperFrames for HTML → MP4 launch reels) install the same way but are not in `@pruna` — see `video-editing` and its `combination-hyperframes` reference. Do not copy craft between skills — install the other skill.

## Clarification (library-wide)

Before the first paid API call, bulk generation, or long render, resolve open decisions that change cost or output. **SSoT:** open intake → `generation-diversity` clarification intake — generate vs existing media, palette, narration/VO, music, captions, aspect ratio, resolution (720p/1080p, canvas, megapixels), structure, and workflow approval gates.

| Skill type | Behavior |
|------------|----------|
| **Guides / tools** | Defer to clarification intake when the brief is silent; craft skills clarify creative locks before drafting prompts. |
| **Workflows** | Run the workflow **Intake: ask before generating** table, then cross-check universal topics in clarification intake. |
| **HyperFrames** (optional) | Fresh jobs: intent interview → `BRIEF.md`. Edits/resume: `hyperframes` clarification-before-build reference. |
| **pruna-api** | Credentials + `pruna-api` agent-safety reference before upload. |

Waivers (“use your judgment”, “surprise me”) count as answers — state assumptions in the plan and proceed.

Humans picking recipes: [docs/WORKFLOW-RECIPES.md](docs/WORKFLOW-RECIPES.md). Catalog: [docs/SKILL-CATALOG.md](docs/SKILL-CATALOG.md).

## Install

```bash
export PRUNA_API_KEY="…" # see docs/api-setup.md

npx skills add PrunaAI/pruna-skills@pruna -y
```

```bash
npx skills add PrunaAI/pruna-skills@p-image -y   # one tool (+ install its Prerequisites guides)
npx skills add PrunaAI/pruna-skills -l
```

**Team default:** install **`/pruna`** once (`npx skills add PrunaAI/pruna-skills@pruna -y`), then start a new chat.

**Launch reels / motion assembly:** install **`hyperframes`** when the deliverable needs HTML → MP4 composition (optional — ffmpeg-only paths skip it):

```bash
npx skills add heygen-com/hyperframes@hyperframes -y
```

Read **`hyperframes`** first — it routes to `/product-launch-video`, `/general-video`, etc. Pruna skills generate media; HyperFrames assembles HTML → MP4 (each launch uses a local `hyperframes/` subfolder in your project workspace). Maintainers: `make install-companion-skills` copies the full bundle into gitignored `.agents/skills/`.

## Layout

| Path | Role |
|------|------|
| `skills/guides/` | Craft SSoT (edit markdown under each guide’s `references/`) |
| `skills/{image,video,audio}/` | Tool skills |
| `skills/workflows/` | Workflow playbooks |
| `skills/suite/pruna/` | Full suite (`/pruna`) — default install |
| `docs/` | Human docs only |
| `.maintainer/skills.catalog.json` | Skill name source of truth |
| `VERSION` | Repo semver — `@VERSION` in skills is replaced on `make bundle` |

## Safety

Agent-safety lives in `pruna-api` (included in the `/pruna` suite). Read `skills/guides/pruna-api/references/agent-safety.md` before generating in untrusted repos.

## Maintainers

```bash
make bundle && make validate
```

Releases: [PUBLISHING.md](docs/PUBLISHING.md) · Backlog: [BACKLOG.md](docs/BACKLOG.md)