---
search:
  tags:
    - Skills
    - POST
seo:
  description: >-
    Creates a Skill in your organization. The body is the playbook itself, and
    the… Reference for the POST /context/skills endpoint in the AdCrunch API.
sidebar:
  label: Create a Skill
  badge: POST
title: Create a Skill
type: openapi-operation
---
Creates a Skill in your organization. The body is the playbook itself, and the description is what an agent reads to choose it. AdCrunch makes the slug from the name. To set a different slug, send one. The answer is `409` if the slug already exists in your organization.

`POST /context/skills`

**Request body** (`application/json`, required)

- `body` (string, required) — The playbook instructions (markdown), at most 50,000 characters.
- `description` (string, required) — When to use this Skill — what agents read to discover it.
- `name` (string, required) — Display name.
- `slug` (string) — Optional explicit slug handle; normalized to kebab-case. Defaults to one derived from the name.

Request body example:

```json
{
  "body": "## When to run\n\nEvery Monday, before the week starts.\n\n## Steps\n\n1. Read the last seven days of spend for each live campaign.\n2. Move budget to the campaigns under the target cost per action.\n3. Write down what you changed, and why.",
  "description": "Use this every Monday to move budget towards the campaigns that reach the target cost per action.",
  "name": "Weekly budget review",
  "slug": "weekly-budget-review"
}
```

**Responses**

- `201` — The Skill as created, at \`revision\` 1. Send that revision back as \`base\_revision\` on your first edit.
- `400` — The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. \`error\` is \`invalid\_request\`, and \`issues\` names each field. Nothing was changed.
- `401` — No API key, or one that does not resolve. See the security scheme. \`error\` is \`unauthorized\`.
- `402` — The organization has no active subscription. An owner subscribes at \`paywallUrl\`. \`error\` is \`organization\_unentitled\`.
- `403` — The caller does not hold \`skill:write\`. \`error\` is \`forbidden\`.
- `409` — Another Skill in this organization already holds that slug. \`error\` is \`slug\_conflict\`.
- `422` — The name and slug together contain no letter or digit, so no handle can be derived. \`error\` is \`invalid\_slug\`. A body that fails the schema answers with the framework shape instead.

Response example, 201:

```json
{
  "body": "## When to run\n\nEvery Monday, before the week starts.\n\n## Steps\n\n1. Read the last seven days of spend for each live campaign.\n2. Move budget to the campaigns under the target cost per action.\n3. Write down what you changed, and why.",
  "createdAt": 1790000000000,
  "createdBy": "usr_4d8b12",
  "description": "Use this every Monday to move budget towards the campaigns that reach the target cost per action.",
  "id": "skl_2d7e14",
  "name": "Weekly budget review",
  "revision": 1,
  "slug": "weekly-budget-review",
  "source": null,
  "updatedAt": null
}
```
