| name | documentation-standards |
| description | KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base. |
| effort | medium |
| user-invocable | false |
| allowed-tools | Read |
Documentation Standards
Auto-loaded knowledge skill enforcing KB document conventions across all agents and skills.
Frontmatter Specification (MANDATORY)
Every document in kb/ MUST start with YAML frontmatter:
---
title: "Document Title"
category: reference
service: ai-toolkit
tags: [tag1, tag2, tag3]
last_updated: "YYYY-MM-DD"
created: "YYYY-MM-DD"
description: "One-line summary."
version: "1.0.0"
---
All 7 fields above are REQUIRED. Documents without valid frontmatter fail validate.sh and block CI.
Category Taxonomy
| Category | Directory | Purpose | Examples |
|---|
reference | kb/reference/ | Technical specifications, catalogs, architecture notes, API docs | agents-catalog.md, architecture-overview.md |
howto | kb/howto/ | Step-by-step task guides | use-corrective-rag.md, configure-mcp-server.md |
procedures | kb/procedures/ | SOPs, runbooks, operational processes | maintenance-sop.md, incident-response.md |
troubleshooting | kb/troubleshooting/ | Problem resolution, debugging guides | database-connection-issues.md |
best-practices | kb/best-practices/ | Guidelines, recommendations, standards | security-checklist.md |
Rule: The category: frontmatter field MUST match the directory the file lives in.
Naming Conventions
- Filename: kebab-case, descriptive, no dates (
merge-friendly-install-model.md)
- Title: English, clear, matches filename semantics
- No prefixes: no
001-, no YYYY-MM-DD- in filenames (dates go in frontmatter)
- Max length: keep filenames under 60 characters
Language Rule
All KB content MUST be in English. No exceptions for:
- Document titles
- Body content
- Code comments within docs
- Table headers and descriptions
Quality Standards
Required for every KB document:
Required for procedural docs (howto, procedures):
Required for troubleshooting docs:
Templates
Reference Document
---
title: "AI Toolkit - [Topic]"
category: reference
service: ai-toolkit
tags: [topic, subtopic]
version: "1.0.0"
created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
description: "Brief summary."
---
[What this document covers]
[Technical content]
- [Other relevant KB docs]
How-To Guide
---
title: "How to [Task]"
category: howto
service: ai-toolkit
tags: [howto, task-name]
created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
description: "Step-by-step guide for [task]."
---
- [Requirement]
[Instructions + commands]
[Instructions + commands]
[How to confirm success]
| Problem | Solution |
|---------|----------|
| [Error] | [Fix] |
SOP / Procedure
---
title: "SOP: [Process Name]"
category: procedures
service: ai-toolkit
tags: [sop, process-name]
created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
description: "Standard procedure for [process]."
---
[Why this procedure exists]
- [Requirement]
[Detailed instructions]
[How to verify success]
[How to revert if needed]
Validation
scripts/validate.py
Valid categories: reference, howto, procedures, troubleshooting, best-practices, planning.
Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|
| No frontmatter | Blocks CI, not indexed | Add frontmatter with all required fields |
| Wrong category | Confuses search | Match category: to directory name |
| Non-English content | Inconsistent KB | Translate to English |
| Date in filename | Clutters, becomes stale | Use created: in frontmatter |
| Empty tags | Hurts search relevance | Add at least 1 meaningful tag |
| Placeholder content | Wastes reader time | Write real content or don't create the doc |