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

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

<BetaBadge />

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.

<h2 id="anatomy-of-a-skill">
  Anatomy of a skill
</h2>

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.

<h2 id="use-a-skill">
  Use a skill
</h2>

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.

<h2 id="manage-skills">
  Manage skills
</h2>

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](/docs/products/cloud/features/ai-ml/agents/sharing-and-access)).

<h2 id="skills-vs-instructions">
  Skills vs. instructions
</h2>

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