communicationbusiness

Knowledge Base Article

Write self-service knowledge base articles that resolve customer issues without support contact — with clear titles, step-by-step solutions, troubleshooting trees, and SEO-friendly structure.

knowledge-basesupportself-servicehelp-centertroubleshooting

Works well with agents

Customer Success Manager Agent Support Engineer Agent Technical Writer Agent

Works well with skills

Bug Report Writing

$ npx skills add The-AI-Directory-Company/(…) --skill knowledge-base-article

knowledge-base-article/

SKILL.md

Markdown

1
2	# Knowledge Base Article
3
4	## Before you start
5
6	Gather the following from the user before writing:
7
8	1. What question or problem does this article answer? (Exact customer phrasing, not internal jargon)
9	2. Who is the reader? (End user, admin, developer, or mixed audience)
10	3. What product area does this cover? (Feature name, settings page, API endpoint)
11	4. What is the current resolution path? (Steps support agents follow today, existing macros or scripts)
12	5. Are there multiple causes or variations? (Different root causes that produce the same symptom)
13
14	If the user says "write an article about billing," push back: "Which billing problem? A KB article solves one specific issue. 'Why was I charged twice' is a different article from 'How to update my payment method.'"
15
16	## Article template
17
18	### Title
19
20	Use the format customers would type into a search bar. Start with "How to," "Why," or the symptom itself.
21
22	Good: "How to reset your password when the reset email does not arrive"
23	Bad: "Password Reset Functionality" or "Authentication Troubleshooting Guide"
24
25	Test: if a customer pastes the title into Google, it should match their intent exactly.
26
27	### Overview
28
29	1-2 sentences confirming the reader is in the right place. Restate the problem in plain language and preview the solution. Include the product area and approximate time to resolve.
30
31	```
32	If you requested a password reset email and it has not arrived after 5 minutes,
33	this article walks you through three checks to resolve it (about 2 minutes).
34	```
35
36	### Applies to
37
38	State the product version, plan tier, platform, or role this article covers. Customers who do not match should know immediately that this article is not for them.
39
40	### Step-by-Step Solution
41
42	Number every step. Each step must include:
43
44	- One action per step (click, navigate, enter, select)
45	- The exact UI label or menu path: Settings > Account > Security
46	- What the user should see after completing the step (confirmation message, changed state)
47	- A screenshot or annotated image reference where the UI is not obvious
48
49	Use conditional branches when the problem has multiple causes:
50
51	```
52	3. Check your spam/junk folder for an email from noreply@example.com.
53	- IF the email is in spam: Mark it as "Not spam," then click the reset link.
54	You are done — skip to Verification below.
55	- IF the email is not in spam: Continue to step 4.
56	```
57
58	Every branch must end at a resolution or route to the next diagnostic step. Never leave the reader stranded.
59
60	### Troubleshooting
61
62	Use a decision-tree format for cases where the primary solution does not work. Structure as symptom-then-action pairs:
63
64	\| Still seeing this? \| Try this \|
65	\|---\|---\|
66	\| Reset link says "expired" \| Request a new reset — links expire after 30 minutes \|
67	\| "Email not found" error \| Verify you are using the email tied to your account under Profile > Email \|
68	\| No error but no email after 15 min \| Contact support with your account email and the timestamp of your last attempt \|
69
70	### Related articles
71
72	Link 2-4 articles covering adjacent topics. Customers who landed on the wrong article should find the right one without going back to search.
73
74	## Quality checklist
75
76	Before delivering the article, verify:
77
78	- [ ] Title matches the phrase a customer would search for, not internal terminology
79	- [ ] Overview confirms the reader has the right article within the first two sentences
80	- [ ] Every step contains one action, the exact UI path, and the expected result
81	- [ ] Conditional branches resolve to a next step, a solution, or a support escalation
82	- [ ] Troubleshooting covers the top 3 failure modes after the primary solution
83	- [ ] "Applies to" section scopes the article to specific versions, plans, or roles
84	- [ ] No internal jargon remains — every term is one the customer would use or is defined on first use
85	- [ ] Related articles link to adjacent problems, not random content
86
87	## Common mistakes
88
89	- Writing for internal teams, not customers. "Clear the OAuth token cache and re-authenticate via SSO" means nothing to a non-technical user. Write "Log out, close your browser, open it again, and log back in."
90	- Combining multiple problems in one article. "Billing FAQ" with 12 questions gets poor search rankings and forces readers to scroll. One article, one problem.
91	- Skipping the 'Applies to' section. Customers on the free plan waste time following steps that require a paid feature. State the scope upfront.
92	- Instructions without verification. "Click Save" is incomplete. "Click Save. A green banner reading 'Settings updated' appears at the top of the page" lets the reader confirm success.
93	- Using screenshots as the only instruction. Screenshots go stale when the UI changes. Write the text instructions first; screenshots supplement, never replace.
94	- Forgetting the dead-end reader. If every troubleshooting path fails, the article must tell the reader exactly how to contact support and what information to include.
95