Kai Best Practices
Tips for working with Kai: give business context, plan before building, iterate, be specific, use dev branches, manage context, and keep security in mind.
Effective Prompting
Section titled “Effective Prompting”Provide Business Context
Section titled “Provide Business Context”Kai knows your schema but not your business rules. Include domain context for better results.
| Weak | Strong |
|---|---|
| ”Calculate Q3 revenue" | "Calculate Q3 revenue from orders where status = 'completed', excluding VAT in tax_amount" |
| "Show customer churn" | "Calculate monthly churn from subscriptions where end_date is not null and churn_reason != ‘upgrade’” |
Pro tip: Have Kai update your table metadata with business definitions—future queries benefit automatically.
Plan Before Building
Section titled “Plan Before Building”For complex tasks, ask Kai to outline its approach first:
"I need to build a customer lifetime value model. First outline which tables you'll use and how you'll join them. Don't execute anything yet."Iterate
Section titled “Iterate”Don’t expect production-ready code on the first try:
- Request initial approach
- Review output
- Refine: “Now optimize the join, add null handling, and include comments”
Be Specific
Section titled “Be Specific”| Vague | Specific |
|---|---|
| ”Fix the extractor" | "Analyze job failure for config keboola.ex-shopify (ID: 12345)—why is the refunds endpoint timing out?" |
| "Document this" | "Document transformation tr-customer-metrics for new team members, focusing on business logic” |
Development Workflow
Section titled “Development Workflow”Use Dev Branches
Section titled “Use Dev Branches”Test changes safely by creating a development branch in the Keboola UI, then working with Kai in that branch. Review changes before merging to production.
Manage Context
Section titled “Manage Context”- One topic per chatdon’t mix unrelated tasks
- Reset when stuckif Kai gets confused after 2-3 tries, start fresh with clearer context
- Let Kai read logsinstead of pasting, use
"Read the latest job log for ex-google-analytics" - Attach what Kai cannot reachfor security reasons Kai cannot open links, so upload a file rather than pasting a URL
- Compact rather than lose your placein a long session that is still on topic, run
/compactand name what has to survive the summary. It keeps the thread going where a new chat would drop everything. If the topic has actually changed, start a new chat instead — compacting carries context you no longer want
Security
Section titled “Security”- Let Kai handle credentials through secure configuration forms—never type secrets directly in chat
- Say “I’ll provide the API key when you prompt me” and Kai will use the secure configuration interface
- Review every tool approval before confirming
- Configure Tool Permissions to control which tools Kai can use—block tools you don’t need and set sensitive tools to Always ask
- Use dev branches for testing
- Paste credentials, API keys, or passwords in plain text chat messages
- Blindly approve actions
- Assume Kai knows about other projects (it only sees your current project)
What to Avoid
Section titled “What to Avoid”- Don’t argue with a confused Kaireset the conversation instead
- Don’t skip verificationalways review business logic, data quality rules, and production deployments
- Don’t expect cross-project knowledgeKai only sees your current project
- Don’t paste a link and expect Kai to read itfor security reasons Kai cannot open links. Attach the document to your message, or add it as a context file if you need it in every conversation
Team Tips
Section titled “Team Tips”- Save and share successful prompts with teammates
- Use Kai to onboard new team members:
"Give a new engineer an overview of this project's architecture" - Keep project documentation updated so Kai has better context for everyone
- Use thumbs up/down buttons to provide feedback
Was this page helpful?
Thank you for helping improve Keboola's documentation!