Skip to content
Documentation

Update skill

PATCH
/api/v1/workspaces/{workspace_id}/skills/{id}
curl --request PATCH \
  --url https://example.com/%7B%7Bapp_url%7D/api/v1/workspaces/1/skills/1 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "brand-voice", "description": "Use when writing on-brand marketing copy for Acme.", "instructions": "# Brand voice\n\nWrite in a warm, concise tone." }'

Updates a single skill by ID.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspace_id
required
integer

Workspace ID

id
required
integer

Skill ID

Request Body

Section titled “Request Body”
Media typeapplication/json
object
name

Unique handle for the skill within the workspace. Lowercase letters, numbers and single hyphens only.

string
Example
brand-voice
description

What the skill does and when to use it.

string
Example
Use when writing on-brand marketing copy for Acme.
instructions

The markdown body of the skill (the SKILL.md instructions).

string
Example
# Brand voice


Write in a warm, concise tone.

Responses

Section titled “Responses”

200

Section titled “200”

Successful

Media typeapplication/json
object
id
required
integer
name
required

Unique handle for the skill within the workspace. Lowercase letters, numbers and single hyphens only (agentskills.io name constraint).

string
description
required

Describes what the skill does and when to use it. Surfaced to the agent as part of the skills manifest.

string
instructions
required

The markdown body of the skill (the SKILL.md instructions).

string
attached_emails
required

Emails attached via email:<id> tokens in the body, resolved to their current id and name. Derived from the body; not set directly.

Array<object>
object
id
required
integer
name
required
string
ai_agents
required

Build agents that can access this skill.

Array<object>
object
id
required
integer
name
required
string
ai_reviewers
required

Review agents that can access this skill.

Array<object>
object
id
required
integer
name
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "id": 12345,
  "name": "brand-voice",
  "description": "Use when writing on-brand marketing copy for Acme.",
  "instructions": "# Brand voice\n\nWrite in a warm, concise tone. Never use exclamation marks.",
  "attached_emails": [
    {
      "id": 12345,
      "name": "Product Updates"
    }
  ],
  "ai_agents": [
    {
      "id": 12345,
      "name": "Marketing Agent"
    }
  ],
  "ai_reviewers": [
    {
      "id": 12345,
      "name": "Brand Reviewer"
    }
  ]
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

404

Section titled “404”

Not Found

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

422

Section titled “422”

Unprocessable Entity

Media typeapplication/json
object
message
required
string
errors
required
object
key
additional properties
Array<string>
Example
{
  "errors": {
    "username": [
      "Username is required.",
      "Username must be unique."
    ],
    "email": [
      "Invalid email format."
    ]
  }
}