---
title: skill_update
description: Change a Skill, with a revision check that keeps a change that somebody else made.
---

Ask the agent to change a Skill: its playbook, its name, its description or its slug. Only the parts that you name change.

> Add a rule to the weekly budget review: end with a summary of one line.

The agent reads the Skill with [`skill_get`](/mcp/tools/skill-get), and then calls this tool with the revision that it read. The revision increases by one. If somebody changed the Skill after the agent read it, AdCrunch changes nothing, and the agent reads the Skill again to apply your change to the new version. [Reuse a playbook](/mcp/tools/reuse-a-playbook) walks the whole job.

## Reference

Update an ad-ops playbook (Skill). Pass base_revision (from skill_get) — the update is rejected if the Skill changed since you read it. Only the fields you pass are changed. Optionally rename the slug handle.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `base_revision` | integer | yes | The revision you last read via skill_get. Guards against overwriting a concurrent edit. |
| `body` | string | no | New playbook instructions. |
| `description` | string | no | New discovery description. |
| `name` | string | no | New display name. |
| `skill_name` | string | yes | The current Skill slug identifying which Skill to update. |
| `slug` | string | no | Optional new slug handle (a deliberate rename); normalized to kebab-case. Callers of the old handle must be updated. |

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `skill` | object | yes | The Skill, as it is after the call. |
| `skill.body` | string | yes | The playbook: the instructions that the agent follows, in Markdown. |
| `skill.createdAt` | number | yes | The time at which a user created the Skill, in milliseconds since the Unix epoch, UTC. |
| `skill.createdBy` | string | yes | The id of the user who created the Skill. |
| `skill.description` | string | yes | When to use the Skill. An agent reads it to choose a Skill. |
| `skill.id` | string | yes | The id of the Skill. It does not change when the slug changes. |
| `skill.name` | string | yes | The display name of the Skill. |
| `skill.revision` | integer | yes | It increases by one at each change. Send it as `base_revision` to update or delete the Skill. |
| `skill.slug` | string | yes | The handle of the Skill in your organization. Send it as `skill_name`. |
| `skill.updatedAt` | number or null | yes | The time of the last change to the Skill, in milliseconds since the Unix epoch, UTC. It is `null` until the first update. |

### Failure codes

A failed call has `isError` set, and `structuredContent.error` holds one of these codes. [Errors](/mcp/errors) describes the shape of a failed call.

- `not_found`
- `invalid_slug`
- `revision_mismatch`
- `slug_conflict`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

The token must hold `skill:write`. [Auth & scopes](/mcp/auth) lists each scope.

### Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

- **Writes.** The tool can change data.
- **Destructive.** The tool can make a change that you cannot undo. A client can ask you to confirm before it calls the tool.
- **Not idempotent.** A second call with the same arguments can change more.
- **Closed world.** The tool reads and writes the data of AdCrunch only.

### Example

The arguments:

```json
{
  "base_revision": 3,
  "body": "## When to run\n\nEvery Monday, before the week starts.\n\n## Steps\n\n1. Read the spend of the last seven days for each active campaign.\n2. Find the campaigns above the target cost per action.\n3. Write down what you found, and what you suggest.\n\n## Rules\n\n- End with a summary of one line.",
  "skill_name": "weekly-budget-review"
}
```

The result, in `structuredContent`:

```json
{
  "skill": {
    "body": "## When to run\n\nEvery Monday, before the week starts.\n\n## Steps\n\n1. Read the spend of the last seven days for each active campaign.\n2. Find the campaigns above the target cost per action.\n3. Write down what you found, and what you suggest.\n\n## Rules\n\n- End with a summary of one line.",
    "createdAt": 1789913600000,
    "createdBy": "usr_h3k9m2q7w1z5x8c4v6b0n2d7",
    "description": "Use this every Monday to find the campaigns above the target cost per action.",
    "id": "skl_q8v3m1z6k2d9w4p7x5n0c3j1",
    "name": "Weekly budget review",
    "revision": 4,
    "slug": "weekly-budget-review",
    "updatedAt": 1790172800000
  }
}
```