# Skills

6 min read

This feature is currently in `BETA`. It may change significantly before general availability. Documentation may lag behind feature updates. Use in production environments at your own discretion. Please refer to our [Upgrade and Release Process](https://docs.unique.ai/it-operators/installing-and-upgrading-unique/upgrade-and-release-process) for more information.

Skills follow the open [Agent Skills](https://agentskills.io/home) concept and the [Agent Skills specification](https://agentskills.io/specification). Existing skills authored against that specification are portable into Unique AI Chat when the required `SKILL.md` entry file is present and follows the supported format.

For the end-user explanation of what skills are and how to invoke them in chat, see [Skills in Unique AI Chat](https://docs.unique.ai/users/spaces/unique-ai-chat/skills-in-unique-ai-chat).

# Functionality

The Skills capability lets a Space admin curate a library of named, reusable instructions that users can invoke from chat with a `/` slash command or the chat input menu. Each skill is stored in the company Knowledge Base as a folder containing a `SKILL.md` file with YAML frontmatter and a Markdown body of instructions.

Skills are prompt enrichment. The agent first sees only the available skill names and descriptions. The full skill instructions are loaded only when the user forces a skill or when the agent decides that a skill is relevant for the current request.

Skills are storage-backed by the Knowledge Base. They are not pulled from a git repository, npm registry, external URL, or automatic skill-generation workflow. Admins create the skill manually, upload it into the dedicated company `Skills` folder, and choose which subset to expose to each Space.

## Use Cases

The Skills capability is ideal for:

1. **Reusable analyses and workflows.** Capture a multi-step process, such as competitor research or earnings-call summaries, once as a skill and let users trigger it consistently.

2. **Domain expertise injection.** Encode a subject-matter playbook, such as regulatory review, financial-statement reading, or contract review steps.

3. **Templated outputs.** Ask the model to produce a specific output shape, such as an executive summary, KPI table, board update, or email draft.

4. **Prompt-size control.** Keep rarely needed workflow instructions out of the always-active system prompt and load them only when needed.

## End-User Invocation

End users invoke a skill in one of three ways. Check [here](https://docs.unique.ai/users/spaces/unique-ai-chat/skills-in-unique-ai-chat) for guidance.

# Create a Skill

Unique AI Chat does not yet auto-generate skills. Create the skill manually and upload it to the Knowledge Base.

## Folder Structure

Each skill consists of a folder named after the skill. Inside the folder, add a raw Markdown file named `SKILL.md`.

```
Skills/
  analyze-data/
    SKILL.md
```

The broader Agent Skills concept can include additional files such as `scripts/`, `references/`, `assets/`, examples, templates, and other resources. In Unique AI Chat today, only `SKILL.md` is loaded into the chat context. Add all instructions required by Chat directly to `SKILL.md`.

## Skill File Format

The `SKILL.md` file contains YAML frontmatter followed by the full skill instructions.

```
---
name: analyze-data
description: >-
  Tabular and numerical data analysis with descriptive statistics and insights.
  Use when the user provides data, tables, CSVs, or numbers and wants analysis.
metadata:
  thinking_level: medium
---

# Analyze Data

Follow this workflow when analyzing tabular data...
```

## Format Requirements

| Requirement | Details |
| --- | --- |
| File name | The entry file must be named `SKILL.md`. |
| Frontmatter | The file must start with YAML frontmatter. |
| `name` | **Required**. Use lowercase kebab-case with letters, numbers, and hyphens only, for example `draft-email`. The name can be 1-64 characters. For portability, keep it identical to the parent folder name. |
| `description` | **Required**. Explain what the skill does and when the agent should use it. This description is what helps the agent decide whether to load the skill automatically. |
| `metadata.thinking_level` | **Optional**. Hints the preferred reasoning effort for this skill. Supported values are `minimal`, `low`, `medium`, and `high` (depending on LLM). Put it inside the standard Agent Skills `metadata` block, not as a top-level frontmatter key. |
| Body | Everything below the frontmatter is the full instruction set loaded when the skill is activated. |
| Encoding | Use UTF-8 Markdown. |

## Thinking Level Metadata

Use `metadata.thinking_level` when a skill usually benefits from a specific reasoning effort. The value is used in the next loop iteration after the skill is invoked in the current turn.

```
---
name: security-audit
description: Review code for security issues.
metadata:
  thinking_level: high
---
```

The hint acts as a floor or default for the active skill, not as an override. Explicit higher LLM options, and model-supported effort levels still take precedence. If multiple skills are activated in one run, the highest declared thinking level is used. Invalid values are ignored, and skills without `metadata.thinking_level` behave as before.

If the Markdown or frontmatter does not follow the required format, the skill cannot be loaded and will not be available to the agent.

## Authoring Guidelines

- Keep each skill focused on one workflow or domain.

- Write the `description` as activation guidance. It should clearly say when the skill should be used.

- Put only instructions that are not needed for every message into skills. Always-relevant policies still belong in the space instructions.

- Keep the `SKILL.md` body concise. Very long reference material is part of the broader Agent Skills pattern, but Unique AI Chat does not currently load supporting reference files.

- Validate against the [Agent Skills specification](https://agentskills.io/specification) when portability to other skills-compatible agents is important.

# Configure Skills for a Space

Skills are configured per Space. Adding a skill to the Knowledge Base does not automatically expose it in chat. A Space admin must enable the Skills capability and select the skill folder.

1. **Author the skill.** Create a skill folder under the company `Skills` Knowledge Base folder and upload `SKILL.md`.

2. **Open the Space configuration.** Open the target Space.

3. **Go to Sources & Tools.** Enable the **Skills** capability.

4. **Pick the source folder.** In the Skills settings, click **Select Skills Root Folder**, then choose the `Skills` root, a grouping folder, or an individual skill folder.

5. **Save the Space.** The selected folder and resolved skill list are saved in the Space configuration.

Selecting the root folder makes all valid skills below it available to the Space. Selecting a subfolder limits the Space to the skills in that folder and its subfolders.

## Advanced Configuration

The Skills capability includes advanced configuration like other tools & capabilities in a Space.

| **Setting** | **What it controls** |
| --- | --- |
| Tool Description | The LLM-facing description that explains when skills should be used. |
| Tool Description For System Prompt | Persistent instructions that tell the agent how to activate and follow skills. |
| Tool System Reminder For User Message | The dynamic list of available skills shown to the agent during each turn. |
| Tool Parameter Description Skill Name | Describes the skill name that should be activated. |
| Tool Parameter Description Arguments | Describes optional context that may be passed to a skill when it is activated. |
| Max Listing Desc Chars | Limits the length of each skill description in the skill listing. |
| Skill Budget Context Percent | Limits how much of the context window may be used for the skill listing. |

# Limitations

- **Knowledge Base only.** Skills must live in the company `Skills` Knowledge Base folder. Pulling skills from external git repos, URLs, or registries is not supported. Uploading a skill to a chat does not work.

- **No automatic skill generation.** Unique AI Chat does not yet create skills automatically. Admins create and upload `SKILL.md` manually.

- **Only**`SKILL.md` is loaded in Unique AI Chat. Supporting files such as `scripts/`, `references/`, `assets/`, templates, and code snippets are part of the broader Agent Skills concept, but Unique AI Chat currently does not read them into the chat context.

- **Marker file.** Only folders containing a top-level `SKILL.md` are recognized as skills. Folders without `SKILL.md` are ignored.

- **Single Skills root per company.** The platform auto-creates a single `Skills` scope at the company root with company-wide access. Renaming or duplicating it is not supported.

- **No**`allowed-tools` enforcement. The `allowed-tools` field from the Agent Skills specification is not currently consumed by Unique AI Chat; a skill cannot restrict which platform tools the agent may call from inside its instructions.

- **Naming consistency.** Keep the folder name and `name:` frontmatter value identical to avoid confusion and to stay portable with the Agent Skills specification.

# Admin Validation Messages

The picker (selection of Skill folder to include in the configuration) can surface these validation messages:

- `No skill folders with SKILL.md or Skills.md were found for this selection.` — the selected folder or its visible subtree contains no valid skill.

- `These folders have no Skill/Skills markdown file: …` — the selection includes folders that do not contain `SKILL.md`.

- `Multiple Skills root folders detected. Please rename or remove duplicates so only one 'Skills' folder remains.` — more than one active Skills root exists for the company.

# Feature Flag

The following feature flag must be set for Skills to function:

| Name | Value | Pod | Effect when off |
| --- | --- | --- | --- |
| `FEATURE_FLAG_ENABLE_SKILLS_UN_20042` | `true` or a comma-separated list of Company IDs | `backend-service-chat`, `web-app-theme`, `web-app-admin`, `node-ingestion` | The Skills capability is hidden from the Space tool list, the `/` slash picker and Tools-menu submenu are not shown, the `getOrCreateSkillsRootScope` mutation returns `null`, and no company `Skills` Knowledge Base folder is provisioned.