/studio-assistant-action-surface-guide

name: studio-assistant-action-surface-guide
description: "Lists the exact APM Assistant apply_studio_actions mutation surface, field rules, ref ordering, and payload self-checks. Use before emitting or validating any APM Studio mutation tool call."
compatibility: Designed for the APM Studio built-in assistant projection.

APM Studio Assistant Action Surface

Use this skill when you need to produce, inspect, or verify an `apply_studio_actions` payload.

Output Shape

• Mutations must go through `apply_studio_actions`.
• Tool arguments must be `{ "version": 1, "actions": [...] }`.
• Do not paste raw JSON or fenced JSON into the assistant reply text.
• Omit unspecified optional fields. Do not send empty strings, null placeholders, or empty draft objects.
• Validate the whole payload before calling the tool; one invalid action can cause the call to fail.

Ordering And Refs

• Actions are applied sequentially.
• Use snapshot ids for existing objects.
• Use `ref` only for objects created earlier in the same tool call.
• Keep dependent actions in order: create dependencies first, then attach/update/use them.
• Never invent ids such as `agent-1`, `team-1`, `relation-1`, or `draft-1`.

Action Families

• Instruction draft CRUD: `createInstructionDraft`, `updateInstructionDraft`, `deleteInstructionDraft`
• Skill draft CRUD: `createSkillDraft`, `updateSkillDraft`, `deleteSkillDraft`
• Skill files: `upsertSkillBundleFile`, `deleteSkillBundleEntry`
• Agent CRUD: `createAgent`, `updateAgent`, `deleteAgent`
• Team CRUD: `createTeam`, `updateTeam`, `deleteTeam`
• Participants: `attachAgentToTeam`, `detachParticipantFromTeam`, `updateParticipantSubscriptions`
• Relations: `connectAgents`, `updateRelation`, `removeRelation`
• Studio UI: `showAgent`, `showTeam`, `showDraft`, `setStudioPanel`, `setStudioNodeVisibility`, `setStudioNodeFrame`

Agent Fields

`createAgent` and `updateAgent` support:

• `description`
• `model`
• `modelVariant`
• Skill additions: `addSkillUrns`, `addSkillDraftIds`, `addSkillDraftRefs`, inline `addSkillDrafts`
• Skill removals: `removeSkillUrns`, `removeSkillDraftIds`
• MCP changes: `addMcpServerNames`, `removeMcpServerNames`

Rules:

• Do not include Instruction fields on Agent actions. Instruction drafts are standalone primitives.
• Use inline `addSkillDrafts` when the Skill dependency is new and known.
• Use only available model and variant ids from the snapshot.
• MCP names must already exist in Studio MCP library context; do not invent them.

Team And Relation Fields

`createTeam` supports:

• `name`, `description`, `teamRules`, `safety`
• `participantAgentIds`, `participantAgentRefs`, `participantAgentNames`
• inline `relations`

`updateTeam` supports:

• `name`, `description`, `teamRules`, `safety`

Relation payloads use:

• source locators: `sourceParticipantKey`, `sourceAgentId`, `sourceAgentRef`, `sourceAgentName`
• target locators: `targetParticipantKey`, `targetAgentId`, `targetAgentRef`, `targetAgentName`
• `direction`, `name`, `description`

Rules:

• `teamRules` must be an array of strings.
• Every new relation needs non-empty `name` and `description`.
• Use `source...` and `target...` fields for relation endpoints.
• For brand-new Teams with known participants, prefer participants and relations directly on `createTeam`.

Draft And Bundle Fields

• Instruction/Skill CRUD acts on local drafts only.
• Skill file actions target saved Skill drafts only.
• Bundle paths are relative to the Skill root.
• Bundle paths must not target `SKILL.md` or `draft.json`.
• Use bundle files for `references/*`, `scripts/*`, `assets/*`, and `agents/openai.yaml`.
• Bundle filenames should be stable and human-readable; do not append random strings, hashes, timestamps, or cache-busting suffixes unless the user explicitly wants versioned files.

Participant Subscriptions

`updateParticipantSubscriptions` targets a participant by:

• `participantKey`
• attached `agentId`
• same-call `agentRef`
• exact `agentName`

`subscriptions` supports:

• `messagesFromParticipantKeys`
• `messagesFromAgentIds`
• `messagesFromAgentRefs`
• `messagesFromAgentNames`
• `messageTags`
• `callboardKeys`
• `eventTypes`

Rules:

• Use `null` to clear subscriptions.
• `eventTypes` currently supports only `runtime.idle`.
• `callboardKeys` is canonical.

UI Operations

• `showAgent`: select/reveal an Agent, or open its editor with `surface: "editor"`.
• `showTeam`: select/reveal a Team, or open its editor with `surface: "editor"` and optional `editorMode`.
• `showDraft`: open a saved or same-call Instruction/Skill draft editor.
• `setStudioPanel`: open or close `packages`, `workspaceTracking`, or `terminal`.
• `setStudioNodeVisibility`: hide or show an existing Agent or Team.
• `setStudioNodeFrame`: set absolute canvas `position` and/or `size` for an Agent or Team.

UI-only operations are hot Studio state changes. Do not describe them as packaged, saved, installed, or runtime-affecting.

Examples

Read `references/payload-examples.md` only when you need concrete payload examples.