skills

Workspace API

---

Workspace API / types/skills

types/skills

Interfaces

JSONSchema

Defined in: types/skills.ts:15

JSON Schema definition for input/output validation

Properties

type

type: "string" | "number" | "boolean" | "object" | "array" | "null"

Defined in: types/skills.ts:16

properties?

optional properties: Record<string, JSONSchema>

Defined in: types/skills.ts:17

items?

optional items: JSONSchema

Defined in: types/skills.ts:18

required?

optional required: string[]

Defined in: types/skills.ts:19

additionalProperties?

optional additionalProperties: boolean

Defined in: types/skills.ts:20

minLength?

optional minLength: number

Defined in: types/skills.ts:21

maxLength?

optional maxLength: number

Defined in: types/skills.ts:22

minimum?

optional minimum: number

Defined in: types/skills.ts:23

maximum?

optional maximum: number

Defined in: types/skills.ts:24

enum?

optional enum: (string | number | boolean | null)[]

Defined in: types/skills.ts:25

description?

optional description: string

Defined in: types/skills.ts:26

default?

optional default: unknown

Defined in: types/skills.ts:27

---

DomainPack

Defined in: types/skills.ts:37

Domain Pack - domain-specific system prompts + policy defaults

Properties

id

id: string

Defined in: types/skills.ts:38

organization_id

organization_id: string | null

Defined in: types/skills.ts:39

key

key: string

Defined in: types/skills.ts:40

display_name

display_name: string

Defined in: types/skills.ts:41

system_prompt

system_prompt: string

Defined in: types/skills.ts:42

policy_defaults

policy_defaults: DomainPolicyDefaults

Defined in: types/skills.ts:43

status

status: "disabled" | "active"

Defined in: types/skills.ts:44

created_at

created_at: string

Defined in: types/skills.ts:45

updated_at

updated_at: string

Defined in: types/skills.ts:46

---

DomainPolicyDefaults

Defined in: types/skills.ts:52

Domain-level policy defaults

Properties

default_risk_level?

optional default_risk_level: "high" | "medium" | "low"

Defined in: types/skills.ts:53

default_allowed_tools?

optional default_allowed_tools: string[]

Defined in: types/skills.ts:54

default_caps?

optional default_caps: Partial<SkillCaps>

Defined in: types/skills.ts:55

---

Skill

Defined in: types/skills.ts:65

Skill metadata (shell)

Properties

id

id: string

Defined in: types/skills.ts:66

organization_id

organization_id: string

Defined in: types/skills.ts:67

skill_key

skill_key: string

Defined in: types/skills.ts:68

domain_key

domain_key: string

Defined in: types/skills.ts:69

name

name: string

Defined in: types/skills.ts:70

description

description: string

Defined in: types/skills.ts:71

tags

tags: string[]

Defined in: types/skills.ts:72

trigger_phrases

trigger_phrases: string[]

Defined in: types/skills.ts:73

status

status: "active" | "deprecated"

Defined in: types/skills.ts:74

created_by

created_by: string

Defined in: types/skills.ts:75

created_at

created_at: string

Defined in: types/skills.ts:76

updated_at

updated_at: string

Defined in: types/skills.ts:77

deleted_at?

optional deleted_at: string

Defined in: types/skills.ts:78

---

SkillVersionMetadata

Defined in: types/skills.ts:85

Skill Version Metadata Contains version-level configuration

Indexable

[key: string]: unknown

Additional feature flags or configuration

Properties

engine?

optional engine: "voltagent" | "legacy"

Defined in: types/skills.ts:87

Deprecated

Executor engine selection - no longer used, always VoltAgent

---

SkillVersion

Defined in: types/skills.ts:95

Skill Version - immutable contract

Properties

id

id: string

Defined in: types/skills.ts:96

skill_id

skill_id: string

Defined in: types/skills.ts:97

skill_key

skill_key: string

Defined in: types/skills.ts:98

domain_key

domain_key: string

Defined in: types/skills.ts:99

name

name: string

Defined in: types/skills.ts:100

description

description: string

Defined in: types/skills.ts:101

tags?

optional tags: string[]

Defined in: types/skills.ts:102

trigger_phrases?

optional trigger_phrases: string[]

Defined in: types/skills.ts:103

version

version: string

Defined in: types/skills.ts:104

status

status: "draft" | "active" | "deprecated"

Defined in: types/skills.ts:105

manifest_hash

manifest_hash: string

Defined in: types/skills.ts:106

model_spec

model_spec: SkillModelSpec

Defined in: types/skills.ts:107

metadata?

optional metadata: SkillVersionMetadata

Defined in: types/skills.ts:109

