Skills

Support reference for the skills library and shared builder pages.

• Library route: `/skills`
• Shared detail route: `/skills/[skill_id]`
• Runs route: `/skills/[skill_id]/runs`
• Run detail route: `/skills/[skill_id]/runs/[run_id]`
• Sidebar/menu label: `Flows`
• Library page heading: `Workflows and Skills`
• The `/skills` library page is org-admin gated in the frontend.
• The shared detail and runs pages are reused from other entry points and do not add the same frontend org-admin gate.

• Header description: `Create, manage, and monitor skills and workflows`.
• Primary action: `Add`
• `/skills` lists only `agent` and `structured` workflows. The default employee workflow type is not part of this library view.
• Current filters on `/skills`:
• `Type`: `Agent`, `Flow`
• `Member`
• `Added`
• `Updated`
• Columns:
• `ID`
• `Member`
• `Name`
• `Description`
• `Type`
• `Added`
• `Updated`
• Row actions:
• `Logs`
• `Delete`
• Bulk action:
• `Delete`

• Dialog title: `New Skill`
• Current fields:
• skill name
• AI teammate selector
• optional description
• The current dialog does not expose a type picker.
• It always creates a `structured` workflow.
• If opened from an AI teammate page, the teammate is preselected and the selector is hidden.

• Shared with org workflows; the back link changes based on `?from=`.
• Top actions:
• `Back` or `Back to Workflows`
• `View Runs`
• `Edit`
• while editing: `Reset Draft`, `Publish`, close button
• The page opens read-only first.
• Name is inline-editable from the header.
• While editing, draft autosave runs after about 1 second of inactivity.
• Publish sends:
• `flow`
• `starting_step_id`
• `payload_format`
• `state_definition`
• `mode`
• `debounce_seconds`
• `debounce_key`

• Entry node label: `Starting Step`
• Starting Step editor currently exposes:
• payload schema editor
• state schema editor labeled `State Definition`
• `Execution Mode`
• `Debounce (seconds)`
• `Debounce Key`
• Debounce validation:
• minimum `5`
• maximum `90`
• Debounce key validation:
• optional
• max length `255`
• State-definition field names use the same frontend validation rules as payload fields:
• must start with a letter or underscore
• only letters, numbers, underscores, and dots are allowed
• trailing dots and consecutive dots are rejected
• Starting Step actions:
• `Start`
• `API` when the workflow has an API URL
• The `Start Skill` dialog always includes a payload JSON textarea.
• If the starting step declares a state definition, the dialog also shows `Initial State (JSON)`.
• The manual-start dialog describes these state values as available through `{{state.key}}` in later steps.
• The manual-start dialog persists the last payload/state JSON locally per skill in the browser.
• `Run Skill` node:
• label defaults to `Run Skill`
• targets another skill
• filters to skills assigned to the same AI teammate when the current workflow has one
• can store payload values and save-to-state mappings
• requires the selected skill to have both a flow and a starting step
• `Assign AI` node:
• backend step type is `run_employee`
• label defaults to `Assign AI`
• selects an AI Teammate from the active AI staff list
• stores an assignment, optional attachments JSON, AI response schema with descriptions, and save-to-state mappings
• `Alloy AI` nodes use the full organization tool catalog in the editor, but published validation still enforces workflow-type guardrails:
• `agent` workflows may contain only `Alloy AI`
• `structured` workflows cannot publish `Alloy AI`

• List entry from the library is labeled `Logs`, but the detail page action is `View Runs`.
• Runs page supports:
• server pagination
• conversation ID filtering via URL/query state
• open run details
• Run detail page heading for logs: `Execution Logs`

• List/create:
• `GET /api/organizations/{orgId}/workflows`
• `POST /api/organizations/{orgId}/workflows`
• Bulk actions:
• `POST /api/organizations/{orgId}/workflows/bulk-delete/`
• `POST /api/organizations/{orgId}/workflows/bulk-restore/`
• All items:
• `GET /api/organizations/{orgId}/workflows/all/`
• Detail/update/delete:
• `GET /api/organizations/{orgId}/workflows/{workflow_id}/`
• `PUT /api/organizations/{orgId}/workflows/{workflow_id}/`
• `DELETE /api/organizations/{orgId}/workflows/{workflow_id}/`
• Draft/publish:
• `PUT /api/organizations/{orgId}/workflows/{workflow_id}/draft`
• `POST /api/organizations/{orgId}/workflows/{workflow_id}/publish`
• Runs:
• `GET /api/organizations/{orgId}/workflows/{workflow_id}/runs/`
• `POST /api/organizations/{orgId}/workflows/{workflow_id}/runs/`
• `GET /api/organizations/{orgId}/workflows/{workflow_id}/runs/{run_id}/`
• manual run creation can send both `payload` and `state`
• org-wide logs feed: `GET /api/organizations/{orgId}/workflows/runs/`
• Public API trigger:
• `POST /api/public/trigger/{public_api_key}/{workflow_id}`
• if `debounce_seconds` and an extractable `debounce_key` are configured, the request is queued in the debouncer and returns `{ debounced: true }`
• if `mode = restart` and the same debounce key already has an active run, the older run is aborted before the new run starts
• Manual run validation:
• payload must include every key declared in `payload_format` with the expected primitive type
• state is optional; when provided, only declared keys are type-checked against `state_definition`
• Current run filters confirmed in code:
• `status`
• `run_id`
• `conversation_id`
• `channel`
• `model`
• `workflow_id`
• `ai_employee_id`
• `trigger_id`
• `started`
• `ended`
• `duration`
• `tokens`
• `exclude`
• WebSocket events used by the library:
• `skill.created`
• `skill.updated`
• `skill.deleted`

• The current create dialogs only create `structured` workflows, even though the list still displays both `Agent` and `Flow` entries.
• The old skill chat/messages endpoints are not part of the current skills UI.
• The workflow detail response currently exposes the workflow object and `api_url`. The shared detail page still does not expose trigger management here.