# Skills

## List skills

> List skills for a workspace with pagination. Optionally filter by enabled status. Requires \`Skill.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SearchString":{"type":"string","maxLength":200,"minLength":1},"PaginatedResponse_SkillResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SkillResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[SkillResponse]"},"SkillResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model"},"max_tokens":{"type":"integer","title":"Max Tokens"},"max_result_chars":{"type":"integer","title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S"},"thinking_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Thinking Effort"},"enable_caching":{"type":"boolean","title":"Enable Caching"},"enable_citations":{"type":"boolean","title":"Enable Citations"},"use_structured_output":{"type":"boolean","title":"Use Structured Output"},"integration_tools":{"items":{"$ref":"#/components/schemas/src__models__IntegrationToolRef"},"type":"array","title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/src__models__StaticToolDef"},"type":"array","title":"Static Tools"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery"},"urgency_keywords":{"items":{"type":"string"},"type":"array","title":"Urgency Keywords"},"enabled":{"type":"boolean","title":"Enabled"},"execution_tier":{"type":"string","enum":["direct","orchestrated","autonomous","browser","computer_use"],"title":"Execution Tier"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns"},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled"},"approval_required":{"type":"boolean","title":"Approval Required"},"browser_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Start Url"},"browser_allowed_domains":{"items":{"type":"string"},"type":"array","title":"Browser Allowed Domains"},"browser_auth_integration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Auth Integration"},"version":{"type":"integer","title":"Version"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","slug","name","description","system_prompt","input_schema","result_schema","model","max_tokens","max_result_chars","max_input_tokens","timeout_s","thinking_effort","enable_caching","enable_citations","use_structured_output","integration_tools","static_tools","delivery","urgency_keywords","enabled","execution_tier","max_agent_turns","checkpoint_enabled","approval_required","browser_start_url","browser_allowed_domains","browser_auth_integration","version","created_at","updated_at"],"title":"SkillResponse"},"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"handler":{"type":"string","title":"Handler"}},"type":"object","required":["name","description","input_schema","handler"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/skills":{"get":{"tags":["Skills"],"summary":"List skills","description":"List skills for a workspace with pagination. Optionally filter by enabled status. Requires `Skill.view` permission.","operationId":"list-skills","parameters":[{"name":"enabled","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"}},{"name":"execution_tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Tier"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchString"},{"type":"null"}],"title":"Search"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_SkillResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a skill

> Create a new companion agent skill in a workspace. Requires \`Skill.create\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateSkillRequest":{"properties":{"slug":{"type":"string","maxLength":63,"title":"Slug"},"name":{"$ref":"#/components/schemas/StrippedNonemptyString"},"description":{"$ref":"#/components/schemas/StrippedNonemptyString"},"system_prompt":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","maxLength":128,"title":"Model","default":"claude-sonnet-4-6"},"max_tokens":{"type":"integer","title":"Max Tokens","default":4096},"max_result_chars":{"type":"integer","title":"Max Result Chars","default":2000},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S","default":60},"thinking_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Thinking Effort"},"enable_caching":{"type":"boolean","title":"Enable Caching","default":true},"enable_citations":{"type":"boolean","title":"Enable Citations","default":false},"use_structured_output":{"type":"boolean","title":"Use Structured Output","default":false},"integration_tools":{"items":{"$ref":"#/components/schemas/IntegrationToolRef-Input"},"type":"array","title":"Integration Tools","default":[]},"static_tools":{"items":{"$ref":"#/components/schemas/StaticToolDef-Input"},"type":"array","title":"Static Tools","default":[]},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"urgency_keywords":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Urgency Keywords"},"enabled":{"type":"boolean","title":"Enabled","default":true},"execution_tier":{"type":"string","enum":["direct","orchestrated","autonomous","browser","computer_use"],"title":"Execution Tier","default":"orchestrated"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns","default":20},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled","default":true},"approval_required":{"type":"boolean","title":"Approval Required","default":false},"browser_start_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Browser Start Url"},"browser_allowed_domains":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Browser Allowed Domains"},"browser_auth_integration":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Browser Auth Integration"}},"type":"object","required":["slug","name","description","input_schema"],"title":"CreateSkillRequest"},"StrippedNonemptyString":{"type":"string","minLength":1},"IntegrationToolRef-Input":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"StaticToolDef-Input":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"handler":{"type":"string","title":"Handler"}},"type":"object","required":["name","description","input_schema","handler"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."},"SkillResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model"},"max_tokens":{"type":"integer","title":"Max Tokens"},"max_result_chars":{"type":"integer","title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S"},"thinking_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Thinking Effort"},"enable_caching":{"type":"boolean","title":"Enable Caching"},"enable_citations":{"type":"boolean","title":"Enable Citations"},"use_structured_output":{"type":"boolean","title":"Use Structured Output"},"integration_tools":{"items":{"$ref":"#/components/schemas/src__models__IntegrationToolRef"},"type":"array","title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/src__models__StaticToolDef"},"type":"array","title":"Static Tools"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery"},"urgency_keywords":{"items":{"type":"string"},"type":"array","title":"Urgency Keywords"},"enabled":{"type":"boolean","title":"Enabled"},"execution_tier":{"type":"string","enum":["direct","orchestrated","autonomous","browser","computer_use"],"title":"Execution Tier"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns"},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled"},"approval_required":{"type":"boolean","title":"Approval Required"},"browser_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Start Url"},"browser_allowed_domains":{"items":{"type":"string"},"type":"array","title":"Browser Allowed Domains"},"browser_auth_integration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Auth Integration"},"version":{"type":"integer","title":"Version"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","slug","name","description","system_prompt","input_schema","result_schema","model","max_tokens","max_result_chars","max_input_tokens","timeout_s","thinking_effort","enable_caching","enable_citations","use_structured_output","integration_tools","static_tools","delivery","urgency_keywords","enabled","execution_tier","max_agent_turns","checkpoint_enabled","approval_required","browser_start_url","browser_allowed_domains","browser_auth_integration","version","created_at","updated_at"],"title":"SkillResponse"},"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"handler":{"type":"string","title":"Handler"}},"type":"object","required":["name","description","input_schema","handler"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}},"paths":{"/v1/{workspace_id}/skills":{"post":{"tags":["Skills"],"summary":"Create a skill","description":"Create a new companion agent skill in a workspace. Requires `Skill.create` permission.","operationId":"create-skill","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."},"409":{"description":"Skill slug already taken or conflicts with a built-in tool name."},"422":{"description":"Invalid request body."}}}}}}
```