Version metadata including executor engine selection

input_schema

input_schema: JSONSchema

Defined in: types/skills.ts:110

input_schema_version

input_schema_version: string

Defined in: types/skills.ts:111

output_schema

output_schema: JSONSchema

Defined in: types/skills.ts:112

output_schema_version

output_schema_version: string

Defined in: types/skills.ts:113

policy

policy: SkillPolicy

Defined in: types/skills.ts:114

workflow

workflow: SkillWorkflow

Defined in: types/skills.ts:115

skill_system_prompt

skill_system_prompt: string

Defined in: types/skills.ts:116

step_prompts

step_prompts: Record<string, string>

Defined in: types/skills.ts:117

published_by?

optional published_by: string

Defined in: types/skills.ts:118

published_at?

optional published_at: string

Defined in: types/skills.ts:119

created_by

created_by: string

Defined in: types/skills.ts:120

created_at

created_at: string

Defined in: types/skills.ts:121

deleted_at?

optional deleted_at: string

Defined in: types/skills.ts:122

---

SkillModelSpec

Defined in: types/skills.ts:128

Model specification for skill execution

Properties

allowed_models?

optional allowed_models: string[]

Defined in: types/skills.ts:129

default_temperature?

optional default_temperature: number

Defined in: types/skills.ts:130

default_max_tokens?

optional default_max_tokens: number

Defined in: types/skills.ts:131

---

SkillPolicy

Defined in: types/skills.ts:137

Skill policy configuration

Properties

risk_level

risk_level: "high" | "medium" | "low"

Defined in: types/skills.ts:138

requires_human_review

requires_human_review: boolean

Defined in: types/skills.ts:139

allowed_tools

allowed_tools: string[]

Defined in: types/skills.ts:140

data_access

data_access: "project" | "documents" | "org"

Defined in: types/skills.ts:141

caps

caps: SkillCaps

Defined in: types/skills.ts:142

suggestion_requirements?

optional suggestion_requirements: Record<string, unknown>

Defined in: types/skills.ts:143

---

SkillCaps

Defined in: types/skills.ts:149

Execution caps/limits

Properties

max_steps

max_steps: number

Defined in: types/skills.ts:150

max_tool_calls

max_tool_calls: number

Defined in: types/skills.ts:151

max_runtime_ms

max_runtime_ms: number

Defined in: types/skills.ts:152

max_retries_per_step

max_retries_per_step: number

Defined in: types/skills.ts:153

max_payload_bytes

max_payload_bytes: number

Defined in: types/skills.ts:154

---

SkillWorkflow

Defined in: types/skills.ts:160

Skill workflow definition

Properties

type

type: "declarative_v1"

Defined in: types/skills.ts:161

steps

steps: WorkflowStep[]

Defined in: types/skills.ts:162

---

WorkflowStep

Defined in: types/skills.ts:173

Workflow step definition

Properties

name

name: string

Defined in: types/skills.ts:174

type

type: WorkflowStepType

Defined in: types/skills.ts:175

tool_name?

optional tool_name: string

Defined in: types/skills.ts:176

tool_args?

optional tool_args: Record<string, unknown>

Defined in: types/skills.ts:177

tool_calls_allowed?

optional tool_calls_allowed: boolean

Defined in: types/skills.ts:178

allowed_tools?

optional allowed_tools: string[]

Defined in: types/skills.ts:179

output_schema?

optional output_schema: JSONSchema

Defined in: types/skills.ts:180

timeout_ms?

optional timeout_ms: number

Defined in: types/skills.ts:181

prompt_template?

optional prompt_template: string

Defined in: types/skills.ts:182

---

WorkflowRun

Defined in: types/skills.ts:209

Workflow run record

Properties

id

id: string

Defined in: types/skills.ts:210

organization_id

organization_id: string

Defined in: types/skills.ts:211

user_id

user_id: string

Defined in: types/skills.ts:212

conversation_id?

optional conversation_id: string

Defined in: types/skills.ts:213

skill_id

skill_id: string

Defined in: types/skills.ts:214

skill_version_id

skill_version_id: string

Defined in: types/skills.ts:215

manifest_hash

manifest_hash: string

Defined in: types/skills.ts:216

status

status: WorkflowStatus

Defined in: types/skills.ts:217

idempotency_key

idempotency_key: string

Defined in: types/skills.ts:218

approved_at?

optional approved_at: string

Defined in: types/skills.ts:219

approved_by?

optional approved_by: string

Defined in: types/skills.ts:220

input

input: Record<string, unknown>

Defined in: types/skills.ts:221

output?

optional output: Record<string, unknown>

