docs(kai): document context files, skill files, and API/CLI management - #1085
Conversation
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8
keboola-pr-reviewer-bot
left a comment
keboola-pr-reviewer-bot
left a comment
There was a problem hiding this comment.
Verdict: needs_human (risk 2/5) · profile docs
Needs human — well-formed docs PR but introduces unverifiable Kai product-behaviour claims that policy forbids auto-approving.
Concerns:
src/content/docs/kai/settings.md: New Kai product-behaviour claims (tags, 50KB/10-file limits, CLAUDE.md, shadowing) unverifiable from diffsrc/content/docs/kai/settings.md: API-vs-UI frontmatter-enforcement claim needs product-team confirmation
Suggested reviewers: @keboola/docs
| 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. |
There was a problem hiding this comment.
I think it's Kai Agent in settings now, not kai assistant.
There was a problem hiding this comment.
Fixed in 0c7f756 — verified against kbc-ui: the tab title follows the project's Kai branding (useKaiName), so it's Kai Agent on upgraded projects (the only ones with context/skill files) and Kai Assistant on legacy ones. Renamed all four references and noted the legacy label once at first mention.
Generated by Claude Code
| kbagent storage file-delete --project myproj --file-id 12345 --yes | ||
| ``` | ||
|
|
||
| ### Keeping a Context File in Sync Automatically |
There was a problem hiding this comment.
Maybe this deserves an accompanying skill
There was a problem hiding this comment.
We actually built exactly that (a bundled kai-customization skill in kai-agent, keboola/ui#7690) and then deliberately dropped it: a second copy of this how-to living in a repo the docs team never touches would drift — this page is now the single source of truth, and Kai reaches it via docs_query (its prompt routes all capability/customization questions there). If a skill still feels valuable, the drift-safe shape would be a downloadable example skill file linked from this section (a user uploads it to their own project) rather than a bundled one — deferring that call to @davidesner as a follow-up so it doesn't hold this page.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8
4 participants
Jira issue(s): SUPPORT-17235 / Linear AI-3693
Changes:
kai/settings) with three new sections: Context Files (kai-contextStorage tag,.md, 50 KB / 10-file limits,CLAUDE.mdhandling, managed in Settings → Kai Assistant), Skill Files (kai-skilltag,.md-with-frontmatter and.skillarchive formats,/slash-menu behavior, built-in shadowing), and Managing Files via API or CLI (Storage Files API +kbagentrecipes, plus the scheduled sync-pipeline pattern for keeping a standards document current).descriptionto the page frontmatter mentioning context/skill files so search and the docs RAG (docs_query) retrieve the page for those queries.Why: a customer asked Kai whether it supports context/knowledge files and Kai denied the feature exists — the docs don't cover it and
docs_queryreturns "I do not have sufficient information", so they built a Storage-table workaround (SUPPORT-17235). Companion change teaching Kai itself about the feature: keboola/ui#7690.Facts verified against the implementation in
keboola/ui(apps/kai-agent/src/services/context-files.ts,sandbox-executor.ts,apps/kbc-ui/.../KaiAgentTab/);kbagentcommand syntax matches_data/cli/command-reference.md(CLI gate passes: 0 findings).npm run buildclean (306 pages);audit-phase2.mjsreports no findings for this page.🤖 Generated with Claude Code
https://claude.ai/code/session_01A5e7tJ8L69Vgs5P49wU1U8
Generated by Claude Code