## Get a skill

> Retrieve a skill by ID. Requires \`Skill.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SkillResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model"},"max_tokens":{"type":"integer","title":"Max Tokens"},"max_result_chars":{"type":"integer","title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S"},"thinking_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Thinking Effort"},"enable_caching":{"type":"boolean","title":"Enable Caching"},"enable_citations":{"type":"boolean","title":"Enable Citations"},"use_structured_output":{"type":"boolean","title":"Use Structured Output"},"integration_tools":{"items":{"$ref":"#/components/schemas/src__models__IntegrationToolRef"},"type":"array","title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/src__models__StaticToolDef"},"type":"array","title":"Static Tools"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery"},"urgency_keywords":{"items":{"type":"string"},"type":"array","title":"Urgency Keywords"},"enabled":{"type":"boolean","title":"Enabled"},"execution_tier":{"type":"string","enum":["direct","orchestrated","autonomous","browser","computer_use"],"title":"Execution Tier"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns"},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled"},"approval_required":{"type":"boolean","title":"Approval Required"},"browser_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Start Url"},"browser_allowed_domains":{"items":{"type":"string"},"type":"array","title":"Browser Allowed Domains"},"browser_auth_integration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Auth Integration"},"version":{"type":"integer","title":"Version"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","slug","name","description","system_prompt","input_schema","result_schema","model","max_tokens","max_result_chars","max_input_tokens","timeout_s","thinking_effort","enable_caching","enable_citations","use_structured_output","integration_tools","static_tools","delivery","urgency_keywords","enabled","execution_tier","max_agent_turns","checkpoint_enabled","approval_required","browser_start_url","browser_allowed_domains","browser_auth_integration","version","created_at","updated_at"],"title":"SkillResponse"},"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"handler":{"type":"string","title":"Handler"}},"type":"object","required":["name","description","input_schema","handler"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/skills/{skill_id}":{"get":{"tags":["Skills"],"summary":"Get a skill","description":"Retrieve a skill by ID. Requires `Skill.view` permission.","operationId":"get-skill","parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Skill not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a skill

> Update a skill's configuration. Increments version and creates an audit trail snapshot. Requires \`Skill.update\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UpdateSkillRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"system_prompt":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens"},"max_result_chars":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timeout S"},"thinking_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Thinking Effort"},"enable_caching":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enable Caching"},"enable_citations":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enable Citations"},"use_structured_output":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Use Structured Output"},"integration_tools":{"anyOf":[{"items":{"$ref":"#/components/schemas/IntegrationToolRef-Input"},"type":"array"},{"type":"null"}],"title":"Integration Tools"},"static_tools":{"anyOf":[{"items":{"$ref":"#/components/schemas/StaticToolDef-Input"},"type":"array"},{"type":"null"}],"title":"Static Tools"},"delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Delivery"},"urgency_keywords":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Urgency Keywords"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"execution_tier":{"anyOf":[{"type":"string","enum":["direct","orchestrated","autonomous","browser","computer_use"]},{"type":"null"}],"title":"Execution Tier"},"max_agent_turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Agent Turns"},"checkpoint_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Checkpoint Enabled"},"approval_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Approval Required"},"browser_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Start Url"},"browser_allowed_domains":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Browser Allowed Domains"},"browser_auth_integration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Auth Integration"}},"type":"object","title":"UpdateSkillRequest"},"StrippedNonemptyString":{"type":"string","minLength":1},"IntegrationToolRef-Input":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"StaticToolDef-Input":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"handler":{"type":"string","title":"Handler"}},"type":"object","required":["name","description","input_schema","handler"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."},"SkillResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model"},"max_tokens":{"type":"integer","title":"Max Tokens"},"max_result_chars":{"type":"integer","title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S"},"thinking_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Thinking Effort"},"enable_caching":{"type":"boolean","title":"Enable Caching"},"enable_citations":{"type":"boolean","title":"Enable Citations"},"use_structured_output":{"type":"boolean","title":"Use Structured Output"},"integration_tools":{"items":{"$ref":"#/components/schemas/src__models__IntegrationToolRef"},"type":"array","title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/src__models__StaticToolDef"},"type":"array","title":"Static Tools"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery"},"urgency_keywords":{"items":{"type":"string"},"type":"array","title":"Urgency Keywords"},"enabled":{"type":"boolean","title":"Enabled"},"execution_tier":{"type":"string","enum":["direct","orchestrated","autonomous","browser","computer_use"],"title":"Execution Tier"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns"},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled"},"approval_required":{"type":"boolean","title":"Approval Required"},"browser_start_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Start Url"},"browser_allowed_domains":{"items":{"type":"string"},"type":"array","title":"Browser Allowed Domains"},"browser_auth_integration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Browser Auth Integration"},"version":{"type":"integer","title":"Version"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","slug","name","description","system_prompt","input_schema","result_schema","model","max_tokens","max_result_chars","max_input_tokens","timeout_s","thinking_effort","enable_caching","enable_citations","use_structured_output","integration_tools","static_tools","delivery","urgency_keywords","enabled","execution_tier","max_agent_turns","checkpoint_enabled","approval_required","browser_start_url","browser_allowed_domains","browser_auth_integration","version","created_at","updated_at"],"title":"SkillResponse"},"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"handler":{"type":"string","title":"Handler"}},"type":"object","required":["name","description","input_schema","handler"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}},"paths":{"/v1/{workspace_id}/skills/{skill_id}":{"put":{"tags":["Skills"],"summary":"Update a skill","description":"Update a skill's configuration. Increments version and creates an audit trail snapshot. Requires `Skill.update` permission.","operationId":"update-skill","parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSkillRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Skill not found."},"422":{"description":"Invalid request body."}}}}}}
```

