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

# Skills

> Create reusable instruction playbooks that agents invoke on their own to standardize repetitive work like document generation

A Skill is a **reusable instruction playbook that an agent invokes on its own**.
Define the method once ("when this kind of request comes in, handle it this way"), and the agent automatically loads and follows it whenever a request during a conversation matches the skill's purpose.

```mermaid theme={null}
flowchart LR
    A[User request] --> B[Agent checks skill catalog<br/>name + when to use]
    B --> C{Is there a<br/>matching skill?}
    C -->|No| D[Answer from general knowledge]
    C -->|Yes| E[Load skill body]
    E --> F[Follow instructions exactly]
    F --> G[Answer · result]
```

<Note>
  The Skills tab is currently in **preview** and appears only in certain environments (development/staging hosts).
  If the Skills tab isn't visible in production, contact your administrator. Document-generation skills (PPT, Word, Excel, HTML) are provided through the [Marketplace](/en/workspace/marketplace).
</Note>

***

## What is a skill?

A skill is an **imperative instruction set** you hand to the agent. It has three parts.

| Element                       | Role                                                            |
| ----------------------------- | --------------------------------------------------------------- |
| **Name**                      | Skill identifier (globally unique)                              |
| **Description (when to use)** | The criteria the agent uses to decide when to invoke this skill |
| **Body (SKILL.md)**           | The step-by-step instructions the agent follows                 |

You can also bundle **files** (scripts, reference documents, etc.) with it when needed.

### Skill vs prompt

They are easy to confuse but are opposites.

<Columns cols={2}>
  <Card title="Prompt" icon="message">
    **You type it yourself.** In chat, a `/` command expands saved text.
  </Card>

  <Card title="Skill" icon="wand-magic-sparkles">
    **The agent chooses it.** You never call a skill — when a request matches the description, the agent invokes it on its own.
  </Card>
</Columns>

<Tip>
  That's why **writing a good description ("when to use") matters most.** The agent decides whether to trigger a skill based solely on this description.
  Example: "Use when the user asks to organize meeting notes into the standard format."
</Tip>

***

## Skill list

Go to **Workspace > Skills** to see every skill you can access.

Each card shows the name, description, author, and last-modified time. Use the search box at the top to search by name or description. The **Generate with AI** and **New Skill** buttons are at the top right (if you have skill write permission).

Card actions:

| Action             | Description                                         |
| ------------------ | --------------------------------------------------- |
| **Click the card** | Open the edit screen (if you have write permission) |
| **Export**         | Download the skill as a JSON file                   |
| **Delete**         | Owner or admin only                                 |

<Warning>
  **Export is a partial backup.** It includes only the name, description, and body — not bundle files or access-control settings. Do not rely on it as a full backup.
</Warning>

***

## Creating a skill

There are two ways to create a skill.

<Tabs>
  <Tab title="New Skill (write it yourself)">
    Click **New Skill** and enter the basic information first.

    | Field                                                   | Description                                     |
    | ------------------------------------------------------- | ----------------------------------------------- |
    | **What are you working on?** (name)                     | Skill name                                      |
    | **When should the agent use this skill?** (description) | Trigger condition                               |
    | **Permission**                                          | Private / Public, per-group/org-unit read/write |

    After saving, you go straight to the **editor** to write the body (SKILL.md). A skill you create yourself is **private** (owner-only) by default.
  </Tab>

  <Tab title="Generate with AI">
    Click **Generate with AI**, describe the skill you need in natural language, and select a model.

    ```
    Example: A skill that reviews Python code and suggests performance improvements
    ```

    The AI drafts the skill's **name, description, and body**. You are taken to the editor afterward to review and refine.

    <Warning>
      **A skill generated with AI is saved as Public by default** — every logged-in user can read it.
      To keep it private, change the permission via the **Access** button in the editor.
    </Warning>
  </Tab>
</Tabs>

<Note>
  A skill **name must be unique across the whole workspace** and is case-sensitive. Saving with a name that already exists produces an error.
</Note>

***

## Skill editor

The editor is a small IDE with a **file tree** on the left and an **editing area** on the right.

### Entry point — SKILL.md

`SKILL.md` always appears at the top of the file tree with an **Entry** tag. Its contents are the skill body — the instructions the agent follows when the skill is triggered.

<Tip>
  Write the body as **imperative instructions to the agent.** The more specific the steps, rules, and output format, the more consistently the agent follows it.
</Tip>

### Adding bundle files

Use the **Add file** button in the file tree to add scripts or reference documents. Specify a path (e.g. `scripts/lookup.py`, `references/style-guide.md`) and they are organized by folder.

* Markdown files support a formatting toolbar (bold/italic/code/list) and an **Edit/Preview** toggle
* Code files (`.py`, `.js`, `.sql`, etc.) get syntax highlighting
* Only relative paths are allowed, and `SKILL.md` cannot be a bundle file (it is the entry point)

<Note>
  When the body references a bundle file, the agent reads it only when needed. It does not load all files at once, so you can include large reference materials without concern.
</Note>

### Meta information

