> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Skills

> Create a workspace skill, choose where agents can use it, and confirm it changes their output in Chat, Review, Incident, or Assessment.

A custom skill is a set of written instructions (a `SKILL.md` file) that teaches CloudThinker your team's way of doing a job, such as a review checklist, an escalation order, or a tagging convention. You write it once in **More → Workspace settings → Skills**, and agents apply it wherever you make it available, so nobody retypes the same rule into every prompt.

## When to write a skill

Write a skill when you catch yourself repeating the same instruction. Some typical ones:

| Area | Example rule a skill can carry |
| - | - |
| Review | "Flag any SQL built with string concatenation. Require parameterized queries." |
| Incident | "Check the load balancer and the database before the application pods." |
| Cloud operations | "Every resource needs `team`, `env`, and `cost-center` tags." |
| Reports | "Summarize in three sections: wins, blockers, next steps." |

A skill tells agents **how to act**; reference material to look up belongs in the [knowledge base](https://docs.cloudthinker.io/guide/knowledge.md). See [when to use a skill](https://docs.cloudthinker.io/guide/skills/overview.md#when-to-use-a-skill).

## Prerequisites

* The right role for your method. Developers and Viewers can read skills but don't see the **+** button or **New Skill**. See [roles](https://docs.cloudthinker.io/guide/security/roles.md).

| Method | Who can use it |
| - | - |
| **Write skill instructions**, **Upload zip file**, edit, delete | Workspace Admin |
| **Create with CloudThinker** (`/create-skill` in chat) | Any member who can chat (Admin or Developer) |
| **Skills Hub** install link | Any workspace member |

* If you plan to write `SKILL.md` by hand or upload a package, skim [skill format](https://docs.cloudthinker.io/guide/skills/skill-format.md).

## Create a skill

**1. Open Skills**

Go to **More → Workspace settings → Skills**. The page lists your workspace's skills on the left and shows the selected skill on the right.

**2. Open the new skill menu**

Click the **+** button next to **Search skills**, at the top of the skills list. (With no skills yet, the page shows a **New Skill** button instead.) Pick one of the creation methods from the menu. Use the tabs below for the one you chose.

**3. Create the skill**

> [tab] Create with CloudThinker
>
> Best for a first skill. CloudThinker interviews you and drafts the file.
>
> 1. Click **Create with CloudThinker**. A chat opens with the `/create-skill` command filled in.
> 2. Send it, then answer the questions. Describe one concrete rule your team applies, with an example.
> 3. Review the draft CloudThinker proposes. When it asks **Proceed with creating this skill?**, pick **Yes, create it**, or pick **Change something** and say what to change. Then open **More → Workspace settings → Skills** to confirm the skill is there, enabled and available in **Chat**.
>
> You can start the same flow from any chat by typing `/create-skill`. It's a normal chat, so it uses credits. Nothing is saved until you pick **Yes, create it**, so leaving midway leaves no half-made skill.

> [tab] Write skill instructions
>
> Best when you already know the exact rules.
>
> 1. Click **Write skill instructions**.
> 2. Fill in the form:
>
> | Field | What to enter |
> | - | - |
> | **Skill name** | Starts with a letter or digit; then letters, digits, `_`, or `-`. Example: `weekly-status-report`. Up to 255 characters. |
> | **Description** (required) | When agents should use the skill. Example: "Generate weekly status reports. Use when asked for updates or progress summaries." Always fill it in: agents pick skills by description, and CloudThinker can't save a skill without one. Up to 2,000 characters. |
> | **Instructions** | The rules, in Markdown. Up to 50,000 characters. |
>
> 3. Click **Create**.
>
> A complete example you can paste, used again under [Test the skill](#test-the-skill):
>
> * **Skill name:** `weekly-status-report`
> * **Description:** `Generate weekly status reports. Use when asked for updates or progress summaries.`
> * **Instructions:**
>
> ```markdown theme={null}
> # Weekly status report
>
> Write the report in exactly three sections, in this order:
>
> ## Wins
> What shipped or finished this week. One bullet per item, with the owner.
>
> ## Blockers
> What is stuck, why, and who can unblock it. Write "None" if nothing is blocked.
>
> ## Next steps
> What the team will do next week. One bullet per item, with the owner.
>
> Keep the whole report under 200 words. No other sections.
> ```

> [tab] Upload zip file
>
> Best for skills you keep in a repository or share between workspaces.
>
> 1. Click **Upload zip file**.
> 2. Drop a `.zip` that contains `SKILL.md`. See [zip package layout](https://docs.cloudthinker.io/guide/skills/skill-format.md#zip-package-layout) for the folders and limits.
> 3. Click **Upload**.
>
> If the zip's file name matches an existing skill (for example `weekly-status-report.zip`), CloudThinker asks whether to **Replace** it. **Replace** deletes the old skill and uploads the new one, so the switch goes back on and **Available in** resets to **Chat** only. Re-tick any other surfaces afterwards. On Scale and above, [Audit Logs](https://docs.cloudthinker.io/guide/security/audit-logs.md) keep both the delete and the upload. Either way, the old files and settings are gone.
>
> The match is on the zip's file name, exactly, including case. If the zip name matches an existing skill but its frontmatter `name` differs, **Replace** still deletes the matched skill, then uploads the new one under the frontmatter name.

> [tab] Browse Skills Hub
>
> The hub is a separate site. You leave CloudThinker, pick a skill, and come back through its install link.
>
> 1. Click **Browse Skills Hub**. The public catalog opens in a new tab.
> 2. Find the skill you want.
> 3. Click its install link. CloudThinker opens an **Install Skill** page in your workspace.
> 4. Click **Install**. The skill is added to your skills list, enabled in **Chat** only.
>
> An installed hub skill doesn't update when the hub version changes. If a skill with that name is already in your workspace, the install fails with **Skill already installed in this workspace**.

**Success state:** the skill appears in the list with its switch on and **Chat** checked under **Available in**.

## Choose where the skill applies

A new skill starts enabled and available in Chat only. The other areas stay off until you turn them on, so a half-tested rule can't change your reviews or incident work.

**1. Select the skill**

In **More → Workspace settings → Skills**, click the skill in the list.

**2. Check the areas under Available in**

Tick each place the skill should apply:

| Option | Where agents use it |
| - | - |
| **Chat** | Workspace chat, plus automations and webhooks |
| **Review** | Every merge request and pull request CloudThinker reviews in this workspace, in every connected repository, whether the review started on its own or from an `@cloudthinker-ai review` comment. See [Review](https://docs.cloudthinker.io/guide/code-review/overview.md). |
| **Incident** | Incident analysis and root cause investigation in [Resolve](https://docs.cloudthinker.io/guide/incident/overview.md) |
| **Assessment** | Well-architected and posture assessments |

To pause a skill, use the switch rather than unticking every box.

> [!WARNING]
>
> **Review** has no per-repository filter. Ticking it applies the skill to the next review in every repository. Test the skill in **Chat** first, then follow the Review test under [Test the skill](#test-the-skill).

**3. Confirm the switch is on**

The switch next to the skill name enables or disables it. A disabled skill stays saved but no agent uses it.

## Test the skill

**1. Run a task where the rule matters**

Try both ways, each in a new chat. For the `weekly-status-report` example from the **Write skill instructions** tab:

Run it by name (type `/` and pick it from the menu):

```text theme={null}
/weekly-status-report Notes: shipped the new login page (Ana). Billing export blocked on finance sign-off (Raj). Next week: start the search rewrite (Ana).
```

Run it without naming it:

```text theme={null}
Write a status update for the platform team from these notes: shipped the new login page (Ana). Billing export blocked on finance sign-off (Raj). Next week: start the search rewrite (Ana).
```

Paste notes like these so the agent has real content. Without them, or a connected tracker, it has nothing to report and may ask questions instead. Expect three sections, **Wins**, **Blockers**, and **Next steps**, each with one bullet and an owner.

**Success state:** the agent's activity shows a **Load Skill** step, and both answers follow the skill (here, the wins, blockers, next steps layout) without you restating the rule.

**2. Widen it once it works**

After a few good results in Chat, tick **Review**, **Incident**, or **Assessment** and check the next run there. Review has no sandbox, so test it like this:

1. Tick **Review**.
2. Open a small pull request in a scratch repository that Review covers. Don't open it as a draft: drafts aren't reviewed until they're marked ready. Or comment `@cloudthinker-ai review` on an existing pull request.
3. Check the review follows the skill. If it doesn't, untick **Review** right away, since every repository uses the skill while it's ticked.

The CloudThinker app must be installed on that repository; see [Review setup](https://docs.cloudthinker.io/guide/code-review/setup.md) and [mention commands](https://docs.cloudthinker.io/guide/code-review/mention-commands.md).

If the output ignores the rule, make the rule more specific and add a good and a bad example. Vague guidance such as "follow our style" rarely changes results.

## Edit, download, or delete a skill

Select the skill, then use the icon buttons next to **Available in**. Hover one to see its name.

| Action | How | Notes |
| - | - | - |
| Edit with CloudThinker | Pencil icon (**Edit skill**) → **CloudThinker** | Opens a chat that loads the skill and helps you refine it. |
| Edit by hand | Pencil icon (**Edit skill**) → **Manual** | Edits `SKILL.md` only. Use **Preview** to check rendering, then **Save**. The `name` in the frontmatter must stay the same. To change files in `references/`, `scripts/`, or `schemas/`, download the skill, edit them, and upload the `.zip` with **Replace**. **Replace** resets **Available in** to **Chat** only, so re-tick other surfaces. |
| Download | Download icon (**Download**) | Saves the skill as a `.zip` you can upload to another workspace. |
| Delete | Trash icon (**Delete skill**) | Permanent. |

> [!WARNING]
>
> Deleting a skill can't be undone, and there's no version history to roll back an edit. Download the `.zip` before you edit or delete, or turn the switch off instead if you might need the skill again.

[Audit Logs](https://docs.cloudthinker.io/guide/security/audit-logs.md) record who created, uploaded, edited, re-scoped, or deleted a skill in **More → Workspace settings → Skills**, but only on Scale and Enterprise, and not for skills an agent saves from chat. On other plans nothing records skill changes, so keep every skill's `.zip` in a repository and upload changes from there.

## Troubleshooting

> [accordion] This skill name is already in use
>
> Another skill in this workspace has that name. Pick a different name, or upload a `.zip` and choose **Replace** to overwrite the existing one.

> [accordion] This skill name is reserved
>
> The name matches one of CloudThinker's built-in skills, such as `pdf`, `docx`, or `deep-research`. Pick a different name.

> [accordion] Failed to create skill
>
> The form lets you submit an empty **Description**, but the save then fails with this error. Add one sentence saying when to use the skill and click **Create** again. If the description is filled in, the skill store didn't accept the file; try again.

> [accordion] Failed to upload skill to executor
>
> This is the literal error text (the executor is the service that stores skill files). Usually the `SKILL.md` frontmatter is missing, invalid, or lacks a `name` or `description`. See [skill format troubleshooting](https://docs.cloudthinker.io/guide/skills/skill-format.md#troubleshooting).

> [accordion] Only .zip files are accepted
>
> The upload accepts `.zip` only. Put `SKILL.md` (and any `scripts/`, `schemas/`, or `references/` folders) in a folder, zip it, and upload the zip.

> [accordion] No agent can load this skill
>
> This shows as an alert on the skill's detail panel in **More → Workspace settings → Skills**. The skill's `SKILL.md` frontmatter has no usable `description`, usually because a manual edit removed or broke the `description:` line. Edit it by hand, add a `description:` line, and click **Save**. Until then the skill doesn't appear in the `/` menu.

> [accordion] Cannot preview this skill
>
> The skill's file content can't be loaded. Click **Recovery with AI** to rebuild the `SKILL.md` with CloudThinker through a short interview, or click **Re-upload** to restore it from a `.zip` you kept (for example one you downloaded earlier).

> [accordion] The agent ignores the skill
>
> * Check that the switch is on.
> * Check that the right area is ticked under **Available in** (for example **Review** for pull request reviews).
> * Make the instructions concrete and add examples. Split a long, broad skill into several short ones.

## Next steps

> [card] [Skill format](https://docs.cloudthinker.io/guide/skills/skill-format.md)
>
> Structure `SKILL.md`, set frontmatter, and write rules agents follow.

> [card] [Knowledge base](https://docs.cloudthinker.io/guide/knowledge.md)
>
> Give agents reference docs to look up.

> [card] [Commands](https://docs.cloudthinker.io/guide/commands.md)
>
> Run skills and saved prompts from the `/` menu.

> [card] [Custom agents](https://docs.cloudthinker.io/guide/agents/customize.md)
>
> Build an agent for one job and pair it with your skills.


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