## Delete a skill

> Delete a skill. SkillVersion audit trail is retained. Requires \`Skill.delete\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/skills/{skill_id}":{"delete":{"tags":["Skills"],"summary":"Delete a skill","description":"Delete a skill. SkillVersion audit trail is retained. Requires `Skill.delete` permission.","operationId":"delete-skill","parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Skill not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get skill references

> Find all HSMs and services that reference this skill's slug in their latest version's tool\_call\_specs. Requires \`Skill.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SkillReferencesResponse":{"properties":{"skill_id":{"type":"string","title":"Skill Id"},"skill_slug":{"type":"string","title":"Skill Slug"},"context_graph_references":{"items":{"$ref":"#/components/schemas/SkillContextGraphReference"},"type":"array","title":"Context Graph References"},"service_references":{"items":{"type":"string"},"type":"array","title":"Service References"}},"type":"object","required":["skill_id","skill_slug","context_graph_references","service_references"],"title":"SkillReferencesResponse"},"SkillContextGraphReference":{"properties":{"context_graph_id":{"type":"string","title":"Context Graph Id"},"context_graph_name":{"type":"string","title":"Context Graph Name"},"version":{"type":"integer","title":"Version"},"states":{"items":{"$ref":"#/components/schemas/SkillStateReference"},"type":"array","title":"States"}},"type":"object","required":["context_graph_id","context_graph_name","version","states"],"title":"SkillContextGraphReference"},"SkillStateReference":{"properties":{"state_name":{"type":"string","title":"State Name"},"tool_spec_category":{"type":"string","title":"Tool Spec Category"}},"type":"object","required":["state_name","tool_spec_category"],"title":"SkillStateReference"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/skills/{skill_id}/references":{"get":{"tags":["Skills"],"summary":"Get skill references","description":"Find all HSMs and services that reference this skill's slug in their latest version's tool_call_specs. Requires `Skill.view` permission.","operationId":"get-skill-references","parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillReferencesResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Skill not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Test a skill

> Execute a skill in isolation with the given input.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"TestSkillRequest":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input"},"static_tool_mocks":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Tool Mocks","default":{}}},"type":"object","required":["input"],"title":"TestSkillRequest"},"TestSkillResponse":{"properties":{"result":{"type":"string","title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms"},"input_tokens":{"type":"integer","title":"Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"cached_tokens":{"type":"integer","title":"Cached Tokens"},"rounds":{"type":"integer","title":"Rounds"},"sub_tool_logs":{"items":{"$ref":"#/components/schemas/SubToolLog"},"type":"array","title":"Sub Tool Logs"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["result","duration_ms","input_tokens","output_tokens","cached_tokens","rounds","sub_tool_logs"],"title":"TestSkillResponse"},"SubToolLog":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"input":{"additionalProperties":true,"type":"object","title":"Input"},"output":{"type":"string","title":"Output"},"duration_ms":{"type":"number","title":"Duration Ms"},"succeeded":{"type":"boolean","title":"Succeeded"},"round":{"type":"integer","title":"Round"}},"type":"object","required":["tool_name","input","output","duration_ms","succeeded","round"],"title":"SubToolLog"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/skills/{skill_id}/test":{"post":{"tags":["Skills"],"summary":"Test a skill","description":"Execute a skill in isolation with the given input.","operationId":"test-skill","parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestSkillRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestSkillResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Skill not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```