Writing the knowledge an AI assistant can actually find

You already know which facts are missing. This is how to write them: short cards, one question each, titled the way a customer would ask, specific enough to act on.

By · · 12 min read

Writing for an assistant is a different job from writing for your website. Website copy is written to be browsed. Someone lands on your shipping page, scans it, and pulls what they need out of a wall of text. Assistant knowledge is written to be retrieved. A short piece has to be selected out of everything you have written, on the strength of a question that may share almost no words with it, and then answer that question on its own with no page around it. Almost every rule below follows from that one difference. All of it assumes you already know which fact is missing. Working out whether a bad reply came from a fact nobody wrote or from a card that existed and was never reached is a diagnosis rather than a writing job, and it happens before any of this.

The title is the highest-leverage line in the card

Each piece of knowledge is a card with a topic line on top. Treat that line as the retrieval mechanism, because it is. A card that is not pinned enters a reply by its title: the customer's question is matched against your topic lines, and the ones that look relevant go into the prompt. The body produces the answer. The title decides whether the answer exists at all. That makes it the highest-leverage line in the card, and it is worth more of your time than the paragraph underneath it. It is also the reason a shop can have a correct policy written down and still watch the assistant improvise around it: that is a retrieval failure rather than a content one, it is diagnosed elsewhere, and everything on this page is what you do once the diagnosis says the title was the problem.

So title it the way a customer would ask it. "How long does delivery take" is a good title. "Logistics" is not. "Shipping and fulfillment policy" is worse, because it is written in the vocabulary of the person who runs the warehouse, and no customer types the word fulfillment into a chat box. Here is the same knowledge titled badly and titled usefully:

If the same question arrives in genuinely different words, that is a reason to write a second card, not to stuff both phrasings into one title with a slash in it. And if you sell something customers name in two ways, put the customer's word in the title and your internal word in the body, not the other way around.

A correct answer under a bad title is invisible, and it fails quietly. Nothing errors. The assistant answers from something else, while the fact sits in your knowledge base written correctly and never gets read.

One topic per card

A single page covering shipping, returns and payment gets pulled in for all three questions and answers none of them well. It is too long, so the one line the customer needed is buried between two policies they did not ask about. It is also too broad, so its title ends up being something like "Store policies", which matches everything and therefore means nothing.

Split until each piece answers one question. Shipping cost is one card. Delivery time is another. The returns window is a third, and who pays return postage is a fourth if that is not obvious from the third. This will feel like too many cards. It is the right number. Twenty short cards with sharp titles get found more often than five long ones, because the retrieval step is choosing between titles rather than reading your handbook.

Numbers, not adjectives

"Fast delivery, and returns are easy" is not knowledge. It is a slogan, and an assistant handed a slogan will either refuse or fill the gap itself. The same content written to be used: "Delivery is 2 to 3 working days to a home address, ₪25, free over ₪200. Orders placed after 14:00 ship the next working day." The first version cannot answer a single real question. The second answers four, and it answers them the same way twice.

Do the same to a returns line. "Easy returns" becomes "Returns accepted within 14 days of delivery, unopened and in the original packaging. You pay return postage, ₪20 if you use our courier label. Refunds are issued to the original payment method within 5 working days of the parcel arriving back." That version can be quoted to a customer who is deciding whether to buy, and it can be quoted back to you a month later without embarrassing anybody.

Every threshold, price and day count you leave vague becomes a place where the assistant either refuses or guesses, and a guess about your refund window is a promise you then have to keep. Before you save a card, check that it commits to the things a customer would have to know to act:

Write the exception down

The exceptions are the whole reason you are writing anything. The general rule is usually on your website already. What is written nowhere is that wholesale accounts always get free shipping, that opened skincare cannot be returned, that the wool coat runs one size small, that 12 kg sacks cannot be sent to a pickup point. Those live in your head and in your team's habits, which means the assistant does not have them. Places they tend to hide:

Unwritten exceptions are what gets answered wrongly in public. The assistant applies the general rule with confidence, because the general rule is all it was given, and the customer holds you to it. Put the exception in the card that carries the rule it modifies, in the same breath: "Returns within 14 days, unopened, in original packaging. Skincare and pierced earrings cannot be returned once opened." One card, rule and exception together, so they can never be retrieved apart. An exception written in its own card is an exception that can be found without its rule, and then quoted at a customer it does not apply to.

Never write "answer this, then hand off"

A card that says "explain how repairs work and then pass the customer to a human" looks sensible and is a trap. What happens in practice is that the customer gets the handoff line and loses the answer. The handoff fires, its message replaces the reply, and the three careful sentences you wrote about repairs never reach anybody. You have taken your best content and hidden it behind a transfer.

Decide which one the situation deserves, and write only that. Either it is a question you want answered, in which case write the answer and say nothing about handing off, or it is a question that needs a person, in which case the card says that and nothing else. This is a rule about writing cards. Where a handoff goes, who it alerts and which topics should trigger one are separate decisions, made outside the card.

One language per card

Mixed-language content produces mixed-language replies. A card with a Hebrew title and a half-English body comes back as an answer that switches mid-sentence, or as an answer in the wrong language entirely. The assistant answers in the customer's own language, and it does that cleanly when the source it is reading is clean.

If you sell in two languages, write the card twice, once in each, title included. Titles matter more than bodies here: a card whose body is in Hebrew but whose title is in English will not be retrieved for a Hebrew question at all. Keep the formats native too. Number, currency and date written the way that market reads them, so the answer is something a customer can act on rather than translate. How those replies then behave once they arrive somewhere, particularly the way right-to-left text renders on a phone, is a channel problem rather than a card problem and is dealt with where the channel is.

