---
name: omnivibe-studio-builder
description: Create, configure, validate, and publish OmniVibe Studio agents from a local coding harness using an owner API key.
version: "2026-08-21"
---

# OmniVibe Studio Builder

Use this skill when the user asks you to create or maintain an OmniVibe Studio
agent from their local coding environment. Prefer the OmniVibe CLI when it is
installed; otherwise use the REST API directly.

## Authentication and safety

- Read the owner credential from `OMNIVIBE_API_KEY`. It must start with
  `omv_owner_`.
- Never print, echo, log, commit, or include the key in a URL, prompt, generated
  file, screenshot, or final response.
- If the key is missing, ask the user to create one in OmniVibe Studio and set
  it in their shell or secret manager. Do not ask them to paste it into chat.
- Use `OMNIVIBE_BASE_URL` when set; otherwise use
  `https://api.omnivibe.me`.
- Owner API keys can manage Studio drafts, identity, soul, skills, assets,
  validation, and publishing. They cannot create/revoke owner keys or accept
  Publishing Terms.
- Runtime agent keys (`omv_agent_...`) are not owner credentials and are
  rejected on Studio endpoints.
- Canonical agent credentials must be submitted through Studio's secure
  credential form. Do not use the legacy secrets write endpoints.

## Required agent content

Before publishing, ensure the agent has:

- A unique lowercase handle using letters, numbers, and hyphens.
- A clear name, description, and tagline.
- An explicit category and at least one specialty.
- A non-empty soul or at least one active skill.
- No secrets embedded in the soul, skill instructions, assets, or metadata.

Keep the project source-controlled, but exclude `.env`, credential files, and
local sync metadata that contains sensitive values.

## Preferred CLI workflow

Create the local project if it does not exist:

```bash
omnivibe studio create ./agents/my-agent \
  --handle my-agent \
  --name "My Agent" \
  --category productivity \
  --specialties "workflow automation"
```

Edit these local files:

- `agent.yaml` for identity, category, specialties, and starter prompts.
- `SOUL.md` for behavior and persona.
- `skills/<skill-name>/SKILL.md` for each active capability.
- `assets/` for supported public media files.

Then inspect, sync, and publish:

```bash
omnivibe studio status ./agents/my-agent
omnivibe studio push ./agents/my-agent --dry-run
omnivibe studio push ./agents/my-agent
omnivibe studio publish ./agents/my-agent
```

If publish reports that Publishing Terms are not accepted, stop and ask the
human owner to accept the current version in Studio. Do not attempt to bypass
the attestation with the owner API key.

## Direct REST workflow

Send the owner key only in the `X-API-Key` header:

```http
X-API-Key: <value from OMNIVIBE_API_KEY>
```

1. Create the draft with an idempotency key:

```http
POST /v1/studio/agents
Content-Type: application/json

{
  "creation_intent_id": "stable_unique_intent_id",
  "name": "My Agent",
  "handle": "my-agent",
  "description": "What the agent does.",
  "tagline": "A short user-facing promise",
  "category": "productivity",
  "specialties": ["workflow automation"]
}
```

Reuse the same `creation_intent_id` and request body when retrying a timed-out
create request. Treat the returned top-level `id` as `agent_id`.

2. Update identity when needed:

```http
PATCH /v1/studio/agents/{agent_id}
```

3. Configure the soul:

```http
PUT /v1/studio/agents/{agent_id}/soul
Content-Type: application/json

{
  "raw_fields": {
    "role": "Workflow assistant",
    "style": "Concise and practical",
    "constraints": "Never expose private data"
  },
  "content": "# My Agent\n\nHelp the user automate repeatable workflows."
}
```

4. Add active skills:

```http
POST /v1/studio/agents/{agent_id}/skills
Content-Type: application/json

{
  "name": "workflow-planning",
  "description": "Plan a repeatable workflow",
  "version": "1.0",
  "instructions": "Return a concise ordered plan.",
  "status": "active"
}
```

Treat the skill response's top-level `id` as `skill_id` for mutation routes.
Re-list skills after a canonical bundle update instead of assuming database
projection IDs remain stable.

5. Upload public assets with multipart field `file`:

```http
POST /v1/studio/agents/{agent_id}/assets
```

6. Validate, and inspect all errors and warnings:

```http
POST /v1/studio/agents/{agent_id}/validate
```

Do not publish unless validation returns `status: "passed"`.

7. Read the Publishing Terms state:

```http
GET /v1/studio/publish-terms
```

If `publish_rights_attested` is false or the accepted version is stale, ask
the human owner to accept the current terms in Studio.

8. Publish and verify the result:

```http
POST /v1/studio/agents/{agent_id}/publish
GET  /v1/studio/agents/{agent_id}
GET  /v1/studio/agents/{agent_id}/soul
GET  /v1/studio/agents/{agent_id}/skills
GET  /v1/studio/agents/{agent_id}/assets
```

Confirm that `publish_status` is `published` and that the remote identity,
soul, skills, and assets match the intended project.

## Completion report

Tell the user:

- Which agent and handle were created or updated.
- Whether validation passed and whether warnings remain.
- Whether the agent is draft, review-gated, or published.
- What human action is still required, if any.

Never include the owner key or any credential value in the report.