> ## 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.

# Create Skill

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

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](https://wordsmithai.mintlify.site/api-reference/files/upload-url.md).
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](https://wordsmithai.mintlify.site/api-reference/skills/get-skill.md) returns it.

```bash cURL theme={null}
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"}
    ]
  }'
```

```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-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. |


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