Skills
Configure LLM-backed micro-agent capabilities with system prompts, schemas, and tool access.
Skills are companion agent capabilities. They are LLM-backed micro-agents that execute specific tasks within a conversation. Unlike Classic API tools (which run versioned code packages), skills are configured declaratively with a system prompt, input/output schema, and model selection.
API Surface
Create a Skill
Create a new companion agent skill in a workspace. Requires Skill.create permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[a-z0-9][a-z0-9_-]*[a-z0-9]$Anthropic model id the skill runs on. A retired Claude id is a 422 that names its successor.
claude-sonnet-5-54096200060Anthropic sampling temperature (0-1). Ignored on models that reject sampling params (Opus 4.7+/Fable, which 400 otherwise). Set at most one of temperature/top_p -- Claude 4+ rejects both; the runtime keeps temperature and drops top_p.
Anthropic nucleus sampling (0-1). Ignored on sampling-param-rejecting models; see temperature.
truefalsefalsetrue20truefalseWhat this skill's writes do, for its sub-tool calls to an endpoint whose kind varies
(one generic GraphQL endpoint that books, cancels and reads). Sub-tool endpoints with their
own kind write that kind whatever the skill says. Leave unset when unknown.
Successful Response
What this skill's writes do through an endpoint whose kind varies. Null when undeclared.
Missing or invalid API key.
Insufficient permissions.
Workspace not found.
Skill slug already taken or conflicts with a built-in tool name.
Invalid request body.
Rate limited.
POST /v1/{workspace_id}/skills HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 755
{
"slug": "text",
"name": "text",
"description": "text",
"system_prompt": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"max_result_chars": 2000,
"max_input_tokens": 1,
"timeout_s": 60,
"thinking_effort": "low",
"temperature": 1,
"top_p": 1,
"enable_caching": true,
"enable_citations": false,
"use_structured_output": false,
"integration_tools": [
{
"integration": "text",
"endpoint": "text",
"skill_input_bindings": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"static_tools": [
{
"name": "text",
"description": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"enabled": true,
"max_agent_turns": 20,
"checkpoint_enabled": true,
"approval_required": false,
"write_kind": "booking"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"name": "text",
"description": "text",
"system_prompt": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"model": "text",
"max_tokens": 1,
"max_result_chars": 1,
"max_input_tokens": 1,
"timeout_s": 1,
"thinking_effort": "low",
"temperature": 1,
"top_p": 1,
"enable_caching": true,
"enable_citations": true,
"use_structured_output": true,
"integration_tools": [
{
"integration": "text",
"endpoint": "text",
"skill_input_bindings": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"static_tools": [
{
"name": "text",
"description": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"enabled": true,
"max_agent_turns": 1,
"checkpoint_enabled": true,
"approval_required": true,
"write_kind": "booking",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}List Skills
List skills for a workspace with pagination. Optionally filter by enabled status. Requires Skill.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
[]50Successful Response
Missing or invalid API key.
Insufficient permissions.
Validation Error
Rate limited.
GET /v1/{workspace_id}/skills HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"name": "text",
"description": "text",
"system_prompt": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"model": "text",
"max_tokens": 1,
"max_result_chars": 1,
"max_input_tokens": 1,
"timeout_s": 1,
"thinking_effort": "low",
"temperature": 1,
"top_p": 1,
"enable_caching": true,
"enable_citations": true,
"use_structured_output": true,
"integration_tools": [
{
"integration": "text",
"endpoint": "text",
"skill_input_bindings": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"static_tools": [
{
"name": "text",
"description": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"enabled": true,
"max_agent_turns": 1,
"checkpoint_enabled": true,
"approval_required": true,
"write_kind": "booking",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": true,
"continuation_token": null
}Get a Skill
Retrieve a skill by ID. Requires Skill.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
What this skill's writes do through an endpoint whose kind varies. Null when undeclared.
Missing or invalid API key.
Insufficient permissions.
Skill not found.
Validation Error
Rate limited.
GET /v1/{workspace_id}/skills/{skill_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"name": "text",
"description": "text",
"system_prompt": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"model": "text",
"max_tokens": 1,
"max_result_chars": 1,
"max_input_tokens": 1,
"timeout_s": 1,
"thinking_effort": "low",
"temperature": 1,
"top_p": 1,
"enable_caching": true,
"enable_citations": true,
"use_structured_output": true,
"integration_tools": [
{
"integration": "text",
"endpoint": "text",
"skill_input_bindings": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"static_tools": [
{
"name": "text",
"description": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"enabled": true,
"max_agent_turns": 1,
"checkpoint_enabled": true,
"approval_required": true,
"write_kind": "booking",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Update a Skill
Update a skill's configuration in place.
Field semantics. Omitted fields and explicit null are treated identically — both leave the existing value unchanged. Empty-string is rejected with 422 for fields that carry a minLength bound (model). Clearing a previously-set optional value back to null is not currently supported via PUT.
Requires Skill.update permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Anthropic model id; see CreateSkillRequest. null/absent leaves it unchanged.
Anthropic sampling temperature (0-1); see CreateSkillRequest. null/absent leaves it unchanged.
Anthropic nucleus sampling (0-1); see CreateSkillRequest. null/absent leaves it unchanged.
What this skill's writes do; see CreateSkillRequest. null/absent leaves it unchanged.
Successful Response
What this skill's writes do through an endpoint whose kind varies. Null when undeclared.
Missing or invalid API key.
Insufficient permissions.
Skill not found.
Invalid request body.
Rate limited.
PUT /v1/{workspace_id}/skills/{skill_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 717
{
"name": "text",
"description": "text",
"system_prompt": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"model": "text",
"max_tokens": 1,
"max_result_chars": 1,
"max_input_tokens": 1,
"timeout_s": 1,
"thinking_effort": "low",
"temperature": 1,
"top_p": 1,
"enable_caching": true,
"enable_citations": true,
"use_structured_output": true,
"integration_tools": [
{
"integration": "text",
"endpoint": "text",
"skill_input_bindings": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"static_tools": [
{
"name": "text",
"description": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"enabled": true,
"max_agent_turns": 1,
"checkpoint_enabled": true,
"approval_required": true,
"write_kind": "booking"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"slug": "text",
"name": "text",
"description": "text",
"system_prompt": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"result_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"model": "text",
"max_tokens": 1,
"max_result_chars": 1,
"max_input_tokens": 1,
"timeout_s": 1,
"thinking_effort": "low",
"temperature": 1,
"top_p": 1,
"enable_caching": true,
"enable_citations": true,
"use_structured_output": true,
"integration_tools": [
{
"integration": "text",
"endpoint": "text",
"skill_input_bindings": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"static_tools": [
{
"name": "text",
"description": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"enabled": true,
"max_agent_turns": 1,
"checkpoint_enabled": true,
"approval_required": true,
"write_kind": "booking",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Delete a Skill
Delete a skill.
Not idempotent. A second concurrent caller racing the same delete will receive 404 Not Found once the row is gone — clients should treat 404 as success-equivalent for cleanup workflows. Requires Skill.delete permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Missing or invalid API key.
Insufficient permissions.
Skill not found.
Skill is referenced by one or more context graphs.
Validation Error
Rate limited.
DELETE /v1/{workspace_id}/skills/{skill_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Missing or invalid API key.
Insufficient permissions.
Skill not found.
Validation Error
Rate limited.
GET /v1/{workspace_id}/skills/{skill_id}/references HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"skill_id": "123e4567-e89b-12d3-a456-426614174000",
"skill_slug": "text",
"context_graph_references": [
{
"context_graph_id": "123e4567-e89b-12d3-a456-426614174000",
"context_graph_name": "text",
"version": 1,
"states": [
{
"state_name": "text",
"tool_spec_category": "text"
}
]
}
],
"service_references": [
"123e4567-e89b-12d3-a456-426614174000"
]
}Test a Skill
Execute a skill in isolation with the given input.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Final result text produced by the skill
Total execution time in milliseconds
Number of input tokens consumed
Number of output tokens generated
Number of tokens served from cache
Number of agent reasoning rounds executed
Error message if the skill execution failed
Missing or invalid API key.
Insufficient permissions.
Skill not found.
Validation Error
POST /v1/{workspace_id}/skills/{skill_id}/test HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103
{
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"static_tool_mocks": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}{
"result": "text",
"duration_ms": 1,
"input_tokens": 1,
"output_tokens": 1,
"cached_tokens": 1,
"rounds": 1,
"sub_tool_logs": [
{
"tool_name": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"output": "text",
"duration_ms": 1,
"succeeded": true,
"round": 1
}
],
"error": "text"
}Input Schema Compatibility
A skill input_schema is used as an LLM tool schema during execution. Keep it in the supported tool-schema subset:
The root schema must describe a single JSON object.
Do not use a top-level
$ref,anyOf,oneOf, orallOf.Array-typed properties must declare
items.
Unsupported shapes are rejected on create/update with 422 because they can cause the LLM tool call to fail silently at runtime.
Execution Configuration
Skills execute as multi-turn LLM agents. Configure their model, token and result limits, timeout, sampling controls, structured output, caching, approval requirement, and maximum tool-use turns through the request schema embedded above. Sampling controls are model-gated; models that do not support them ignore those fields.
A skill model must be a Claude model id. A retired Claude id runs on the current model of its tier, in conversations and in the standalone skill tester: claude-sonnet-5 and claude-sonnet-4-6 run on claude-sonnet-5-5, claude-opus-4-8 on claude-opus-5-5, and claude-haiku-4-5 on claude-haiku-5-5. The stored id is not rewritten and is what skill reads return. A skill created without a model stores claude-sonnet-5-5. Pin a current id to make the configuration match what runs.
A result_schema must be valid JSON Schema, or create and update return 422. With use_structured_output: true, the schema must also constrain status to an enum of success and failure and stay within the supported structured-output subset; otherwise the write returns 422 naming the failing requirement. An update checks only when it sends result_schema or use_structured_output. The skill tester builds the same structured request as conversations, so a structured skill returns JSON matching its result_schema there too.
A skill that calls an integration endpoint declared varies sets write_kind to say what its write does. See Endpoint Write Declarations.
A skill whose last round stops at the token limit or on a model refusal without producing text returns a failed result rather than an empty successful one.
The schema still accepts and returns enable_citations and checkpoint_enabled, but the runtime does not read either field. Setting them has no effect on execution.
Integration with External APIs
Skills can call external APIs through Integrations and inline static tool definitions. Integration tool references identify the integration and endpoint by name.
Bind Skill Inputs to Integration Tools
A Context Graph state can fill a skill’s input using context_bindings or context_binding_aliases; see Pass Context to Tool Parameters. On voice calls, a skill input bound to a declared context key that the call did not start with is refused; see Set Context on a Live Voice Call. The skill’s integration tool reference can then map its inputs into endpoint parameters:
This is an integration_tools entry, not a complete skill request. Both the target endpoint parameter and source skill input must be declared in their respective input schemas. Create/update rejects references to undeclared fields. The runtime hides the target from the companion model and injects the parent skill input when the sub-tool executes. Missing source input prevents that sub-tool call; a model argument cannot substitute for it. The standalone skill tester also applies this mapping, but its parent input must be supplied by the test request.
An integration endpoint can route that parameter into an HTTP header with an exact binding such as "X-Region": "$param.region_header" in its headers configuration. The value must be a non-null scalar without line breaks. Missing or invalid values fail before an outbound request. A consumed header parameter is excluded from the ordinary query/body parameters. Static header values remain supported; this is an exact binding, not arbitrary string interpolation.
Use verified identity bindings for identity-derived authentication. Caller-supplied skill or conversation input is not an access-control credential, and header routing does not make that input trusted.
References
Before modifying or deleting a skill, check what depends on it:
The references operation returns context graphs (with specific states) and services that reference the skill's slug. This prevents breaking live conversation flows by accidentally removing a skill that is in use.
Testing
Use the tool testing endpoints to execute a skill in isolation without starting a conversation. Useful for validating prompt engineering and schema design before wiring into a context graph.
Last updated
Was this helpful?