Defined in: types/skills.ts:222

error?

optional error: WorkflowError

Defined in: types/skills.ts:223

trace_id

trace_id: string

Defined in: types/skills.ts:224

checkpoint_data?

optional checkpoint_data: Record<string, unknown>

Defined in: types/skills.ts:225

created_at

created_at: string

Defined in: types/skills.ts:226

updated_at

updated_at: string

Defined in: types/skills.ts:227

deleted_at?

optional deleted_at: string

Defined in: types/skills.ts:228

---

WorkflowStepRecord

Defined in: types/skills.ts:234

Workflow step record

Properties

id

id: string

Defined in: types/skills.ts:235

run_id

run_id: string

Defined in: types/skills.ts:236

step_index

step_index: number

Defined in: types/skills.ts:237

name

name: string

Defined in: types/skills.ts:238

type

type: "tool" | "llm"

Defined in: types/skills.ts:239

status

status: StepStatus

Defined in: types/skills.ts:240

allowed_tools

allowed_tools: string[]

Defined in: types/skills.ts:241

input?

optional input: Record<string, unknown>

Defined in: types/skills.ts:242

output?

optional output: Record<string, unknown>

Defined in: types/skills.ts:243

raw_output?

optional raw_output: string

Defined in: types/skills.ts:244

tool_calls?

optional tool_calls: ToolCallRecord[]

Defined in: types/skills.ts:245

started_at?

optional started_at: string

Defined in: types/skills.ts:246

ended_at?

optional ended_at: string

Defined in: types/skills.ts:247

error?

optional error: WorkflowError

Defined in: types/skills.ts:248

deleted_at?

optional deleted_at: string

Defined in: types/skills.ts:249

---

ToolCallRecord

Defined in: types/skills.ts:255

Tool call record for audit

Properties

tool

tool: string

Defined in: types/skills.ts:256

args

args: Record<string, unknown>

Defined in: types/skills.ts:257

result

result: Record<string, unknown>

Defined in: types/skills.ts:258

duration_ms

duration_ms: number

Defined in: types/skills.ts:259

timestamp

timestamp: string

Defined in: types/skills.ts:260

---

WorkflowError

Defined in: types/skills.ts:303

Workflow error structure

Properties

code

code: WorkflowErrorCode

Defined in: types/skills.ts:304

message

message: string

Defined in: types/skills.ts:305

step_index?

optional step_index: number

Defined in: types/skills.ts:306

details?

optional details: Record<string, unknown>

Defined in: types/skills.ts:307

---

SkillMetadata

Defined in: types/skills.ts:330

Metadata event payload

Properties

traceId

traceId: string

Defined in: types/skills.ts:331

runId

runId: string

Defined in: types/skills.ts:333

Workflow run ID (UUID) - canonical identifier for API use

voltAgentRunId?

optional voltAgentRunId: string

Defined in: types/skills.ts:335

VoltAgent run ID (TEXT) - for VoltOps trace lookup (optional, only present for VoltAgent executions)

voltAgentRunUuid?

optional voltAgentRunUuid: string

Defined in: types/skills.ts:337

VoltAgent run UUID - internal identifier for FK references (optional, only present for VoltAgent executions)

conversationId?

optional conversationId: string

Defined in: types/skills.ts:338

skillId

skillId: string

Defined in: types/skills.ts:339

skillVersionId

skillVersionId: string

Defined in: types/skills.ts:340

manifestHash

manifestHash: string

Defined in: types/skills.ts:341

approvedAt

approvedAt: string

Defined in: types/skills.ts:342

---

SkillPlan

Defined in: types/skills.ts:348

Plan event payload

Properties

steps

steps: object[]

Defined in: types/skills.ts:349

stepIndex

stepIndex: number

name

name: string

type

type: WorkflowStepType

---

StepUpdate

Defined in: types/skills.ts:359

Step update event payload

Properties

stepIndex

stepIndex: number

Defined in: types/skills.ts:360

name?

optional name: string

Defined in: types/skills.ts:361

status

status: StepStatus

Defined in: types/skills.ts:362

output?

optional output: Record<string, unknown>

Defined in: types/skills.ts:363

startedAt?

optional startedAt: string

Defined in: types/skills.ts:364

endedAt?

optional endedAt: string

Defined in: types/skills.ts:365

error?

optional error: string

Defined in: types/skills.ts:367

Error code when status is 'failed'

message?

optional message: string

Defined in: types/skills.ts:369

Error message when status is 'failed'

---

ToolCallEvent

Defined in: types/skills.ts:375

Tool call event payload

Properties

stepIndex

stepIndex: number

Defined in: types/skills.ts:376

tool

