📋 Kai Best Practices

Effective Prompting

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

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

Don’t expect production-ready code on the first try:

1. Request initial approach
2. Review output
3. Refine: “Now optimize the join, add null handling, and include comments”

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

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

• 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 /compact and 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

Do

• 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

Don’t

• 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

• 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

• 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