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

# Skills

> Reusable instruction packs for ClickHouse Agents

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

A skill is a reusable instruction pack an agent can apply on demand. Use skills for procedures that recur across agents — a brand-style guide, a code-review checklist, a runbook for a specific workflow — instead of duplicating the instructions into each agent's system prompt.

## Anatomy of a skill

A skill is a Markdown file with a small frontmatter header:

```markdown theme={null}
---
name: revenue-report
description: Generates the weekly revenue report using our standard segments
always-apply: false
user-invocable: true
---

When asked to generate a revenue report:
1. Filter to the requested period.
2. Apply the standard MRR formula:
     SUM(CASE
       WHEN billing_cycle = 'monthly' THEN amount
       WHEN billing_cycle = 'yearly'  THEN amount / 12
       ELSE 0
     END)
3. Break down by segment: Enterprise, Mid-Market, SMB.
4. Render the result as a Markdown table.
```

The frontmatter knobs that matter most:

* **`name`** - kebab-case identifier.
* **`description`** - short summary used by the model to decide when this skill is relevant. Treat this as the most important field. Write it specifically; vague descriptions lead to wrong-skill invocations.
* **`always-apply`** - when `true`, the skill is primed into every turn instead of being selected. Use sparingly; always-apply skills consume context on every message.
* **`user-invocable`** - when `true` (the default), the skill appears in the `$` popover for manual selection.

You can bundle supporting files alongside the skill — reference docs, sample queries, small scripts — by uploading a `.zip` containing the `SKILL.md` and its assets.

## Use a skill

Three ways an agent reaches for a skill in a conversation:

* **User invocation** - press `$` in the composer and pick the skill from the popover. The skill's content is primed for the next turn.
* **Model auto-selection** - based on the skill's `description`, the agent decides on its own when to apply it.
* **Always-apply** - primed on every turn for skills configured that way.

## Manage skills

The Skills panel in the Cloud console lets you create skills inline, upload `.md` or `.zip` files, and manage which skills are active for your user. Owned skills default to active; deactivate one to remove it from the popover and the model's catalog without deleting it.

Skills can be shared with other users (see [sharing and access](https://clickhouse.com/docs/agents/sharing-and-access.md)).

## Skills vs. instructions

* **Agent instructions** define what the agent is and how it behaves overall. Always on for that agent.
* **Skills** are situational — applied when relevant, scoped to specific workflows.

Reach for a skill when the same set of step-by-step instructions keeps showing up across multiple agents, or when you want it triggered only for specific user requests rather than every turn.
