diff --git a/docs/features/chat-features/index.mdx b/docs/features/chat-features/index.mdx index 9ac8814f..21428972 100644 --- a/docs/features/chat-features/index.mdx +++ b/docs/features/chat-features/index.mdx @@ -26,3 +26,4 @@ Open WebUI provides a comprehensive set of chat features designed to enhance you - **[🧠 Reasoning & Thinking Models](./reasoning-models.mdx)**: Specialized support for models that generate internal chains of thought using thinking tags. - **[💬 Follow-Up Prompts](./follow-up-prompts.md)**: Automatic generation of suggested follow-up questions after model responses. +- **Skill Mentions**: Use `$` in the chat input to mention and activate [Skills](/features/workspace/skills) on-the-fly, injecting their manifests into the conversation. diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index 7ad37607..1cdd8ce3 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -206,6 +206,8 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_channel_messages` | Search for specific messages inside accessible channels. | | `view_channel_message` | View a specific message or its details in a channel. | | `view_channel_thread` | View a full message thread/replies in a channel. | +| **Skills** | *Requires per-model "Skills" category enabled (default: on).* | +| `view_skill` | Load the full instructions of a skill from the available skills manifest. | | **Time Tools** | *Requires per-model "Time & Calculation" category enabled (default: on).* | | `get_current_timestamp` | Get the current UTC Unix timestamp and ISO date. | | `calculate_timestamp` | Calculate relative timestamps (e.g., "3 days ago"). | @@ -244,6 +246,8 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_channel_messages` | `query` (required), `count` (default: 10), `start_timestamp`, `end_timestamp` | Array of `{id, channel_id, content, user_name, created_at}` | | `view_channel_message` | `message_id` (required) | `{id, content, user_name, created_at, reply_count}` | | `view_channel_thread` | `parent_message_id` (required) | Array of `{id, content, user_name, created_at}` | +| **Skills** | | | +| `view_skill` | `name` (required) | `{name, content}` | | **Time Tools** | | | | `get_current_timestamp` | None | `{current_timestamp, current_iso}` | | `calculate_timestamp` | `days_ago`, `weeks_ago`, `months_ago`, `years_ago` (all default: 0) | `{current_timestamp, current_iso, calculated_timestamp, calculated_iso}` | @@ -314,6 +318,7 @@ When the **Builtin Tools** capability is enabled, you can further control which | **Notes** | `search_notes`, `view_note`, `write_note`, `replace_note_content` | Search, view, and manage user notes | | **Knowledge Base** | `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `view_knowledge_file` | Browse and query knowledge bases | | **Channels** | `search_channels`, `search_channel_messages`, `view_channel_message`, `view_channel_thread` | Search channels and channel messages | +| **Skills** | `view_skill` | Load skill instructions on-demand from the manifest | All categories are **enabled by default**. Disabling a category prevents those specific tools from being injected, while keeping other categories active. diff --git a/docs/features/rbac/permissions.md b/docs/features/rbac/permissions.md index fe671438..5bde3c3f 100644 --- a/docs/features/rbac/permissions.md +++ b/docs/features/rbac/permissions.md @@ -47,6 +47,7 @@ Some permissions are **dependent** on others (e.g., you cannot import models if | **Tools Access** | **(Parent)** Access the **Tools** workspace to manage functions/tools. | | **Tools Import** | *(Requires Tools Access)* Ability to import tools. | | **Tools Export** | *(Requires Tools Access)* Ability to export tools. | +| **Skills Access** | Access the **Skills** workspace to create and manage reusable instruction sets. | ### 2. Sharing Permissions Controls what users can share with the community or make public. @@ -61,6 +62,8 @@ Controls what users can share with the community or make public. | **Public Prompts** | *(Requires Share Prompts)* Ability to make prompts public. | | **Share Tools** | **(Parent)** Ability to share tools. | | **Public Tools** | *(Requires Share Tools)* Ability to make tools public. | +| **Share Skills** | **(Parent)** Ability to share skills. | +| **Public Skills** | *(Requires Share Skills)* Ability to make skills public. | | **Share Notes** | **(Parent)** Ability to share Notes. | | **Public Notes** | *(Requires Share Notes)* Ability to make Notes public. | diff --git a/docs/features/workspace/index.mdx b/docs/features/workspace/index.mdx index 46d6145d..8ff8d81f 100644 --- a/docs/features/workspace/index.mdx +++ b/docs/features/workspace/index.mdx @@ -11,5 +11,6 @@ The Workspace in Open WebUI provides a comprehensive environment for managing yo - [🧠 Knowledge](./knowledge.md) - Manage your knowledge bases for retrieval augmented generation - [📚 Prompts](./prompts.md) - Create and organize reusable prompts - [📁 Files](./files.md) - Centralized management for all your uploaded documents +- [📝 Skills](./skills.md) - Reusable markdown instruction sets for guiding model behavior Each section of the Workspace is designed to give you fine-grained control over your Open WebUI experience, allowing for customization and optimization of your AI interactions. diff --git a/docs/features/workspace/models.md b/docs/features/workspace/models.md index 052c6b3d..e41bd548 100644 --- a/docs/features/workspace/models.md +++ b/docs/features/workspace/models.md @@ -74,6 +74,7 @@ You can transform a generic model into a specialized agent by toggling specific - **Knowledge**: Instead of manually selecting documents for every chat, you can bind a specific knowledgebase **Collection** or **File** to this model. Whenever this model is selected, RAG (Retrieval Augmented Generation) is automatically active for those specific files. Click on attached items to toggle between **Focused Retrieval** (RAG chunks) and **Using Entire Document** (full content injection). See [Full Context vs Focused Retrieval](/features/workspace/knowledge#full-context-vs-focused-retrieval) for details. - **Tools**: Force specific tools to be enabled by default (e.g., always enable the **Calculator** tool for a "Math Bot"). +- **Skills**: Bind [Skills](/features/workspace/skills) to this model so their manifests are always injected. The model can load full skill instructions on-demand via the `view_skill` builtin tool. - **Filters**: Attach specific Pipelines/Filters (e.g., a Profanity Filter or PII Redaction script) to run exclusively on this model. - **Actions**: Attach actionable scripts like `Add to Memories` or `Button` triggers. - **Capabilities**: Granularly control what the model is allowed to do: diff --git a/docs/features/workspace/skills.md b/docs/features/workspace/skills.md new file mode 100644 index 00000000..d7abfc9a --- /dev/null +++ b/docs/features/workspace/skills.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 6 +title: "Skills" +sidebar_label: "Skills" +--- + +Skills are reusable, markdown-based instruction sets that you can attach to models or invoke on-the-fly in chat. Unlike [Tools](/features/plugin/tools) (which are executable Python scripts), Skills are **plain-text instructions** that teach a model *how* to approach a task — such as code review guidelines, writing style rules, or troubleshooting playbooks. + +## How Skills Work + +Skills use a **lazy-loading** architecture to keep the model's context window efficient: + +1. **Manifest injection** — When a skill is active (either bound to a model or mentioned in chat), only a lightweight manifest containing the skill's **name** and **description** is injected into the system prompt. +2. **On-demand loading** — The model receives a `view_skill` builtin tool. When it determines it needs a skill's full instructions, it calls `view_skill` with the skill name to load the complete content. + +This design means that even if dozens of skills are available, only the ones the model actually needs are loaded into context. + +## Creating a Skill + +Navigate to **Workspace → Skills** and click **+ New Skill**. + +| Field | Description | +| :--- | :--- | +| **Name** | A human-readable display name (e.g., "Code Review Guidelines"). | +| **Skill ID** | A unique slug identifier, auto-generated from the name (e.g., `code-review-guidelines`). Editable during creation, read-only afterwards. | +| **Description** | A short summary shown in the manifest. The model uses this to decide whether to load the full instructions. | +| **Content** | The full skill instructions in **Markdown**. This is the content loaded by `view_skill`. | + +Click **Save & Create** to finalize. + +## Using Skills + +### In Chat ($ Mention) + +Type `$` in the chat input to open the skill picker. Select a skill, and it will be attached to the message as a **skill mention** (similar to `@` for models or `#` for knowledge). The skill manifest is injected for that conversation, and the model can call `view_skill` to load the full instructions when needed. + +### Bound to a Model + +You can permanently attach skills to a model so they are always available: + +1. Go to **Workspace → Models**. +2. Edit a model and scroll to the **Skills** section. +3. Check the skills you want this model to always have access to. +4. Click **Save**. + +When a user chats with that model, the selected skills' manifests are automatically injected. + +## Import and Export + +### Importing from Markdown + +Click **Import** on the Skills workspace page and select a `.md` file. If the file contains YAML frontmatter with `name` and/or `description` fields, those values are auto-populated into the creation form. + +Example frontmatter: + +```yaml +--- +name: code-review-guidelines +description: Step-by-step instructions for thorough code reviews +--- + +# Code Review Guidelines + +1. Check for correctness... +``` + +### Exporting + +- **Single skill**: Click the ellipsis menu (**...**) on a skill and select **Export** to download it as a JSON file. +- **Bulk export**: Click the **Export** button at the top of the Skills page to export all accessible skills as a single JSON file. + +## Skill Management + +From the Skills workspace list, you can perform the following actions via the ellipsis menu (**...**) on each skill: + +| Action | Description | +| :--- | :--- | +| **Edit** | Open the skill editor to modify content, name, or description. | +| **Clone** | Create a copy with `-clone` appended to the ID and "(Clone)" to the name. | +| **Export** | Download the skill as a JSON file. | +| **Delete** | Permanently remove the skill. Also available via Shift+Click on the delete icon for quick deletion. | + +### Active / Inactive Toggle + +Each skill has an **active/inactive toggle** visible on the list page. Inactive skills are excluded from manifests and cannot be loaded by the model, even if they are bound to one or mentioned in chat. + +## Access Control + +Skills use the same [Access Control](/features/rbac) system as other workspace resources: + +- **Private by default**: Only the creator can see and edit a new skill. +- **Share with users or groups**: Use the **Access** button in the skill editor to grant `read` or `write` access to specific users or groups. +- **Read-only access**: Users with only read access can view the skill content but cannot edit it. The editor displays a "Read Only" badge. + +### Required Permissions + +- **Workspace → Skills Access**: Required to access the Skills workspace and create/manage skills. +- **Sharing → Share Skills**: Required to share skills with individual users or groups. +- **Sharing → Public Skills**: Required to make skills publicly accessible. + +See [Permissions](/features/rbac/permissions) for details on how to configure these. diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index b5203d21..f6fc962a 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5294,6 +5294,13 @@ For API Key creation (and the API keys themselves) to work, you need **both**: - Description: Enables or disables user permission to access workspace tools. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `USER_PERMISSIONS_WORKSPACE_SKILLS_ACCESS` + +- Type: `bool` +- Default: `False` +- Description: Enables or disables user permission to access workspace skills. +- Persistence: This environment variable is a `PersistentConfig` variable. + ### Sharing (Private) These settings control whether users can share workspace items with other users **privately** (non-public sharing). @@ -5326,6 +5333,13 @@ These settings control whether users can share workspace items with other users - Description: Enables or disables **private sharing** of workspace tools. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_SHARING` + +- Type: `str` +- Default: `False` +- Description: Enables or disables **private sharing** of workspace skills. +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `USER_PERMISSIONS_NOTES_ALLOW_SHARING` - Type: `str` @@ -5365,6 +5379,13 @@ These settings control whether users can share workspace items **publicly**. - Description: Enables or disables **public sharing** of workspace tools. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_PUBLIC_SHARING` + +- Type: `str` +- Default: `False` +- Description: Enables or disables **public sharing** of workspace skills. +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING` - Type: `str` diff --git a/docs/tutorials/tips/sqlite-database.md b/docs/tutorials/tips/sqlite-database.md index a6802bda..5795a782 100644 --- a/docs/tutorials/tips/sqlite-database.md +++ b/docs/tutorials/tips/sqlite-database.md @@ -81,9 +81,10 @@ Here is a complete list of tables in Open-WebUI's SQLite database. The tables ar | 25 | oauth_session | Manages active OAuth sessions for users | | 26 | prompt | Stores templates and configurations for AI prompts | | 27 | prompt_history | Tracks version history and snapshots for prompts | -| 28 | tag | Manages tags/labels for content categorization | -| 29 | tool | Stores configurations for system tools and integrations | -| 30 | user | Maintains user profiles and account information | +| 28 | skill | Stores reusable markdown instruction sets (Skills) | +| 29 | tag | Manages tags/labels for content categorization | +| 30 | tool | Stores configurations for system tools and integrations | +| 31 | user | Maintains user profiles and account information | Note: there are two additional tables in Open-WebUI's SQLite database that are not related to Open-WebUI's core functionality, that have been excluded: @@ -483,6 +484,27 @@ Access control for resources (models, knowledge bases, tools, prompts, notes, fi | commit_message | Text | nullable | Version commit message | | created_at | BigInteger | NOT NULL | Creation timestamp | +## Skill Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | --------------- | ---------------------------------- | +| id | Text | PRIMARY KEY | Unique identifier (UUID) | +| user_id | Text | NOT NULL | Owner/creator of the skill | +| name | Text | NOT NULL | Display name of the skill | +| description | Text | nullable | Short description (used in manifest) | +| content | Text | NOT NULL | Full skill instructions (Markdown) | +| data | JSON | nullable | Additional skill data | +| meta | JSON | nullable | Skill metadata | +| is_active | Boolean | default=True | Active status | +| created_at | BigInteger | NOT NULL | Creation timestamp | +| updated_at | BigInteger | NOT NULL | Last update timestamp | + +Things to know about the skill table: + +- Uses UUID for primary key +- Access control is managed through the `access_grant` table (resource_type `skill`) +- `description` is injected into the system prompt as part of the manifest; `content` is loaded on-demand via the `view_skill` builtin tool + ## Tag Table | **Column Name** | **Data Type** | **Constraints** | **Description** | @@ -555,6 +577,7 @@ erDiagram user ||--o{ prompt_history : "creates" prompt ||--o{ prompt_history : "has" user ||--o{ tag : "creates" + user ||--o{ skill : "manages" user ||--o{ tool : "manages" user ||--o{ note : "owns" user ||--|| oauth_session : "has" @@ -757,6 +780,17 @@ erDiagram json meta } + skill { + text id PK + text user_id FK + text name + text description + text content + json data + json meta + boolean is_active + } + tool { string id PK string user_id FK