Core Concepts

Everything you need to understand DOT's building blocks.

On this page you'll learn:

• The core DOT packages: Tal, Dance, Performer, Act
• How assets are structured
• The URN format for naming and discovery
• When to use each concept

Quick reference:

Every DOT Asset Uses the Same Base Shape#

Published DOT assets follow the same high-level structure:

{
  "$schema": "https://schemas.danceoftal.com/assets/tal.v1.json",
  "kind": "tal",
  "urn": "tal/@acme/agent-presets/example",
  "description": "Short human-readable summary.",
  "tags": ["example"],
  "payload": {
    "content": "Actual asset content goes here."
  }
}

Tal — Identity and Rules#

A Tal is the always-on instruction layer — the baseline identity of a Performer.

Use a Tal to define:

• Role and persona
• Tone and communication style
• Decision-making approach
• Non-negotiable constraints
• Standards that always apply

Example#

{
  "$schema": "https://schemas.danceoftal.com/assets/tal.v1.json",
  "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."
  }
}

Tip: Tal works best for stable, identity-level behavior — what the AI optimizes for, how it reasons, what it should never do, and what standards are always active.

Dance — Reusable Skill#

A Dance is a reusable skill module — a technique useful in some situations but not always the core identity.

Great uses for Dances:

• PR review format
• Threat-modeling checklist
• Structured output convention
• Migration review procedure

Example#

{
  "$schema": "https://schemas.danceoftal.com/assets/dance.v1.json",
  "kind": "dance",
  "urn": "dance/@acme-platform/sprint-reviewer/pr-review-standard",
  "description": "Use the team PR review structure and risk language.",
  "tags": ["review", "quality"],
  "payload": {
    "content": "Structure every review as Summary, Risks, Required Changes, and Optional Suggestions. Escalate security and payment risk explicitly."
  }
}

Key behaviors:

• A Performer can include multiple Dances
• Dances are meant to be layered and reused
• They fit techniques better than identity

Performer — Runnable Composition#

A Performer is the installable unit most users care about. It bundles a Tal and/or Dances into something you can run via CLI, MCP hosts, or Studio. If Tal and Dance are modules, Performer is the package.json that locks them together.

Example#

{
  "$schema": "https://schemas.danceoftal.com/assets/performer.v1.json",
  "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"
  }
}

Key fields#

Important:

• At least one of payload.tal or payload.dances must exist
• dot install performer/@author/stage/name cascades — it also installs referenced Tal and Dance assets
• mcp_config should stay portable — project-specific secrets belong in local runtime config

Act — Participant-Based Choreography#

An Act is a multi-performer collaboration asset. The model is participant-first: an Act describes performers that participate in a scene and the relations between them.

Example#

{
  "$schema": "https://schemas.danceoftal.com/assets/act.v1.json",
  "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.",
        "maxCalls": 10,
        "timeout": 300,
        "sessionPolicy": "reuse"
      }
    ]
  }
}

Key fields#

What participants can include#

Each participant references a Performer and may optionally define:

• activeDances — act-specific skill overrides
• subscriptions — event/data channels to watch

What relations define#

Relations describe how participants interact:

Tip: If an Act has multiple participants, it should also have at least one relation — otherwise they can't interact.

URN Format#

Every published DOT asset has a 4-segment URN:

<kind>/@<author>/<stage>/<name>

stage is the third segment — it represents the GitHub repo name for Dance assets, or a managed project group for other asset types.

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

The visual workspace in Studio is called a Workspace, not a Stage.

When to Use What#