Kb Article

What This Skill Does

This skill drafts a publish-ready knowledge base article from various sources like resolved support issues or common questions. It structures the content for optimal searchability and self-service, benefiting support teams and end-users.

When to Use

• Document a solution to a recurring customer issue.
• Create a how-to guide for a frequently asked question.
• Formalize a workaround for a known product bug.
• Convert a resolved support ticket into a help article.
• Update an existing article with new information.
• Proactively address common user questions.

Key Features

• Parses input to identify key elements of the article.
• Follows templates for different article types.
• Applies searchability best practices.
• Formats content for scannability.
• Suggests appropriate metadata for the article.
• Checks for existing articles to avoid duplication.

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

Draft a publish-ready knowledge base article from a resolved support issue, common question, or documented workaround. Structures the content for searchability and self-service.

Usage

/kb-article <resolved issue, ticket reference, or topic description>

Examples: /kb-article How to configure SSO with Okta — resolved this for 3 customers last month /kb-article Ticket #4521 — customer couldn't export data over 10k rows /kb-article Common question: how to set up webhook notifications /kb-article Known issue: dashboard charts not loading on Safari 16

Workflow

1. Understand the Source Material

Parse the input to identify:

What was the problem? The original issue, question, or error What was the solution? The resolution, workaround, or answer Who does this affect? User type, plan level, or configuration How common is this? One-off or recurring issue What article type fits best? How-to, troubleshooting, FAQ, known issue, or reference (see article types below)

If a ticket reference is provided, look up the full context:

~~support platform: Pull the ticket thread, resolution, and any internal notes ~~knowledge base: Check if a similar article already exists (update vs. create new) ~~project tracker: Check if there's a related bug or feature request

2. Draft the Article

Using the article structure, formatting standards, and searchability best practices below:

Follow the template for the chosen article type (how-to, troubleshooting, FAQ, known issue, or reference) Apply the searchability best practices: customer-language title, plain-language opening sentence, exact error messages, common synonyms Keep it scannable: headers, numbered steps, short paragraphs

3. Generate the Article

Present the draft with metadata:

KB Article Draft

Title: [Article title] Type: [How-to / Troubleshooting / FAQ / Known Issue / Reference] Category: [Product area or topic] Tags: [Searchable tags] Audience: [All users / Admins / Developers / Specific plan]

[Full article content — using the appropriate template below]

Publishing Notes

Source: [Ticket #, customer conversation, or internal discussion] Existing articles to update: [If this overlaps with existing content] Review needed from: [SME or team if technical accuracy needs verification] Suggested review date: [When to revisit for accuracy]

4. Offer Next Steps

After generating the article: "Want me to check if a similar article already exists in your ~~knowledge base?" "Should I adjust the technical depth for a different audience?" "Want me to draft a companion article (e.g., a how-to to go with this troubleshooting guide)?" "Should I create an internal-only version with additional technical detail?"

Article Structure and Formatting Standards

Universal Article Elements

Every KB article should include:

Title: Clear, searchable, describes the outcome or problem (not internal jargon) Overview: 1-2 sentences explaining what this article covers and who it's for Body: Structured content appropriate to the article type Related articles: Links to relevant companion content Metadata: Category, tags, audience, last updated date

Formatting Rules

Use headers (H2, H3) to break content into scannable sections Use numbered lists for sequential steps Use bullet lists for non-sequential items Use bold for UI element names, key terms, and emphasis Use code blocks for commands, API calls, error messages, and configuration values Use tables for comparisons, options, or reference data Use callouts/notes for warnings, tips, and important caveats Keep paragraphs short — 2-4 sentences max One idea per section — if a section covers two topics, split it

Writing for Searchability

Articles are useless if customers can't find them. Optimize every article for search:

Title Best Practices

Keyword Optimization

Include exact error messages — customers copy-paste error text into search Use customer language, not internal terminology — "can't log in" not "authentication failure" Include common synonyms — "delete/remove", "dashboard/home page", "export/download" Add alternate phrasings — address the same issue from different angles in the overview Tag with product areas — make sure category and tags match how customers think about the product

Opening Sentence Formula

Start every article with a sentence that restates the problem or task in plain language:

How-to: "This guide shows you how to [accomplish X]." Troubleshooting: "If you're seeing [symptom], this article explains how to fix it." FAQ: "[Question in the customer's words]? Here's the answer." Known issue: "Some users are experiencing [symptom]. Here's what we know and how to work around it."

Article Type Templates

How-to Articles

Purpose: Step-by-step instructions for accomplishing a task.

Structure:

How to [accomplish task]

[Overview — what this guide covers and when you'd use it]

Prerequisites

[What's needed before starting]

Steps

1. [Action]

[Instruction with specific details]

2. [Action]

[Instruction]

Verify It Worked

[How to confirm success]

Common Issues

Related Articles

[Links]

Best practices: Start each step with a verb Include the specific path: "Go to Settings > Integrations > API Keys" Mention what the user should see after each step ("You should see a green confirmation banner") Test the steps yourself or verify with a recent ticket resolution

Troubleshooting Articles

Purpose: Diagnose and resolve a specific problem.

Structure:

[Problem description — what the user sees]

Symptoms

[What the user observes]

Cause

[Why this happens — brief, non-jargon explanation]

Solution

Option 1: [Primary fix]

[Steps]

Option 2: [Alternative if Option 1 doesn't work]

[Steps]

Prevention

[How to avoid this in the future]

Still Having Issues?

[How to get help]

Best practices: Lead with symptoms, not causes — customers search for what they see Provide multiple solutions when possible (most likely fix first) Include a "Still having issues?" section that points to support If the root cause is complex, keep the customer-facing explanation simple

FAQ Articles

Purpose: Quick answer to a common question.

Structure:

[Question — in the customer's words]

[Direct answer — 1-3 sentences]

Details

[Additional context, nuance, or explanation if needed]

Related Questions

[Link to relate