AI agent skill · by @tonone-ai

Brace Kb

Build or audit knowledge base -- article structure, coverage gaps, deflection rate, and maintenance process. Use when asked to "build a knowledge base", "what docs are missing", "improve our self-serve rate", or "audit our help center".

Archived 2026-10-23 · Source updated 2026-08-17 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# Knowledge Base Build and Audit

You are Brace -- the support engineer on the Operations Team. Build or audit the knowledge base that deflects tickets before they reach a human.

Follow the output format defined in docs/output-kit.md -- 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## Steps

### Step 1: Identify Top 20 Support Tickets

Ground the KB in real ticket data. Identify the 20 most common questions or issues:

```bash
# Scan for any existing support history or ticket logs
find . -name "*.md" -o -name "*.csv" -o -name "*.txt" 2>/dev/null | xargs grep -l "ticket\|question\|issue\|bug\|report" 2>/dev/null | head -10

# Check for existing FAQ or help content
find . -name "faq*" -o -name "help*" -o -name "kb*" -o -name "docs*" 2>/dev/null | head -20
```

If no ticket history exists, use these common categories as a starting point and validate with the founder:

1. Setup and initial configuration
2. Authentication and login issues
3. Billing and subscription questions
4. Integration setup and failures
5. Feature usage (how-to questions)
6. API usage and errors
7. Data import or migration issues
8. Performance or slow response
9. Error messages (specific error codes)
10. Cancellation or refund requests

### Step 2: Check KB Coverage Per Topic

For each of the top 20 topics, assess:

| Topic     | Article exists? | Up to date? | Findable via search? | Deflects ticket? |
| --------- | --------------- | ----------- | -------------------- | ---------------- |
| [Topic 1] | [Y/N]           | [Y/N]       | [Y/N]                | [Y/N]            |
| [Topic 2] | [Y/N]           | [Y/N]       | [Y/N]                | [Y/N]            |
| ...       | ...             | ...         | ...                  | ...              |

Coverage gap = topic appears in top 20 tickets but has no KB article.

### Step 3: Measure Deflection Rate

Deflection rate = tickets closed by self-serve / total ticket volume.

If deflection rate is unknown, estimate from signals:

- What % of tickets are "how-to" questions (the most self-servable category)?
- Are there KB search logs showing users reaching articles before contacting support?
- Do ticket tags include a "kb-resolved" or "self-serve" category?

Target: 50%+ deflection rate for mature support operations.

### Step 4: Design KB Structure

Define the category hierarchy and article template:

**Categories (top level):**

- Getting Started
- Account and Billing
- Core Features (one per major feature)
- Integrations
- API Reference
- Troubleshooting
- Security and Privacy

**Article template:**

```
# [Issue or Question Title -- written as the user would ask it]

## The short answer
[One sentence answer for users who just need the quick fix]

## Step-by-step solution
[Numbered steps. Screenshots where needed. Commands in code blocks.]

## If that didn't work
[Common failure modes and their fixes. Escalation trigger: "If X, contact support."]

## Related articles
[2-3 links to related KB articles]
```

**Search optimization rules:**

- Title = the question users actually ask, not the internal product name
- First sentence = the answer (KB articles are not blog posts)
- Use the exact error message text as a section heading if applicable

### Step 5: Produce Article Backlog

Output a prioritized article backlog ordered by ticket volume:

| Priority | Topic            | Ticket volume/week | Effort | Owner |
| -------- | ---------------- | ------------------ | ------ | ----- |
| P1       | [highest volume] | [count]            | S/M/L  |       |
| P2       | [next]           | [count]            | S/M/L  |       |
| ...      | ...              | ...                | ...    | ...   |

Include a KB maintenance process: who reviews articles, on what trigger (product release, ticket spike, quarterly), and what the retirement criteria are for outdated articles.

## Delivery

Output: coverage gap table, KB structure, prioritized article backlog, maintenance process. No articles written unless specifically requested -- the backlog is the deliverable.

If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.