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

# Update Skill

> Change a skill's name, description, instructions or files.

Changes a skill. Send only what you want to change.

* `instructions` replaces the instructions whole.
* `skill_md` replaces the instructions with its body, and the `name` and `description` with those in its front matter. A `name` or `description` sent beside it wins.
* `files` adds files. A file at a path the skill already has replaces it.
* `remove_files` detaches the files at these paths. The files themselves are not deleted.

`@ref[file_upload:<file_id>]` tokens in the instructions follow the files: a replaced file's tokens name the new file, and a removed file's tokens are dropped. Paths follow the rules in [Create Skill](https://wordsmithai.mintlify.site/api-reference/skills/create-skill.md).

You need edit access to the skill. Public and community skills cannot be changed.

## Authentication

Requires an API key, or an OAuth token with `skills:write`. Sending `files` also needs `files:read`.

## Path parameters

**skill\_id** `string` *required*

The skill to change.

## Body parameters

**name** `string`

The new name, up to 200 characters.

**description** `string | null`

The new description, up to 2,000 characters. Send `null` to clear it.

**instructions** `string`

New instructions, up to 100,000 characters. Send this or `skill_md`, not both.

**skill\_md** `string`

A whole `SKILL.md`, up to 100,000 characters. Send this or `instructions`, not both.

**files** `object[]`

Up to 100 files to add or replace, each as `{"path": "...", "file_id": "..."}`.

**remove\_files** `string[]`

Up to 100 paths of bundled files to detach. Each must name a file the skill has.

## Response

Returns `200` with the updated skill, as [Get Skill](https://wordsmithai.mintlify.site/api-reference/skills/get-skill.md) returns it.

```bash cURL theme={null}
curl -X PATCH "https://api.wordsmith.ai/api/v1/skills/5f0d2c1e-8a47-4b6e-9c31-2d7e4a9b6f10" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"path": "references/positions.md", "file_id": "9d3b7a10-6c2e-4f58-a1b4-8e0f5c2d7a96"}
    ]
  }'
```

```json Response theme={null}
{
  "id": "5f0d2c1e-8a47-4b6e-9c31-2d7e4a9b6f10",
  "name": "nda-review",
  "description": "Review an inbound NDA against our standard positions.",
  "visibility": "private",
  "editable": true,
  "url": "https://app.wordsmith.ai/skills/new?mode=edit&skillId=5f0d2c1e-8a47-4b6e-9c31-2d7e4a9b6f10",
  "created_at": "2026-10-19T09:12:04Z",
  "updated_at": "2026-10-19T10:40:51Z",
  "instructions": "# NDA review\n\nCheck each clause against references/positions.md and flag any gap.",
  "files": [
    {
      "path": "references/positions.md",
      "file_id": "9d3b7a10-6c2e-4f58-a1b4-8e0f5c2d7a96",
      "content_type": "text/markdown"
    }
  ],
  "references": []
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | An empty body, both `instructions` and `skill_md`, front matter that is not valid YAML, a path the rules refuse, a `remove_files` path the skill does not have, a path in both `files` and `remove_files`, a `remove_files` change that leaves the instructions empty, or an unknown field. |
| 403 | `forbidden` | The caller can see the skill but not change it, or it is a public or community skill. |
| 403 | `insufficient_scope` | An OAuth token sends `files` without `files:read`. |
| 404 | `resource_not_found` | No skill with this id, or not one the caller can see; or a `file_id` names no file the caller can read. |
| 409 | `scan_in_progress` | A file's malware scan is still running. Try again shortly. |
| 409 | `resource_conflict` | Other changes to the skill kept landing while its files were being updated. Try again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.