Write effective instructions
The tips below are based on experimentation and are not exhaustive. They cover the most common pitfalls we have seen when writing custom instructions, followed by proven patterns you can adapt to your use case.
Be specific
Vague instructions leave too much room for interpretation. The more precisely you describe the behavior you want, the more reliably the assistant will follow it.
Ask clarifying questions when needed.
When a user asks a question that could apply to multiple products in our catalog, list the products it could refer to and ask the user to specify which one before answering.
Be comprehensive
When an instruction lists the cases it handles, cover the full range of inputs your users will actually produce, or tell the model what to do when an input fits none of them. The model will force every input into one of the cases you listed, even inputs that fit none: faced with something the instruction did not anticipate, it picks the closest available case rather than recognizing that none applies.
When you cite a source, label it: use [Docs] for documentation pages and [GitHub] for [GitHub] issues or discussions.
When you cite a source, label it: use [Docs] for documentation pages and [GitHub] for GitHub issues or discussions. If a source is neither, label it as [Other].
Be careful with "never"
Absolute prohibitions can backfire. When given a hard constraint, AI models tend to find the nearest workaround that technically complies with the wording but misses the point. If you say "never use bullet points," the model may switch to numbered lists instead.
When you prohibit a behavior, also specify what the assistant should do instead:
Never use bullet points.
Do not use bulleted or numbered lists in your answers. Write in flowing prose instead.
Set reasonable scope
An instruction like "always respond in exactly three sentences" will produce poor results for complex technical questions. When setting constraints, calibrate to what is realistic across the full range of questions your users ask.
Always respond in exactly three sentences.
Keep answers concise. Use only as much length as the question genuinely needs.
Write each instruction to stand on its own
Instructions are not meant to trigger or reference each other. If two behaviors are related, express them together in a single instruction rather than splitting them across two.
Instruction A: When users ask about competitor products, do not provide comparisons.
Instruction B: When you decline to answer a question, suggest the user contact our sales team for more information.
When users ask about competitor products, do not provide comparisons. Suggest they contact our sales team for more information instead.
Avoid conflicting instructions
Make sure your instructions can all be satisfied at once. Two instructions that each sound reasonable on their own can pull in opposite directions when combined, and the model cannot fully honor both: it will trade one off against the other unpredictably, or land somewhere in between that satisfies neither. Before adding an instruction, check it against the ones you already have and resolve the tension yourself rather than leaving it to the model.
Telling the assistant to be both extremely concise and conversational is a common example. A conversational tone is naturally more verbose, so "extremely concise" and "conversational" pull against each other.
When writing instructions about conciseness, keep in mind that Kapa is designed first and foremost to give complete, exhaustive answers. An aggressive push toward brevity therefore conflicts not just with other instructions you add, but with Kapa's core behavior.
Use customizations sparingly
Every instruction added to the system instructions competes for the model's attention. A customization with a long list of instructions is harder for the model to follow consistently than one with a short, focused list.
The more instructions you add, the further you take Kapa from its default behavior, which means your customization is less covered by Kapa's extensive evaluations and testing. This also makes version upgrades harder, since more custom behavior needs to be re-verified each time. Use customizations sparingly and only add an instruction when you have a clear, recurring need. Whenever possible, not using a customization at all is preferable.
Common patterns
The examples below are starting points that you can take and adapt to your use case.
Formatting and terminology
Customizing formatting is useful when the assistant's default style does not match your brand voice, or when your product has a defined vocabulary that should not be translated.
Never use bulleted lists or numbered lists in your answer. Write in prose instead.
When responding in Chinese, the following technical terms must always remain in English and must not be translated: [term1], [term2], [term3].
When referring to the knowledge sources you draw from, call them "[Company] Documentation" rather than "the docs" or "the knowledge sources".
Adjusting tone
The two most common tone adjustments are conciseness and warmth, and they are not mutually exclusive. Pick one as your baseline and layer the other only if you have a reason.
Developers reading documentation often want direct, concise answers:
Keep answers as concise as possible. Skip preamble, don't restate the question, no closing pleasantries. Prefer omitting non-essential context over omitting the core answer.
For consumer-facing products where warmth matters:
Adopt a warm, conversational tone. Speak directly to the user in the second person. After answering, when a follow-up question would naturally help the user make progress, end with one short follow-up question.
Setting a deployment context
You can tell the assistant where it is deployed and who it is talking to. This is most useful when the assistant is embedded somewhere other than a standard documentation site, for example on a marketing page, in an onboarding flow, or in an internal tool.
You are on [Company]'s marketing website, talking to potential customers who are evaluating the product. When unsure about a detail, do not hedge with 'the docs don't state' language. Answer what you know and invite the user to connect with the team.
Act as an onboarding companion for [Product]. Be welcoming, encouraging, and patient. Prefer 'getting started' resources over deep technical references when both would answer the question.
Handling out-of-scope questions
Users rarely stay perfectly on topic. When a question falls outside what your assistant should handle, the right response is a clear redirect rather than silence or a hallucinated answer. For example, if a user asks a legal question that should go to your legal team, it is better to acknowledge the boundary explicitly and point them to the right contact than to let the assistant speculate.
Do not answer legal questions (terms of service, contracts, liability, compliance, etc.). Briefly tell the user that legal topics fall outside what you can help with and direct them to email legal@[company].com.
Do not tell the user to contact support, open a support ticket, or email the team. If the knowledge sources do not contain enough information to answer, state the limitation directly and stop.