The meta area at the top of the editor shows two things.

| Item               | Meaning                                                      |
| ------------------ | ------------------------------------------------------------ |
| **Used by agents** | List of agents using this skill (reverse dependency)         |
| **Imported**       | Marks skills brought in from the marketplace, a bundle, etc. |

<Tip>
  Check **Used by agents** before deleting or heavily changing a skill. Trying to delete a skill that's in use triggers a confirmation step.
</Tip>

***

## Attaching to an agent

A skill only works once it's attached to an agent.

<Steps>
  <Step title="Open the agent edit screen">
    Open the agent to edit in **Workspace > Agents**.
  </Step>

  <Step title="Select in the Skills section">
    Add the skills to attach in the **Skills** section. Marketplace document-generator capabilities are also selected here.
  </Step>

  <Step title="Save">
    After saving, the agent can use those skills.
  </Step>
</Steps>

<Note>
  Skills have no separate on/off toggle. **Attaching to an agent turns it on; detaching turns it off.** There is no per-conversation toggle.
</Note>

***

## How it works in chat

Once skills are attached to an agent, the following happens during chat.

1. The agent is always aware of the **name + description** list of attached skills
2. When a user request matches a skill's description, the agent **loads that skill's body**
3. It follows the instructions (reading bundle files or running scripts as needed)
4. It reflects the result in the answer

<Note>
  Skill activation has **no separate on-screen indicator.** The agent simply follows the instructions quietly. However, when a skill produces a file (like the document generators), the result file appears above the answer as **`📎 Download: [filename](link)`** first.
</Note>

***

## Executable skills and document generation

Some skills can actually **run** bundled scripts to produce files (PPT, Word, Excel, HTML, etc.). Such **executable skills** work only under these conditions.

* The skill must be marked as executable (the marketplace document generators are the prime example)
* An administrator must have configured a **code execution engine (Jupyter)**

<Warning>
  If the code execution engine is not configured, an executable skill cannot run its scripts and only follows the instructions, so **no file is generated.** If document generation isn't working, ask your administrator to check the code execution setup.
</Warning>

Skills you write yourself cannot become executable. If you need executable document generation, use the document generators in the [Marketplace](/en/workspace/marketplace).

***

## Access control

Skills follow the same permission model as other workspace resources.

| Option      | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| **Public**  | Any logged-in user can read                                             |
| **Private** | Owner and admin only. Can grant read/write to specific groups/org units |

<Note>
  When an agent uses a skill, it re-checks against the **executing user's read permission.** Even if a private skill is attached to a shared agent, it is not exposed to or triggered for users who lack read access.
</Note>

Administrators control per-group **Skills Access** permission (none/read/write) in **Admin Settings > Users > Groups**. The default is locked (none).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Skills tab isn't showing" icon="eye-slash">
    | Cause                           | Solution                                                                        |
    | ------------------------------- | ------------------------------------------------------------------------------- |
    | Preview environment restriction | The Skills tab appears only in certain environments. Contact your administrator |
    | No permission                   | Ask an administrator to grant your group **Skills Access** permission           |
  </Accordion>

  <Accordion title="I can't save the name" icon="triangle-exclamation">
    Skill names must be unique across the whole workspace. Use a different name. (Names are case-sensitive.)
  </Accordion>

  <Accordion title="Documents (PPT, etc.) aren't being created" icon="file-slash">
    Executable skills require an administrator to configure a code execution engine (Jupyter). Check **Admin Settings > Marketplace** or the **Code Execution** settings.
  </Accordion>

  <Accordion title="I can't delete a skill" icon="lock">
    Deletion is blocked if agents are using it. Check the **Used by agents** list in the editor, and if you still want to delete it, confirm the force delete.
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="How is a skill different from a knowledge base?" icon="circle-question">
    A knowledge base (RAG) retrieves and provides **factual information.** A skill provides a **method or procedure.** They work together — for example, a skill instructs "organize it in this format," and the knowledge base fills in the content.
  </Accordion>

  <Accordion title="How long can the skill body be?" icon="circle-question">
    We recommend under 500 lines. Don't put long reference material in the body — split it into **bundle files** and reference them from the body. The agent reads them only when needed.
  </Accordion>

  <Accordion title="Can multiple agents use the same skill?" icon="circle-question">
    Yes. You can attach one skill to multiple agents. Check **Used by agents** in the editor to see which agents currently use it.
  </Accordion>

  <Accordion title="Can I use an AI-generated skill right away?" icon="circle-question">
    It's a draft, so always review it. In particular it's saved as Public by default, so if needed, change the access to Private and refine the body before using it.
  </Accordion>
</AccordionGroup>

***

## Next steps

<Columns cols={2}>
  <Card title="Marketplace" icon="store" href="/en/workspace/marketplace">
    Set up the PPT/Word/Excel/HTML document generators and Google Workspace/Microsoft 365 integrations
  </Card>

  <Card title="Attach to an agent" icon="robot" href="/en/workspace/agents">
    Attach skills to agents to standardize how they work
  </Card>
</Columns>