tool: string

Defined in: types/skills.ts:377

args

args: Record<string, unknown>

Defined in: types/skills.ts:378

---

ToolResultEvent

Defined in: types/skills.ts:384

Tool result event payload

Properties

stepIndex

stepIndex: number

Defined in: types/skills.ts:385

tool

tool: string

Defined in: types/skills.ts:386

result

result: Record<string, unknown>

Defined in: types/skills.ts:387

duration_ms

duration_ms: number

Defined in: types/skills.ts:388

---

SkillComplete

Defined in: types/skills.ts:394

Complete event payload

Properties

status

status: WorkflowStatus

Defined in: types/skills.ts:395

output

output: Record<string, unknown>

Defined in: types/skills.ts:396

---

MatchReason

Defined in: types/skills.ts:406

Match reason for skill suggestion

Properties

type

type: "keyword" | "tag" | "domain" | "semantic"

Defined in: types/skills.ts:407

value

value: string

Defined in: types/skills.ts:408

score?

optional score: number

Defined in: types/skills.ts:409

---

SkillSuggestion

Defined in: types/skills.ts:415

Skill suggestion result

Properties

skillId

skillId: string

Defined in: types/skills.ts:416

skillVersionId

skillVersionId: string

Defined in: types/skills.ts:417

name

name: string

Defined in: types/skills.ts:418

description

description: string

Defined in: types/skills.ts:419

domain_key

domain_key: string

Defined in: types/skills.ts:420

confidence

confidence: number

Defined in: types/skills.ts:421

match_reasons

match_reasons: MatchReason[]

Defined in: types/skills.ts:422

missing_requirements

missing_requirements: string[]

Defined in: types/skills.ts:423

risk_level

risk_level: "high" | "medium" | "low"

Defined in: types/skills.ts:424

allowed_tools

allowed_tools: string[]

Defined in: types/skills.ts:425

data_access

data_access: "project" | "documents" | "org"

Defined in: types/skills.ts:426

---

SuggestSkillsRequest

Defined in: types/skills.ts:436

Suggest skills request

Properties

query

query: string

Defined in: types/skills.ts:437

domainKey?

optional domainKey: string

Defined in: types/skills.ts:438

context?

optional context: Record<string, unknown>

Defined in: types/skills.ts:439

topK?

optional topK: number

Defined in: types/skills.ts:440

---

RunSkillRequest

Defined in: types/skills.ts:446

Run skill request

Properties

skillVersionId?

optional skillVersionId: string

Defined in: types/skills.ts:447

input

input: Record<string, unknown>

Defined in: types/skills.ts:448

idempotencyKey

idempotencyKey: string

Defined in: types/skills.ts:449

conversationId?

optional conversationId: string

Defined in: types/skills.ts:450

approved?

optional approved: boolean

Defined in: types/skills.ts:451

scope?

optional scope: "organization" | "project" | "documents"

Defined in: types/skills.ts:452

scopeIds?

optional scopeIds: string[]

Defined in: types/skills.ts:453

domainKey?

optional domainKey: string

Defined in: types/skills.ts:454

mode?

optional mode: "execute" | "dry_run"

Defined in: types/skills.ts:455

stream?

optional stream: boolean

Defined in: types/skills.ts:456

---

CreateSkillRequest

Defined in: types/skills.ts:462

Create skill request

Properties

domain_key

domain_key: string

Defined in: types/skills.ts:463

name

name: string

Defined in: types/skills.ts:464

description

description: string

Defined in: types/skills.ts:465

tags?

optional tags: string[]

Defined in: types/skills.ts:466

trigger_phrases?

optional trigger_phrases: string[]

Defined in: types/skills.ts:467

---

CreateSkillVersionRequest

Defined in: types/skills.ts:473

Create skill version request

Properties

copyFromVersionId?

optional copyFromVersionId: string

Defined in: types/skills.ts:474

name?

optional name: string

Defined in: types/skills.ts:475

description?

optional description: string

Defined in: types/skills.ts:476

domain_key?

optional domain_key: string

Defined in: types/skills.ts:477

tags?

optional tags: string[]

Defined in: types/skills.ts:478

trigger_phrases?

optional trigger_phrases: string[]

Defined in: types/skills.ts:479

input_schema?

optional input_schema: JSONSchema

Defined in: types/skills.ts:480

output_schema?

optional output_schema: JSONSchema

Defined in: types/skills.ts:481

policy?

optional policy: Partial<SkillPolicy>

Defined in: types/skills.ts:482

workflow?

optional workflow: SkillWorkflow

Defined in: types/skills.ts:483

skill_system_prompt?

optional skill_system_prompt: string

