# sogni-creative-agent-skill

Agent skill and CLI for Sogni AI image and video generation. Works as a skill
source for Claude Code, OpenClaw, Hermes Agent, Manus AI, and other agent
runtimes.

## Install (pick the integration that matches your environment)

```bash
# Agent-safe CLI install or upgrade
npm install -g @sogni-ai/sogni-creative-agent-skill@latest
sogni-agent --version

# Claude Code plugin (requires the CLI install above; the plugin shells out to sogni-agent).
# Run both slash commands from inside Claude Code:
#   /plugin marketplace add Sogni-AI/sogni-creative-agent-skill
#   /plugin install sogni-creative-agent@sogni

# OpenClaw plugin
openclaw plugins install sogni-creative-agent-skill

# OpenClaw local linked checkout (for continuous updates)
cd /path/to/sogni-creative-agent-skill
npm install
npm link
npm run openclaw:sync
openclaw plugins install -l "$PWD/.openclaw-link"
openclaw gateway restart

# Update OpenClaw local linked checkout
cd /path/to/sogni-creative-agent-skill
git pull --ff-only
npm install
npm link
npm run openclaw:sync
openclaw gateway restart

# Agent-safe existing checkout update
DEST="$HOME/Documents/git/sogni/sogni-creative-agent-skill"
git -C "$DEST" pull --ff-only
npm --prefix "$DEST" install

# Hermes Agent / Manus / other agent frameworks
# Point the agent at the Sogni-AI/sogni-creative-agent-skill repository.
# Use SKILL.md as the behavior source and invoke the CLI.
```

When operating inside an agent runtime, do not generate clone-or-pull shell
bootstrap scripts with `set -e`, `bash -c`, `sh -c`, or inline repository URLs.
Use the npm upgrade command above, update an existing checkout with `git -C`, or
ask before cloning.

## Configure Sogni API key

Once-only setup, used by every integration above:

The API key can always be found by logging into https://dashboard.sogni.ai and
opening the account menu.

```bash
mkdir -p ~/.config/sogni
cat > ~/.config/sogni/credentials << 'EOF'
SOGNI_API_KEY=your_api_key
EOF
chmod 600 ~/.config/sogni/credentials
```

You can also export `SOGNI_API_KEY` instead of writing the file.

Hosted API modes require `SOGNI_API_KEY`: use `sogni-agent --api-chat "prompt"`
for `/v1/chat/completions` with rich creative-agent tools and sanitized
message forwarding, or
`sogni-agent --api-workflow --video-prompt "motion" "image prompt"`
for durable `/v1/creative-agent/workflows` execution.
Use `SOGNI_SKILL_USE_SDK_TRANSPORT=1 sogni-agent --durable-chat "prompt"` for
durable `/v1/chat/runs` execution with SSE assistant deltas and per-job
progress / ETA / result events.
Sogni Intelligence utilities are available with `--list-api-models`,
`--get-api-model <id>`, `--task-profile general|coding|reasoning`,
`--max-tokens <n>`, `--thinking` / `--no-thinking`, `--list-replays [n]`,
`--get-replay <id>`, and `--ingest-replay <json|@path>` (use `@path` to load JSON from a file).
Hosted API modes forward media references from `-c`, `--ref`, `--ref-end`,
`--ref-audio`, `--reference-audio-identity`, and `--ref-video` as
`media_references`; API chat also attaches image refs as vision inputs. Local
file references are uploaded to Sogni media storage first and then forwarded as
retrievable URLs. Workflow JSON can bind those refs with
`sourceStepId: "$input_media"`. Use `--workflow-max-cost`, `--confirm-cost`,
or `--no-confirm-cost` for durable workflow cost policy. JSON errors include
canonical `errorType`, `errorCategory`, and retryability when classified.

Reusable hosted workflow behavior belongs in `../sogni-creative-agent` before it
is synced into this public skill. Use typed planner/runtime contracts for media
routing and repair decisions; keep skill-local regex limited to CLI fact
extraction such as paths, URLs, extensions, dimensions, durations, and explicit
positions.

## Repo

Sogni-AI/sogni-creative-agent-skill

## Key files

- `SKILL.md` — agent behavior and usage rules (load this into your agent)
- `openclaw.plugin.json` — OpenClaw plugin manifest and config schema
- `.openclaw-link/` — generated OpenClaw link target for local development only
- `sogni-agent.mjs` — CLI used by the skill
