Core Concepts

The concepts underneath Studio: Tal, Dance, Performer, Act, and URNs.

You can use Studio without editing JSON by hand, but the concepts matter because Studio is showing real portable assets.

The mental model:

The Canonical Asset Shape#

Tal, Dance, Performer, and Act assets use one canonical wrapper:

{
  "kind": "tal",
  "urn": "tal/@acme/agent-presets/example",
  "description": "Short human-readable summary.",
  "tags": ["example"],
  "payload": {
    "content": "Actual asset content goes here."
  }
}

$schema is legacy and is not part of the canonical contract.

Tal#

A Tal is the identity and always-on rule layer.

Use Tal for stable behavior:

• role and posture
• tone and communication style
• decision-making rules
• constraints that should always apply
• team standards that should not be optional

Example:

{
  "kind": "tal",
  "urn": "tal/@acme-platform/agent-presets/senior-backend-engineer",
  "description": "Backend engineer mindset for platform work.",
  "tags": ["backend", "platform"],
  "payload": {
    "content": "You are a senior backend engineer. Prefer explicit tradeoffs, rollback-safe changes, observability, and test coverage."
  }
}

In Studio, Tal is usually edited or inspected inside the Performer composer. A Performer can have at most one active Tal.

Dance#

A Dance is a reusable skill bundle.

In current DOT workflows, Dance source is a GitHub-style skill directory with a required SKILL.md file:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md frontmatter needs a non-empty name and description:

---
name: pr-review-standard
description: Review pull requests with a consistent engineering checklist.
---

# PR Review Standard

Use this skill when reviewing a pull request.

Typical Dance install path:

dance/@acme-platform/sprint-reviewer/pr-review-standard
→ .dance-of-tal/assets/dance/@acme-platform/sprint-reviewer/pr-review-standard/SKILL.md

Dances are best for:

• PR review checklists
• threat modeling routines
• migration safety procedures
• output formats
• domain-specific reference workflows

Dance is usually not opened as the main runnable unit. Attach Dances to a Performer, then run the Performer in Studio.

Performer#

A Performer is the main runnable unit.

It can include:

• one Tal
• one or more Dances
• a preferred model
• a model variant
• portable MCP requirements

Example:

{
  "kind": "performer",
  "urn": "performer/@acme-platform/agent-presets/sprint",
  "description": "Default engineering performer for everyday work.",
  "tags": ["engineering", "sprint"],
  "payload": {
    "tal": "tal/@acme-platform/agent-presets/senior-backend-engineer",
    "dances": [
      "dance/@acme-platform/sprint-reviewer/pr-review-standard"
    ],
    "model": {
      "provider": "anthropic",
      "modelId": "claude-sonnet-4"
    },
    "modelVariant": "normal"
  }
}

Rules:

• payload.tal is optional
• payload.dances is optional
• at least one of payload.tal or payload.dances must exist
• payload.model is an object: { "provider": "...", "modelId": "..." }
• payload.mcp_config must be portable and must not contain secrets when published

Open a Performer directly in Studio:

dot-studio . --performer performer/@acme-platform/agent-presets/sprint

Studio imports it and its dependencies when needed.

Act#

An Act is a multi-performer collaboration asset.

The Act model is participant-first:

• participants are the performers inside the scene
• relations describe how participants can coordinate
• subscriptions define what wakes a participant
• act rules define scene-level instructions

Example:

{
  "kind": "act",
  "urn": "act/@acme-platform/workflows/incident-response",
  "description": "Incident lead and worker choreography.",
  "tags": ["incident", "workflow"],
  "payload": {
    "actRules": [
      "Lead owns final approval."
    ],
    "participants": [
      {
        "key": "lead",
        "performer": "performer/@acme-platform/agent-presets/incident-lead",
        "subscriptions": {
          "callboardKeys": ["shared/*"]
        }
      },
      {
        "key": "worker",
        "performer": "performer/@acme-platform/agent-presets/incident-worker"
      }
    ],
    "relations": [
      {
        "between": ["lead", "worker"],
        "direction": "one-way",
        "name": "review_request",
        "description": "Lead coordinates, worker executes."
      }
    ]
  }
}

Participant fields:

Relation fields:

Open an Act directly in Studio:

dot-studio . --act act/@acme-platform/workflows/incident-response

URN Format#

Every canonical DOT asset uses:

kind/@owner/stage/name

Examples:

tal/@acme-platform/agent-presets/senior-backend-engineer
dance/@monarchjuno/sprint-reviewer/pr-review-standard
performer/@acme-platform/agent-presets/sprint
act/@acme-platform/workflows/incident-response

Studio uses the word Workspace for the local directory and canvas state. That is separate from the stage segment in a URN.

Which One Should I Use?#