---
title: "Create or update a skill (upsert)"
method: PUT
path: "/sdk/agents/{agentId}/skills/{name}"
tags: ["SDK — Skills"]
---

# Create or update a skill (upsert)

`PUT /sdk/agents/{agentId}/skills/{name}`

## Request

- Base URL: `https://api.agentbrink.com/api`
- URL: `https://api.agentbrink.com/api/sdk/agents/{agentId}/skills/{name}`
- Auth: HTTP bearer

## Request body

- UpsertSkillBody
  - `name` string, required
  - `description` string, required
  - `parameters` SkillParameter[]
    - `name` string, required
    - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required
    - `description` string, required
    - `required` boolean
  - `handler` SkillHandler, required
    - `type` 'webhook' | 'mcp', required
    - `webhookUrl` string: For webhook handlers: URL to POST to
    - `webhookHeaders` object: Optional extra headers for webhook calls
    - `mcpServerUrl` string: For MCP handlers: HTTP base URL of the MCP server
    - `mcpToolName` string: For MCP handlers: tool name to call on the MCP server
  - `enabled` boolean

## Response `200`

Upserted

- Skill
  - `_id` string
  - `name` string
  - `description` string
  - `parameters` SkillParameter[]
    - `name` string, required
    - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required
    - `description` string, required
    - `required` boolean
  - `handler` SkillHandler
    - `type` 'webhook' | 'mcp', required
    - `webhookUrl` string: For webhook handlers: URL to POST to
    - `webhookHeaders` object: Optional extra headers for webhook calls
    - `mcpServerUrl` string: For MCP handlers: HTTP base URL of the MCP server
    - `mcpToolName` string: For MCP handlers: tool name to call on the MCP server
  - `enabled` boolean
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400`: Invalid request body

---

[API](https://skmtc.dev/agentbrink/apis/agentbrink-api.md) · [All operations](https://skmtc.dev/agentbrink/apis/agentbrink-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentbrink/apis/agentbrink-api/revisions/d2c782056161?raw)