> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a skill

> Update a skill's metadata or content.

`PUT /api/v1/cloud/skills/{skill_id}`

Updates the metadata or content of the specified skill. Only JSON request bodies are supported.

## Path parameters

| Parameter  | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `skill_id` | string | Yes      | Skill unique identifier |

## Headers

| Header          | Required | Description         |
| --------------- | -------- | ------------------- |
| `Authorization` | Yes      | `Bearer $QODER_PAT` |
| `Content-Type`  | Yes      | `application/json`  |

## Request body

| Field              | Type   | Required | Description                                                                                                                                                     |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | string | No       | New skill name. Maximum 64 characters; lowercase letters, digits, hyphens, and underscores only; must start with a letter or digit                              |
| `description`      | string | No       | New skill description                                                                                                                                           |
| `content`          | string | No       | New skill content. When `content_encoding` is `"base64"`, this must be a base64-encoded zip archive containing `SKILL.md`; otherwise it is stored as plain text |
| `content_encoding` | string | No       | Set to `"base64"` when `content` is a base64-encoded zip archive                                                                                                |
| `metadata`         | object | No       | Custom metadata. Replaces the stored metadata object                                                                                                            |

## Example request

```bash theme={null}
curl -X PUT https://api.qoder.com/api/v1/cloud/skills/skill_019e3bba474b73cfaf19eae9b5f5e66d \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-skill-name",
    "description": "Updated skill description",
    "metadata": {"team":"docs","stage":"updated"}
  }'
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "updated-skill-name",
  "description": "Updated skill description",
  "source": "custom",
  "latest_version": "1",
  "metadata": {
    "team": "docs",
    "stage": "updated"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:36:01.767469Z"
}
```

## Response notes

* `updated_at` is refreshed to the operation time.
* `latest_version` increments when `content` is updated.
* `latest_version` is not incremented for metadata-only updates.
* Fields not included in the request body retain their previous values.

## Errors

| HTTP | Type                    | Trigger                                                            |
| ---- | ----------------------- | ------------------------------------------------------------------ |
| 400  | `invalid_request_error` | Used multipart instead of JSON: "Request body must be valid JSON." |
| 401  | `TOKEN_INVALID`         | Missing or invalid authentication token                            |
| 404  | `not_found_error`       | Skill does not exist or is no longer accessible                    |

## Notes

* The PUT endpoint accepts only `application/json` Content-Type.
* For base64 zip content, the archive must contain `SKILL.md` at the root or one directory below the root.
* If base64 zip content includes `SKILL.md` frontmatter and `name` or `description` are omitted, the API uses the frontmatter values.

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

## Related

<CardGroup cols={2}>
  <Card title="Agent Skills" icon="sparkles" href="/cloud-agents/skills">
    Attach domain expertise to your agent.
  </Card>
</CardGroup>