Keep the pinned set small

Some cards are pinned, meaning they go into every reply no matter what was asked. Everything else earns its way in by topic. The pinned set is where otherwise good setups go wrong, because pinning feels like insurance and does the opposite. The always-on set should be tone, ground rules, and the handful of things that belong in every single reply:

That is four to six cards. When ten policies are pinned, every reply gets written against a wall of mostly irrelevant instruction. Answers get longer and hedgier, the model spends attention on your returns policy while the customer asked about a strap, and you pay for those tokens on every message including the ones that just say hello. A bloated always-on set makes every reply worse and costs more. The test: if you cannot explain why a card must appear in a reply about a completely unrelated topic, it should not be pinned. Your returns policy is important and still fails that test, because it is only important when somebody asks about returns.

What not to write at all

Your catalog is imported. Product names, variants, prices and availability come from that import, not from anything you type. Do not retype any of it into a card. A card listing your ten bestsellers with prices is correct on the day you write it, wrong after the next price change, and harmful in between, because it contradicts the imported catalog and the assistant now holds two answers to the same question.

The same applies to discount codes. On a connected Shopify store the assistant reads your real active discounts and quotes only codes that exist, so a card listing last month's promotion gives it a code to offer that your checkout will reject. Write instead the things no database holds: policy, judgment, exceptions, how to choose between two products, what to say to someone who is unhappy, when a discount is worth offering at all. Let the catalog be the catalog. If you catch yourself typing a number another system already knows, stop typing.

Cards that have to say no

Most advice about knowledge assumes every card carries an answer. A working set also carries refusals, and those are the hardest ones to write, because the instinct is either to over-explain or to sound like a notice pinned to a door. A refusal card has two jobs. State the limit as a fact rather than an apology, and give the customer the next thing to do. "We cannot ship batteries by air, so this item is domestic only" is a fact somebody can act on. "Unfortunately we are unable to accommodate this request at the present time" is a sentence that has said nothing and made a person read it anyway.

Include the reason only where the reason helps. A customer told that opened skincare cannot come back for hygiene reasons stops arguing. A customer told that an exception cannot be made because of company policy starts. And keep the refusal inside the card that carries the rule it comes from rather than giving it a card of its own, for the same reason exceptions belong beside their rules: a no that can be retrieved on its own will eventually be quoted at somebody it never applied to, and that person will be right to be annoyed about it.

Fix from transcripts, not from imagination

The most efficient content work is not a writing session. It is reading what the assistant got wrong yesterday, writing the fact that was missing, and moving on. You can read the conversation transcripts and the per-message traces. Every wrong reply a real customer produced is a card you now know you need, with the title handed to you in their words.

Use their phrasing exactly. If four people asked "does it come with a charger", that is the title, not "accessories included". Every hour spent guessing at content is an hour not spent on questions customers demonstrably asked, and guesses land on the topics you find interesting rather than the ones that keep arriving. How often you read transcripts, and what you measure while you are in there, is a separate question from what you write when you find a gap.

Where the card discipline stops paying

If you sell thirty products and customers ask you four things, do not build a card system. Write those four answers, check them against real questions, and stop. This discipline pays off at the scale where you can no longer hold your own policies in your head. Below that, it is procrastination with a tidy structure.

Splitting can also be taken too far. A one-sentence card sitting alone with no context around it produces a curt reply that reads like a vending machine. If the honest answer to "how long does delivery take" is three sentences because home delivery, pickup points and international all differ, write three sentences. The rule is one question per card, not one fact per card.

Some answers should not be written for an assistant at all. When the reply depends on medical, legal or financial specifics, on a photograph of a damaged item, or on a judgment call about whether to bend a rule for a long-standing customer, the correct card is short and says a person will take it from here. A clever card in that spot does not save you work. It produces a confident answer you never authorized.

And no card fixes a question the assistant cannot answer in principle. There is no lookup of an individual customer's order here, so a card about it only produces a better-worded version of the same refusal. Write one short one that sends those conversations to a person or to your tracking page, then leave the topic alone and put your writing hours where they change an answer. Whether the volume behind that question should have stopped you buying anything at all is a decision taken before the first card is written, not something the writing can rescue.

Common questions

How many knowledge cards does an AI chatbot need?

Start with 15 to 30 short cards: shipping, returns, payment, sizing or usage, and the exceptions to each. The count matters less than the split. One question per card, each titled the way a customer would ask it. Products, prices and stock do not need cards at all, because those come from the imported catalog.

How long should each knowledge card be?

Long enough to answer one question completely, which is usually 40 to 150 words. If a card would need two headings, it is two cards. If it is a single line, check that the answer really is that short rather than underwritten, because a one-line card produces a curt reply with no context around it.

Can I paste my shipping page into the knowledge base?

Start there, but rewrite it. Website pages are written to be browsed, and knowledge cards are selected by title and read on their own, so a long policy page gets retrieved for every shipping-adjacent question and answers none of them precisely. Split it into one card per question, title each the way a customer would ask, delete the navigation and marketing lines, and add the exceptions your public page leaves out.

What should I do if I sell in more than one language?

Write each answer separately in each language, title included, and keep every card in a single language throughout. Mixed-language cards produce replies that switch language mid-sentence or answer in the wrong one. The assistant answers in the customer's own language, and it does that reliably only when the source card is clean.

Should I write product descriptions and prices into knowledge cards?

No. The catalog import supplies product names, variants, prices and availability. A card repeating that data is correct the day you write it and wrong after the next price change, and while it is wrong it contradicts the imported catalog. Write policy, judgment and exceptions instead, and let the catalog handle the products.