docs(kai): illustrate Kai Settings and explain what each level is for - #1107
Conversation
Every card in Settings → Kai Agent now has a screenshot, and the three permission levels have their icons. Tool Permissions says explicitly that the settings are personal, so nobody blocks a tool believing they have secured it for the team. System Instructions leads with concrete rules rather than "persistent context and guidelines", and says which of the three mechanisms to reach for: instructions for short rules, context files for longer knowledge, skill files for a procedure you call. Context Files gains a complete worked example. The section previously listed four things you could put in a context file without showing one, even though the format is free-form Markdown. Skill Files gains how a skill gets called, with the slash-command menu, and what to write one for. Also corrects the context-file upload step: the card has no Upload button, it offers drag and drop or Select Files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The distinction was a subordinate clause in the opening sentence and never said why it matters. It is now a callout answering the question directly: a context file is read every conversation and costs context window space, a skill only when called or matched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
| ## Business rules | ||
|
|
||
| - The fiscal year starts in April. | ||
| - Revenue excludes VAT and any order with `status = 'cancelled'`. | ||
| - An active customer has placed an order in the last 90 days. | ||
|
|
||
| ## Glossary | ||
|
|
||
| - **ARR** is annual recurring revenue and excludes one-off services. | ||
| - **Churn** means no order in 180 days, not a cancelled contract. |
There was a problem hiding this comment.
This should live in Semantic Layer, it is not ideal example. Replace with some data engineering best practices -> e.g. "When writing transformation code avoid using deep CTEs and rather split the query into more intermediate (staging) tables for clarity before assembling the final output table." -> add more similar examples.
There was a problem hiding this comment.
Addressed in ba3a6fa. ## Business rules and ## Glossary are gone from the example, replaced with data engineering conventions:
## Transformations— leads with the deep-CTE/staging-table rule, plus materializing anything more than one transformation reads, filtering and deduplicating before joining, noSELECT *into a shared output table, and PK + watermark for incremental loads.## Integrations— check for an existing connector first, and prefer a Custom Python component over the Generic Extractor for a new one.
Also pulled the business-glossary and data-model framing out of the surrounding prose, so the page recommends business semantics nowhere: the System Instructions lede no longer uses "our fiscal year starts in April", the project-level example is pipeline conventions rather than "project context", and all three descriptions of context files now say "data standards and project-wide conventions". An API reference is no longer suggested as always-on context either — single-task reference material now points at skill files, which load on demand.
No semantic layer pointer added, since help docs have no semantic layer page to link to.
One leftover: line 68 still gives "Write SQL transformations using CTEs instead of subqueries" as a coding-standard example, which sits oddly next to the deep-CTE rule now in the context-file example. Not contradictory, but worth a reword if you want them consistent.
| ## 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. | ||
| A skill is a playbook Kai runs when you need it. Skills appear in the chat's **`/` slash-command menu** alongside Kai's built-in skills. Use them for longer, task-specific instructions such as "build the monthly report" or "onboard a new data source". |
There was a problem hiding this comment.
Done in ba3a6fa. Added to the Skill Files intro: "Kai skills use the open Agent Skills format: a Markdown file with name and description frontmatter, optionally packaged with the supporting files it references."
| pages rather than paragraphs. This is what `.skill` archives are for: a `SKILL.md` plus | ||
| reference files it can read when needed. | ||
|
|
||
| Skills are project-wide, so one person can encode the standard once and the whole team gets |
There was a problem hiding this comment.
Reference official agent skills best practice https://agentskills.io/skill-creation/best-practices
There was a problem hiding this comment.
Done in ba3a6fa. Added at the end of "What to write a skill for": a pointer to best practices for skill creators, framed as how to structure SKILL.md, how long to make it, and when to move detail into separate reference files.
| This is why the `description` matters more than anything else in the file. Kai matches | ||
| against it, and the menu shows it to whoever is choosing. Write what the | ||
| skill does, then when to use it, including the words your team actually types. A good one is | ||
| long and specific: |
There was a problem hiding this comment.
This is why the description matters more than anything else in the file -> Not really true. Description matters the most for agent invoked skills (progressive disclosure).
There was a problem hiding this comment.
Corrected in ba3a6fa. The "matters more than anything else in the file" claim is gone. It now reads:
Kai reads only each skill's
nameanddescriptionup front, then loads the body when it decides the skill applies (progressive disclosure). That makes thedescriptiondecisive for skills Kai invokes itself. Write what it does, then when to use it, in the words your team actually types:
So the weight is scoped to agent-invoked skills, and progressive disclosure is named.
- Replace the business-rules/glossary example in the context file with data engineering conventions (transformations, integrations); business semantics and data model documentation belong in the semantic layer, not here. - Drop the remaining business-glossary and data-model framing from the System Instructions and Context Files prose so the page recommends them nowhere. - Stop suggesting an API reference as always-on context; point single-task reference material at skill files, which load on demand. - Correct the claim that `description` matters more than anything else in a skill file: it is decisive for skills Kai invokes itself (progressive disclosure). - Reference the open Agent Skills format and its best practices for skill creators.
Uploaded project skills appear under `/`; Kai's built-in skills are model-invoked only and are not listed there.
This branch was successfully deployed
2 participants
Jira issue(s): PROOF-XXX
Kai Settings had one screenshot for four cards, and the two sections about giving Kai knowledge never showed what that knowledge looks like. This adds the missing images and fills those gaps.
Changes:
CLAUDE.mdnaming tip, which was buried as a clause in the limits list./menu but never mentioned that Kai also calls them on its own, which the card itself states ("Invoked on demand when relevant").The example
descriptionquoted in Skill Files is real, taken from a workingscrollytelling-data-app.skill, and it is the same skill shown in the slash-menu screenshot.Verified:
npm run buildclean (362 pages),audit-phase2.mjsreports 0 missing images and no broken links from this page. All screenshots are real product captures.@davidesner — three things worth your eye:
The docs claim a 10-file limit for both context files and skill files. Neither card mentions it, though both state the
.mdformat and the 50 KB size. Is that cap still real?I removed a "Built-in skills" subsection before opening this. It said Kai ships with skills from
keboola/ai-kitand linked the repo. AI-3666 and AI-3668 describe vendoring specific ai-kit skills into the sandbox rather than the whole repo, and I could not establish which ones, so I cut it rather than guess. The limits list still says a project skill "with the same name as a built-in skill replaces the built-in one", which references built-ins the page never explains. Worth a sentence once someone can name them.The UI uses sentence case for the tabs — "Tool permissions", "System instructions" — where the docs use title case throughout. Left alone here since it is page-wide, not something this PR introduced.
Em dashes are untouched in the pre-existing text, pending the consistency pass we discussed on #1105.