Defined in: types/skills.ts:484

step_prompts?

optional step_prompts: Record<string, string>

Defined in: types/skills.ts:485

model_spec?

optional model_spec: SkillModelSpec

Defined in: types/skills.ts:486

metadata?

optional metadata: SkillVersionMetadata

Defined in: types/skills.ts:490

Version metadata (engine field deprecated - VoltAgent is the only executor)

---

SkillUsageEvent

Defined in: types/skills.ts:513

Skill usage event record

Properties

id

id: string

Defined in: types/skills.ts:514

organization_id

organization_id: string

Defined in: types/skills.ts:515

user_id

user_id: string

Defined in: types/skills.ts:516

skill_id

skill_id: string

Defined in: types/skills.ts:517

skill_version_id?

optional skill_version_id: string

Defined in: types/skills.ts:518

event_type

event_type: SkillUsageEventType

Defined in: types/skills.ts:519

metadata

metadata: Record<string, unknown>

Defined in: types/skills.ts:520

created_at

created_at: string

Defined in: types/skills.ts:521

Type Aliases

WorkflowStepType

WorkflowStepType = "llm" | "tool"

Defined in: types/skills.ts:168

Workflow step type

---

WorkflowStatus

WorkflowStatus = "queued" | "awaiting_approval" | "running" | "awaiting_review" | "succeeded" | "failed" | "cancelled"

Defined in: types/skills.ts:192

Workflow run status

---

StepStatus

StepStatus = "queued" | "running" | "succeeded" | "failed" | "skipped"

Defined in: types/skills.ts:204

Workflow step status

---

WorkflowErrorCode

WorkflowErrorCode = "INVALID_INPUT_SCHEMA" | "INVALID_STEP_OUTPUT_SCHEMA" | "TOOL_DISABLED" | "TOOL_NOT_ALLOWED" | "TOOL_NOT_FOUND" | "TOOL_ARGUMENTS_INVALID" | "TOOL_EXECUTION_NOT_CONFIGURED" | "TOOL_EXECUTION_FAILED" | "TOOL_EXECUTION_NOT_SUPPORTED" | "TOOL_TIMEOUT" | "POLICY_VIOLATION" | "TIMEOUT" | "RETRY_EXHAUSTED" | "LLM_ERROR" | "LLM_OUTPUT_PARSE_FAILED" | "PERMISSION_DENIED" | "INTERNAL_ERROR" | "EXECUTION_FAILED" | "EXECUTION_CANCELLED" | "IDEMPOTENCY_HIT" | "EXECUTION_IN_PROGRESS" | "EXECUTION_SUSPENDED" | "RATE_LIMIT_EXCEEDED" | "CONCURRENCY_LIMIT_EXCEEDED" | "AGENT_RELOAD_FAILED" | "SKILL_NOT_FOUND" | "SKILL_VERSION_NOT_FOUND" | "DOMAIN_NOT_FOUND"

Defined in: types/skills.ts:270

Workflow error codes

---

SkillSSEEvent

SkillSSEEvent = { type: "metadata"; data: SkillMetadata; } | { type: "plan"; data: SkillPlan; } | { type: "step"; data: StepUpdate; } | { type: "tool_call"; data: ToolCallEvent; } | { type: "tool_result"; data: ToolResultEvent; } | { type: "text"; data: { text: string; }; } | { type: "complete"; data: SkillComplete; } | { type: "error"; data: WorkflowError; }

Defined in: types/skills.ts:317

SSE event types for skill execution streaming

---

SkillUsageEventType

SkillUsageEventType = "suggested" | "accepted" | "run_started" | "run_succeeded" | "run_failed" | "pinned" | "hidden" | "rated"

Defined in: types/skills.ts:500

Skill usage event types

Variables

VALID_WORKFLOW_TRANSITIONS

const VALID_WORKFLOW_TRANSITIONS: Record<WorkflowStatus, WorkflowStatus[]>

Defined in: types/skills.ts:531

Valid workflow status transitions

---

VALID_STEP_TRANSITIONS

const VALID_STEP_TRANSITIONS: Record<StepStatus, StepStatus[]>

Defined in: types/skills.ts:544

Valid step status transitions

Functions

canTransitionWorkflow()

canTransitionWorkflow(from, to): boolean

Defined in: types/skills.ts:555

Check if workflow status transition is valid

Parameters

from

WorkflowStatus

to

WorkflowStatus

Returns

boolean

---

canTransitionStep()

canTransitionStep(from, to): boolean

Defined in: types/skills.ts:562

Check if step status transition is valid

Parameters

from

StepStatus

to

StepStatus

Returns

boolean