From c43a7217189cdd465da233499b142fd6920280c9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 12:39:10 +0000 Subject: [PATCH 1/3] docs(kai): document context files, skill files, and API/CLI management Customers could not discover Kai context files (kai-context tag) and skill files (kai-skill tag): the docs did not mention them, and Kai's docs-backed answers denied the feature exists (SUPPORT-17235 / AI-3693). Extends the Kai Settings page with: - Context files: format, 50 KB / 10-file limits, CLAUDE.md handling, Settings -> Kai Assistant management - Skill files: .md frontmatter and .skill archive formats, slash-menu behavior, built-in shadowing - Managing both via the Storage Files API or kbagent, including the scheduled sync-pipeline pattern for keeping a standards doc current Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8 --- src/content/docs/kai/settings.md | 111 ++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) diff --git a/src/content/docs/kai/settings.md b/src/content/docs/kai/settings.md index 4e2210a00..8a1ac6a41 100644 --- a/src/content/docs/kai/settings.md +++ b/src/content/docs/kai/settings.md @@ -1,13 +1,14 @@ --- title: Kai Settings slug: 'kai/settings' +description: Configure Kai's tool permissions, system instructions, context files (knowledge files), and skill files — in the UI or programmatically via the Storage Files API. --- Kai's settings let you personalize how Kai behaves in your project. Open the Kai chat panel and click the **Settings** icon (gear) to access them. Settings are **per-user and per-project**, so each team member can configure their own preferences independently. -The settings panel has two tabs: **Tool Permissions** and **System Instructions**. +The settings panel has two tabs: **Tool Permissions** and **System Instructions**. Project-wide customization — project-level instructions, [context files](#context-files), and [skill files](#skill-files) — is managed in **Settings → Kai Assistant** in the main Keboola navigation. ## Tool Permissions @@ -93,3 +94,111 @@ This means user-level instructions can refine or add to the project-level instru - Update instructions as your project evolves and conventions change. - Focus on rules Kai can't infer from your project data alone (e.g., business logic, team preferences). - If Kai doesn't seem to follow an instruction, try rephrasing it more directly. +- For knowledge that outgrows the 4,000-character limit — data standards documents, business glossaries — use [context files](#context-files) instead. + +## Context Files + +Context files (also called knowledge files) are Markdown documents that Kai reads automatically at the start of every conversation. Use them to give Kai project knowledge that is too long for system instructions: data standards, naming conventions, business glossaries, or documentation of your data model. + +To manage them, go to **Settings → Kai Assistant** in the main Keboola navigation and use the **Context files** card: + +1. Click **Upload** and select a Markdown (`.md`) file. +2. The file is uploaded and takes effect in every **new** conversation (running conversations are not affected). +3. To replace a file, upload the new version and delete the old one. + +Rules and limits: + +- **Format:** Markdown (`.md`) only. +- **Size:** up to **50 KB** per file. +- **Count:** up to **10 files** per project. +- A file named `CLAUDE.md` becomes Kai's top-level memory file; all other files are loaded as always-on rules alongside it. +- Context files apply **project-wide** — every user's conversations include them. + +:::tip +Every context file is read in every conversation, so keep the set small and focused. One well-structured standards document usually works better than many overlapping files. +::: + +Under the hood, context files are ordinary [Storage Files](/storage/files/) tagged **`kai-context`**, which means you can also manage them programmatically — see [Managing Files via API or CLI](#managing-files-via-api-or-cli). + +## Skill Files + +Skills are reusable, on-demand playbooks that appear in the chat's **`/` slash-command menu** alongside Kai's built-in skills. Unlike context files, Kai loads a skill only when it is invoked — making skills the right place for longer, task-specific instructions (e.g., "build the monthly report," "onboard a new data source") that shouldn't consume context in every chat. + +Manage them in **Settings → Kai Assistant** using the **Skill files** card. Two formats are accepted: + +1. **A single `.md` file** starting with YAML frontmatter. The `name` and `description` fields are required — the description tells Kai when to invoke the skill: + + ```markdown + --- + name: monthly-reporting + description: Build the monthly revenue report. Use when the user asks for the monthly report or KPI refresh. + --- + + # Monthly reporting + + Step-by-step instructions for Kai... + ``` + +2. **A `.skill` archive** — a ZIP file with a `SKILL.md` at its root (or at the root of a single top-level directory), plus any supporting files the skill references. + +Rules and limits: + +- **Size:** up to **50 KB** per file. +- **Count:** up to **10 skill files** per project. +- A project skill with the same `name` as a built-in skill replaces the built-in one. + +Skill files are Storage Files tagged **`kai-skill`**. + +## Managing Files via API or CLI + +Because context and skill files are ordinary Storage Files identified by a tag (`kai-context` or `kai-skill`), any Storage API client can manage them. Upload with the tag and the **permanent** flag (so the file never expires): + +List current files by tag: + +``` +GET https://connection.{stack}/v2/storage/files?tags[]=kai-context +X-StorageApi-Token: {token} +``` + +Upload a new file (Storage import service, multipart form — see the `?service=import` section of your stack's [API reference](https://keboola.docs.apiary.io/)): + +``` +POST https://import.{stack}/upload-file +X-StorageApi-Token: {token} +Form fields: data=@data-standards.md, tags[]=kai-context, isPermanent=1 +``` + +Delete a file by ID: + +``` +DELETE https://connection.{stack}/v2/storage/files/{fileId} +X-StorageApi-Token: {token} +``` + +Or use [kbagent, the Keboola CLI](/cli/): + +```bash +kbagent storage files --project myproj --tag kai-context +kbagent storage file-upload --project myproj --file data-standards.md --tag kai-context --permanent +kbagent storage file-delete --project myproj --file-id 12345 --yes +``` + +### Keeping a Context File in Sync Automatically + +A common pattern: your team maintains a standards document in its own repository or wiki, and a scheduled job keeps Kai's copy current. Kai then answers standards questions from the actual document, and it stays up to date without manual re-uploads. + +On each run, the sync job should: + +1. **List** files tagged `kai-context` and note the ID(s) of the current copy (match by file name). +2. **Upload** the fresh version with the `kai-context` tag and the permanent flag. +3. **Delete** the old file ID(s) from step 1. + +Upload-then-delete (rather than delete-then-upload) ensures a conversation starting mid-sync still finds a copy. Deleting the old copy is required: Kai loads at most 10 tagged files, and both revisions would otherwise be loaded together. + +The job can run anywhere — a CI pipeline triggered on changes to the source document, or a scheduled Keboola flow with a Python step calling the Storage API. It only needs a Storage API token with file write permissions. The same pattern works for skill files using the `kai-skill` tag. + +### Troubleshooting + +- **File uploaded but Kai doesn't see it** — check that the tag is exactly `kai-context` or `kai-skill`, the file is under 50 KB, there are at most 10 tagged files, and the conversation was started *after* the upload. +- **Skill missing from the `/` menu** — the `.md` frontmatter must contain both `name` and `description`; a `.skill` archive must contain `SKILL.md` at its root. +- **File expired or disappeared** — it was uploaded without the permanent flag; re-upload it as permanent (uploads from the Settings UI are always permanent). From f656f73dd520a531cb37ceb0305f1cadaf6be027 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 14:04:57 +0000 Subject: [PATCH 2/3] docs(kai): fix skill troubleshooting symptom description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A skill file without frontmatter still appears in the / menu (API uploads skip validation; the backend falls back to a filename-derived name) — the real symptom is a missing description / wrong name, not absence from the menu. Also mention the single-top-level-dir archive layout. Raised by review on keboola/ui#7690, where the same wording originated. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8 --- src/content/docs/kai/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/kai/settings.md b/src/content/docs/kai/settings.md index 8a1ac6a41..0682140b5 100644 --- a/src/content/docs/kai/settings.md +++ b/src/content/docs/kai/settings.md @@ -200,5 +200,5 @@ The job can run anywhere — a CI pipeline triggered on changes to the source do ### Troubleshooting - **File uploaded but Kai doesn't see it** — check that the tag is exactly `kai-context` or `kai-skill`, the file is under 50 KB, there are at most 10 tagged files, and the conversation was started *after* the upload. -- **Skill missing from the `/` menu** — the `.md` frontmatter must contain both `name` and `description`; a `.skill` archive must contain `SKILL.md` at its root. +- **Skill shows without a description, under a wrong name, or Kai doesn't invoke it** — add `name` and `description` to the `.md` frontmatter. Uploads from the Settings UI enforce the frontmatter, but API uploads don't — a file without it still appears in the `/` menu under a name derived from its file name, with no description to tell Kai when to use it. A `.skill` archive must contain `SKILL.md` at its root (or at the root of a single top-level directory). - **File expired or disappeared** — it was uploaded without the permanent flag; re-upload it as permanent (uploads from the Settings UI are always permanent). From 0c7f756b34781d4e8da0d34868149cc2886b5bf2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Aug 2026 13:07:16 +0000 Subject: [PATCH 3/3] docs(kai): settings tab is labeled Kai Agent on upgraded projects The tab title follows the project's Kai branding (useKaiName in kbc-ui): "Kai Agent" with the new engine, "Kai Assistant" on legacy projects. Context/skill files only exist on upgraded projects, so use the Kai Agent label throughout and note the legacy name once. Raised by review on the PR. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8 --- src/content/docs/kai/settings.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/kai/settings.md b/src/content/docs/kai/settings.md index 0682140b5..24cfee97c 100644 --- a/src/content/docs/kai/settings.md +++ b/src/content/docs/kai/settings.md @@ -8,7 +8,7 @@ description: Configure Kai's tool permissions, system instructions, context file Kai's settings let you personalize how Kai behaves in your project. Open the Kai chat panel and click the **Settings** icon (gear) to access them. Settings are **per-user and per-project**, so each team member can configure their own preferences independently. -The settings panel has two tabs: **Tool Permissions** and **System Instructions**. Project-wide customization — project-level instructions, [context files](#context-files), and [skill files](#skill-files) — is managed in **Settings → Kai Assistant** in the main Keboola navigation. +The settings panel has two tabs: **Tool Permissions** and **System Instructions**. Project-wide customization — project-level instructions, [context files](#context-files), and [skill files](#skill-files) — is managed in **Settings → Kai Agent** in the main Keboola navigation (the tab is labeled **Kai Assistant** in projects not yet upgraded to the new Kai engine). ## Tool Permissions @@ -50,7 +50,7 @@ System Instructions let you provide Kai with persistent context and guidelines s Project-level instructions apply to **all users** in the project. They are managed in the project settings: -1. Go to **Settings → Kai Assistant** in the main Keboola navigation. +1. Go to **Settings → Kai Agent** in the main Keboola navigation. 2. Enter your instructions in the **System instructions** text field. 3. The instructions auto-save. @@ -100,7 +100,7 @@ This means user-level instructions can refine or add to the project-level instru Context files (also called knowledge files) are Markdown documents that Kai reads automatically at the start of every conversation. Use them to give Kai project knowledge that is too long for system instructions: data standards, naming conventions, business glossaries, or documentation of your data model. -To manage them, go to **Settings → Kai Assistant** in the main Keboola navigation and use the **Context files** card: +To manage them, go to **Settings → Kai Agent** in the main Keboola navigation and use the **Context files** card: 1. Click **Upload** and select a Markdown (`.md`) file. 2. The file is uploaded and takes effect in every **new** conversation (running conversations are not affected). @@ -124,7 +124,7 @@ Under the hood, context files are ordinary [Storage Files](/storage/files/) tagg Skills are reusable, on-demand playbooks that appear in the chat's **`/` slash-command menu** alongside Kai's built-in skills. Unlike context files, Kai loads a skill only when it is invoked — making skills the right place for longer, task-specific instructions (e.g., "build the monthly report," "onboard a new data source") that shouldn't consume context in every chat. -Manage them in **Settings → Kai Assistant** using the **Skill files** card. Two formats are accepted: +Manage them in **Settings → Kai Agent** using the **Skill files** card. Two formats are accepted: 1. **A single `.md` file** starting with YAML frontmatter. The `name` and `description` fields are required — the description tells Kai when to invoke the skill: