support knowledge base structure that agents actually use

TL;DR

Agents use a knowledge base when they can find the answer in under 30 seconds. That means a flat structure organized by customer problem (not by your org chart), a search box that actually works, and articles that start with the answer instead of background. Every article gets an owner and a review date, or it rots. The structure matters less than the search and the freshness, so optimize for those two.

The query

support knowledge base structure that agents actually use

Use this when

• Building a knowledge base from scratch
• Agents never open the existing KB
• Reorganizing a KB that grew into a mess
• Connecting KB content to agent or AI search

Not for

• Public customer help centers (related, different audience)
• API reference documentation
• Marketing or product documentation sites
• Internal company wikis

Steps

1. Organize by customer problem, not by team

Top-level categories like Billing, Logins, Exports, Integrations. Not Engineering, Product, Ops. Agents search by what the customer is asking about.

Expected output: a category list where every category is a thing a customer would complain about.

2. Keep it flat: two levels max

Category, then articles. No sub-sub-folders. Deep trees hide articles; flat structures plus search surface them.

Expected output: no article more than two clicks from the home page.

3. Make search the front door

The search box is the home page. Invest in it: index article titles and symptom phrases, not just body text. Test it with the actual queries agents type.

Expected output: the top 20 agent queries each return the right article in the top 3 results.

4. Give every article the same anatomy

Symptom (what the customer says), answer (the fix, first), steps, edge cases, related articles. The answer goes first, always. Agents scan, they dont read.

Expected output: an article template every author uses, with the answer above the fold.

5. Assign every article an owner and a review date

Stale articles are worse than no articles, they teach agents wrong answers. Owner plus 90-day review date on every article, enforced by a report of overdue reviews.

Expected output: zero articles without an owner, zero overdue reviews.

6. Measure usage and prune

Track article views from tickets. Articles nobody opens get archived. Articles everybody opens but that dont resolve tickets get rewritten.

Expected output: a quarterly prune driven by usage data, not opinions.

Article template

Title: [customer symptom phrasing], e.g. export comes out blank

Answer: [the fix in 2-3 sentences]

Steps:
1. ...
2. ...

Edge cases: [when this answer doesnt apply]

Related: [links to 2-3 related articles]

Owner: [name] | Last reviewed: [date] | Next review: [date]

Variant phrasings

how to organize a support knowledge base

Steps 1 and 2. Problem-based categories, two levels deep, search as the front door.

knowledge base best practices for support teams

All six steps. The differentiator is steps 5 and 6: ownership and pruning are what separate a KB agents use from a KB that is a write-only archive.

internal knowledge base structure for customer support

Same structure. Keep it internal-only in tone: agents can handle blunter language and internal links that customers should never see.

Why it happens

Knowledge bases rot because they are organized for the people who write them (teams, products, features) instead of the people who read them (agents with a customer on the line). And they die because nobody owns freshness. The structure in this skill is boring on purpose: the value is in search quality and review discipline, not in clever taxonomy.

Edge cases

• Migrating from a messy KB: dont reorganize everything at once. Fix the top 20 articles first, archive the dead 50 percent, then restructure around what is left.
• AI agents reading the KB: the same anatomy works. Symptom-first titles and answer-first bodies are exactly what retrieval needs.
• Multiple products: one KB with product tags beats one KB per product. Agents support whatever the customer has, they should not have to pick a silo first.
• Sensitive content: keep internal-only articles clearly marked and access-controlled, but in the same search. Agents should find them, customers should not.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_caHf1YkspTE1OGs8o7rXRw