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 - `Run Employee` node: - label defaults to `Run Employee` - selects another AI teammate from the active AI staff list - stores message, optional attachments JSON, output 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.