Create Skill

Create a skill, or import a SKILL.md folder.

POST /api/v1/skills

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/skills" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_md": "---\nname: nda-review\ndescription: Review an inbound NDA against our standard positions.\n---\n\n# NDA review\n\nCheck each clause against references/positions.md and flag any gap.",
    "files": [
      {"path": "references/positions.md", "file_id": "c1a8e5f2-3b9d-4e07-8f61-0a4d2b7c9e35"}
    ]
  }'

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-19T09:12:04Z",
  "instructions": "# NDA review\n\nCheck each clause against references/positions.md and flag any gap.",
  "files": [
    {
      "path": "references/positions.md",
      "file_id": "c1a8e5f2-3b9d-4e07-8f61-0a4d2b7c9e35",
      "content_type": "text/markdown"
    }
  ],
  "references": []
}

Creates a private skill owned by the caller. Send its name, description and instructions, or send a whole SKILL.md as skill_md.

To import a skill folder, such as a Claude skill:

1. Upload every file in the folder except SKILL.md with the Files API.
2. Send the SKILL.md text as skill_md.
3. Send each uploaded file in files with its path in the folder, such as references/policy.md.

The front matter of skill_md gives the name and description; other keys are ignored. Its body becomes the instructions. A name or description sent beside skill_md wins over the front matter.

The Wordsmith agent finds each file at its path in the skill’s folder. Paths follow the app’s rules: relative, with no empty, . or .. segments, and no two files at one path. SKILL.md at the root is reserved for the skill itself.

Authentication

Requires an API key, or an OAuth token with skills:write. Sending files also needs files:read, because the Wordsmith agent reads them.

Body parameters

name · string

The skill’s name, up to 200 characters. Required unless the skill_md front matter has one.

description · string

When to use the skill, up to 2,000 characters. Wordsmith matches requests against it.

instructions · string

The skill’s markdown body, up to 100,000 characters. Send this or skill_md, not both.

skill_md · string

A whole SKILL.md, up to 100,000 characters: YAML front matter between --- lines, then the instructions. Send this or instructions, not both.

files · object[]

Up to 100 files to bundle, each as {"path": "...", "file_id": "..."}. Each file must be one the caller can read, and its malware scan must be clean.

Response

Returns 201 with the new skill, as Get Skill returns it.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/skills" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_md": "---\nname: nda-review\ndescription: Review an inbound NDA against our standard positions.\n---\n\n# NDA review\n\nCheck each clause against references/positions.md and flag any gap.",
    "files": [
      {"path": "references/positions.md", "file_id": "c1a8e5f2-3b9d-4e07-8f61-0a4d2b7c9e35"}
    ]
  }'

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-19T09:12:04Z",
  "instructions": "# NDA review\n\nCheck each clause against references/positions.md and flag any gap.",
  "files": [
    {
      "path": "references/positions.md",
      "file_id": "c1a8e5f2-3b9d-4e07-8f61-0a4d2b7c9e35",
      "content_type": "text/markdown"
    }
  ],
  "references": []
}

Errors

Status	error_code	When
400	invalid_request_body	Both or neither of instructions and skill_md, no name, front matter that is not valid YAML, a skill_md with no body, a path the rules refuse, or an unknown field.
403	insufficient_scope	An OAuth token sends files without files:read.
404	resource_not_found	A file_id names no file the caller can read, or one whose malware scan failed.
409	scan_in_progress	A file’s malware scan is still running. Try again shortly.