Update Skill

Change a skill’s name, description, instructions or files.

PATCH /api/v1/skills/{skill_id}

cURL

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"}
    ]
  }'

Response

{
  "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": []
}

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.

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 returns it.

cURL

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"}
    ]
  }'

Response

{
  "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.