{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/kb-article",
  "version": "1.0.0",
  "name": "kb-article",
  "description": "Draft a knowledge base article from a resolved issue or common question. Use when a ticket resolution is worth documenting for self-service, the same question keeps coming up, a workaround needs to be published, or a known issue should be communicated to customers.",
  "system_prompt_fragment": "# /kb-article\n\n> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).\n\nDraft a publish-ready knowledge base article from a resolved support issue, common question, or documented workaround. Structures the content for searchability and self-service.\n\n## Usage\n\n```\n/kb-article <resolved issue, ticket reference, or topic description>\n```\n\nExamples:\n- `/kb-article How to configure SSO with Okta — resolved this for 3 customers last month`\n- `/kb-article Ticket #4521 — customer couldn't export data over 10k rows`\n- `/kb-article Common question: how to set up webhook notifications`\n- `/kb-article Known issue: dashboard charts not loading on Safari 16`\n\n## Workflow\n\n### 1. Understand the Source Material\n\nParse the input to identify:\n\n- **What was the problem?** The original issue, question, or error\n- **What was the solution?** The resolution, workaround, or answer\n- **Who does this affect?** User type, plan level, or configuration\n- **How common is this?** One-off or recurring issue\n- **What article type fits best?** How-to, troubleshooting, FAQ, known issue, or reference (see article types below)\n\nIf a ticket reference is provided, look up the full context:\n\n- **~~support platform**: Pull the ticket thread, resolution, and any internal notes\n- **~~knowledge base**: Check if a similar article already exists (update vs. create new)\n- **~~project tracker**: Check if there's a related bug or feature request\n\n### 2. Draft the Article\n\nUsing the article structure, formatting standards, and searchability best practices below:\n\n- Follow the template for the chosen article type (how-to, troubleshooting, FAQ, known issue, or reference)\n- Apply the searchability best practices: customer-language title, plain-language opening sentence, exact error messages, common synonyms\n- Keep it scannable: headers, numbered steps, short paragraphs\n\n### 3. Generate the Article\n\nPresent the draft with metadata:\n\n```\n## KB Article Draft\n\n**Title:** [Article title]\n**Type:** [How-to / Troubleshooting / FAQ / Known Issue / Reference]\n**Category:** [Product area or topic]\n**Tags:** [Searchable tags]\n**Audience:** [All users / Admins / Developers / Specific plan]\n\n---\n\n[Full article content — using the appropriate template below]\n\n---\n\n### Publishing Notes\n- **Source:** [Ticket #, customer conversation, or internal discussion]\n- **Existing articles to update:** [If this overlaps with existing content]\n- **Review needed from:** [SME or team if technical accuracy needs verification]\n- **Suggested review date:** [When to revisit for accuracy]\n```\n\n### 4. Offer Next Steps\n\nAfter generating the article:\n- \"Want me to check if a similar article already exists in your ~~knowledge base?\"\n- \"Should I adjust the technical depth for a different audience?\"\n- \"Want me to draft a companion article (e.g., a how-to to go with this troubleshooting guide)?\"\n- \"Should I create an internal-only version with additional technical detail?\"\n\n---\n\n## Article Structure and Formatting Standards\n\n### Universal Article Elements\n\nEvery KB article should include:\n\n1. **Title**: Clear, searchable, describes the outcome or problem (not internal jargon)\n2. **Overview**: 1-2 sentences explaining what this article covers and who it's for\n3. **Body**: Structured content appropriate to the article type\n4. **Related articles**: Links to relevant companion content\n5. **Metadata**: Category, tags, audience, last updated date\n\n### Formatting Rules\n\n- **Use headers (H2, H3)** to break content into scannable sections\n- **Use numbered lists** for sequential steps\n- **Use bullet lists** for non-sequential items\n- **Use bold** for UI element names, key terms, and emphasis\n- **Use code blocks** for commands, API calls, error messages, and configuration values\n- **Use tables** for comparisons, options, or reference data\n- **Use callouts/notes** for warnings, tips, and important caveats\n- **Keep paragraphs short** — 2-4 sentences max\n- **One idea per section** — if a section covers two topics, split it\n\n## Writing for Searchability\n\nArticles are useless if customers can't find them. Optimize every article for search:\n\n### Title Best Practices\n\n| Good Title | Bad Title | Why |\n|------------|-----------|-----|\n| \"How to configure SSO with Okta\" | \"SSO Setup\" | Specific, includes the tool name customers search for |\n| \"Fix: Dashboard shows blank page\" | \"Dashboard Issue\" | Includes the symptom customers experience |\n| \"API rate limits and quotas\" | \"API Information\" | Includes the specific terms customers search for |\n| \"Error: 'Connection refused' when importing data\" | \"Import Problems\" | Includes the exact error message |\n\n### Keyword Optimization\n\n- **Include exact error messages** — customers copy-paste error text into search\n- **Use customer language**, not internal terminology — \"can't log in\" not \"authentication failure\"\n- **Include common synonyms** — \"delete/remove\", \"dashboard/home page\", \"export/download\"\n- **Add alternate phrasings** — address the same issue from different angles in the overview\n- **Tag with product areas** — make sure category and tags match how customers think about the product\n\n### Opening Sentence Formula\n\nStart every article with a sentence that restates the problem or task in plain language:\n\n- **How-to**: \"This guide shows you how to [accomplish X].\"\n- **Troubleshooting**: \"If you're seeing [symptom], this article explains how to fix it.\"\n- **FAQ**: \"[Question in the customer's words]? Here's the answer.\"\n- **Known issue**: \"Some users are experiencing [symptom]. Here's what we know and how to work around it.\"\n\n## Article Type Templates\n\n### How-to Articles\n\n**Purpose**: Step-by-step instructions for accomplishing a task.\n\n**Structure**:\n```\n# How to [accomplish task]\n\n[Overview — what this guide covers and when you'd use it]\n\n## Prerequisites\n- [What's needed before starting]\n\n## Steps\n### 1. [Action]\n[Instruction with specific details]\n\n### 2. [Action]\n[Instruction]\n\n## Verify It Worked\n[How to confirm success]\n\n## Common Issues\n- [Issue]: [Fix]\n\n## Related Articles\n- [Links]\n```\n\n**Best practices**:\n- Start each step with a verb\n- Include the specific path: \"Go to Settings > Integrations > API Keys\"\n- Mention what the user should see after each step (\"You should see a green confirmation banner\")\n- Test the steps yourself or verify with a recent ticket resolution\n\n### Troubleshooting Articles\n\n**Purpose**: Diagnose and resolve a specific problem.\n\n**Structure**:\n```\n# [Problem description — what the user sees]\n\n## Symptoms\n- [What the user observes]\n\n## Cause\n[Why this happens — brief, non-jargon explanation]\n\n## Solution\n### Option 1: [Primary fix]\n[Steps]\n\n### Option 2: [Alternative if Option 1 doesn't work]\n[Steps]\n\n## Prevention\n[How to avoid this in the future]\n\n## Still Having Issues?\n[How to get help]\n```\n\n**Best practices**:\n- Lead with symptoms, not causes — customers search for what they see\n- Provide multiple solutions when possible (most likely fix first)\n- Include a \"Still having issues?\" section that points to support\n- If the root cause is complex, keep the customer-facing explanation simple\n\n### FAQ Articles\n\n**Purpose**: Quick answer to a common question.\n\n**Structure**:\n```\n# [Question — in the customer's words]\n\n[Direct answer — 1-3 sentences]\n\n## Details\n[Additional context, nuance, or explanation if needed]\n\n## Related Questions\n- [Link to related FAQ]\n- [Link to related FAQ]\n```\n\n**Best practices**:\n- Answer the question in the first sentence\n- Keep it concise — if the answer needs a walkthrough, it's a how-to, not an FAQ\n- Group related FAQs and link between them\n\n### Known Issue Articles\n\n**Purpose**: Document a known bug or limitation with a workaround.\n\n**Structure**:\n```\n# [Known Issue]: [Brief description]\n\n**Status:** [Investigating / Workaround Available / Fix In Progress / Resolved]\n**Affected:** [Who/what is affected]\n**Last updated:** [Date]\n\n## Symptoms\n[What users experience]\n\n## Workaround\n[Steps to work around the issue, or \"No workaround available\"]\n\n## Fix Timeline\n[Expected fix date or current status]\n\n## Updates\n- [Date]: [Update]\n```\n\n**Best practices**:\n- Keep the status current — nothing erodes trust faster than a stale known issue article\n- Update the article when the fix ships and mark as resolved\n- If resolved, keep the article live for 30 days for customers still searching the old symptoms\n\n## Review and Maintenance Cadence\n\nKnowledge bases decay without maintenance. Follow this schedule:\n\n| Activity | Frequency | Who |\n|----------|-----------|-----|\n| **New article review** | Before publishing | Peer review + SME for technical content |\n| **Accuracy audit** | Quarterly | Support team reviews top-traffic articles |\n| **Stale content check** | Monthly | Flag articles not updated in 6+ months |\n| **Known issue updates** | Weekly | Update status on all open known issues |\n| **Analytics review** | Monthly | Check which articles have low helpfulness ratings or high bounce rates |\n| **Gap analysis** | Quarterly | Identify top ticket topics without KB articles |\n\n### Article Lifecycle\n\n1. **Draft**: Written, needs review\n2. **Published**: Live and available to customers\n3. **Needs update**: Flagged for revision (product change, feedback, or age)\n4. **Archived**: No longer relevant but preserved for reference\n5. **Retired**: Removed from the knowledge base\n\n### When to Update vs. Create New\n\n**Update existing** when:\n- The product changed and steps need refreshing\n- The article is mostly right but missing a detail\n- Feedback indicates customers are confused by a specific section\n- A better workaround or solution was found\n\n**Create new** when:\n- A new feature or product area needs documentation\n- A resolved ticket reveals a gap — no article exists for this topic\n- The existing article covers too many topics and should be split\n- A different audience needs the same information explained differently\n\n## Linking and Categorization Taxonomy\n\n### Category Structure\n\nOrganize articles into a hierarchy that matches how customers think:\n\n```\nGetting Started\n├── Account setup\n├── First-time configuration\n└── Quick start guides\n\nFeatures & How-tos\n├── [Feature area 1]\n├── [Feature area 2]\n└── [Feature area 3]\n\nIntegrations\n├── [Integration 1]\n├── [Integration 2]\n└── API reference\n\nTroubleshooting\n├── Common errors\n├── Performance issues\n└── Known issues\n\nBilling & Account\n├── Plans and pricing\n├── Billing questions\n└── Account management\n```\n\n### Linking Best Practices\n\n- **Link from troubleshooting to how-to**: \"For setup instructions, see [How to configure X]\"\n- **Link from how-to to troubleshooting**: \"If you encounter errors, see [Troubleshooting X]\"\n- **Link from FAQ to detailed articles**: \"For a full walkthrough, see [Guide to X]\"\n- **Link from known issues to workarounds**: Keep the chain from problem to solution short\n- **Use relative links** within the KB — they survive restructuring better than absolute URLs\n- **Avoid circular links** — if A links to B, B shouldn't link back to A unless both are genuinely useful entry points\n\n## KB Writing Best Practices\n\n1. Write for the customer who is frustrated and searching for an answer — be clear, direct, and helpful\n2. Every article should be findable through search using the words a customer would type\n3. Test your articles — follow the steps yourself or have someone unfamiliar with the topic follow them\n4. Keep articles focused — one problem, one solution. Split if an article is growing too long\n5. Maintain aggressively — a wrong article is worse than no article\n6. Track what's missing — every ticket that could have been a KB article is a content gap\n7. Measure impact — articles that don't get traffic or don't reduce tickets need to be improved or retired",
  "applicable_domains": [
    "support",
    "customer"
  ],
  "invocation": [
    "/kb-article",
    "/kb-article <resolved issue or ticket>"
  ],
  "tags": [
    "customer-support",
    "anthropics",
    "knowledge-work"
  ],
  "authored_by": "anthropics",
  "source_url": "https://github.com/anthropics/knowledge-work-plugins/blob/main/customer-support/skills/kb-article/SKILL.md",
  "lifecycle": "stable",
  "category": "support",
  "provenance": {
    "source": "anthropics/knowledge-work-plugins",
    "source_url": "https://github.com/anthropics/knowledge-work-plugins/blob/main/customer-support/skills/kb-article/SKILL.md",
    "author": "Anthropic",
    "license": "Apache-2.0",
    "notes": "Imported by scripts/import-anthropic-skills.py."
  }
}