documentation-standards

Name: documentation-standards
Author: softspark

161stars21forks

How to install documentation-standards?

softspark/ai-toolkit/documentation-standards

$npx -y skills add softspark/ai-toolkit --skill documentation-standards

Installs into the current project.

Summary

KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.

Files · 1

View on GitHub

SKILL.md

1	# Documentation Standards
2
3	Auto-loaded knowledge skill enforcing KB document conventions across all agents and skills.
4
5	## Frontmatter Specification (MANDATORY)
6
7	Every document in `kb/` MUST start with YAML frontmatter:
8
9	```yaml
10	---
11	title: "Document Title" # REQUIRED — English, descriptive
12	category: reference # REQUIRED — one of 5 valid categories
13	service: ai-toolkit # REQUIRED — service identifier
14	tags: [tag1, tag2, tag3] # REQUIRED — minimum 1, recommended 3+
15	last_updated: "YYYY-MM-DD" # REQUIRED — ISO format
16	created: "YYYY-MM-DD" # REQUIRED — creation date
17	description: "One-line summary." # REQUIRED — for search indexing
18	version: "1.0.0" # optional — semver
19	---
20	```
21
22	All 7 fields above are REQUIRED. Documents without valid frontmatter fail `validate.sh` and block CI.
23
24	## Category Taxonomy
25
26	\| Category \| Directory \| Purpose \| Examples \|
27	\|----------\|-----------\|---------\|----------\|
28	\| `reference` \| `kb/reference/` \| Technical specifications, catalogs, architecture notes, API docs \| `agents-catalog.md`, `architecture-overview.md` \|
29	\| `howto` \| `kb/howto/` \| Step-by-step task guides \| `use-corrective-rag.md`, `configure-mcp-server.md` \|
30	\| `procedures` \| `kb/procedures/` \| SOPs, runbooks, operational processes \| `maintenance-sop.md`, `incident-response.md` \|
31	\| `troubleshooting` \| `kb/troubleshooting/` \| Problem resolution, debugging guides \| `database-connection-issues.md` \|
32	\| `best-practices` \| `kb/best-practices/` \| Guidelines, recommendations, standards \| `security-checklist.md` \|
33
34	Rule: The `category:` frontmatter field MUST match the directory the file lives in.
35
36	## Naming Conventions
37
38	- Filename: kebab-case, descriptive, no dates (`merge-friendly-install-model.md`)
39	- Title: English, clear, matches filename semantics
40	- No prefixes: no `001-`, no `YYYY-MM-DD-` in filenames (dates go in frontmatter)
41	- Max length: keep filenames under 60 characters
42
43	## Language Rule
44
45	All KB content MUST be in English. No exceptions for:
46	- Document titles
47	- Body content
48	- Code comments within docs
49	- Table headers and descriptions
50
51	## Quality Standards
52
53	### Required for every KB document:
54	- [ ] Valid YAML frontmatter with all 7 required fields
55	- [ ] Category matches directory
56	- [ ] Written in English
57	- [ ] Title is clear and descriptive
58	- [ ] Content is actionable (not just placeholders)
59
60	### Required for procedural docs (howto, procedures):
61	- [ ] Prerequisites listed
62	- [ ] Steps are numbered
63	- [ ] Commands are copy-pasteable
64	- [ ] Verification section present
65
66	### Required for troubleshooting docs:
67	- [ ] Symptoms described
68	- [ ] Root cause identified
69	- [ ] Resolution steps provided
70	- [ ] Prevention notes included
71
72	## Templates
73
74	### Reference Document
75	```yaml
76	---
77	title: "AI Toolkit - [Topic]"
78	category: reference
79	service: ai-toolkit
80	tags: [topic, subtopic]
81	version: "1.0.0"
82	created: "YYYY-MM-DD"
83	last_updated: "YYYY-MM-DD"
84	description: "Brief summary."
85	---
86
87	# [Topic]
88
89	## Overview
90	[What this document covers]
91
92	## Details
93	[Technical content]
94
95	## Related
96	- [Other relevant KB docs]
97	```
98
99	### How-To Guide
100	```yaml
101	---
102	title: "How to [Task]"
103	category: howto
104	service: ai-toolkit
105	tags: [howto, task-name]
106	created: "YYYY-MM-DD"
107	last_updated: "YYYY-MM-DD"
108	description: "Step-by-step guide for [task]."
109	---
110
111	# How to [Task]
112
113	## Prerequisites
114	- [Requirement]
115
116	## Steps
117
118	### 1. [Action]
119	[Instructions + commands]
120
121	### 2. [Action]
122	[Instructions + commands]
123
124	## Verification
125	[How to confirm success]
126
127	## Troubleshooting
128	\| Problem \| Solution \|
129	\|---------\|----------\|
130	\| [Error] \| [Fix] \|
131	```
132
133	### SOP / Procedure
134	```yaml
135	---
136	title: "SOP: [Process Name]"
137	category: procedures
138	service: ai-toolkit
139	tags: [sop, process-name]
140	created: "YYYY-MM-DD"
141	last_updated: "YYYY-MM-DD"
142	description: "Standard procedure for [process]."
143	---
144
145	# SOP: [Process Name]
146
147	## Purpose
148	[Why this procedure exists]
149
150	## Prerequisites
151	- [Requirement]
152
153	## Procedure
154	### Step 1: [Action]
155	[Detailed instructions]
156
157	## Verification
158	[How to verify success]
159
160	## Rollback
161	[How to revert if needed]
162	```
163
164	## Validation
165
166	```bash
167	# Validates ALL kb/*/.md frontmatter (title, category, service, tags, created, last_updated, description)
168	scripts/validate.py
169
170	# Checks: required fields present, category is valid, tags non-empty
171	```
172
173	Valid categories: `reference`, `howto`, `procedures`, `troubleshooting`, `best-practices`, `planning`.
174
175	## Anti-Patterns
176
177	\| Anti-Pattern \| Problem \| Fix \|
178	\|-------------\|---------\|-----\|
179	\| No frontmatter \| Blocks CI, not indexed \| Add frontmatter with all required fields \|
180	\| Wrong category \| Confuses search \| Match

People who liked this also viewed

6 picks

Type

documentation-standards

161stars21forks

View on GitHub

How to install documentation-standards?

softspark/ai-toolkit/documentation-standards

$npx -y skills add softspark/ai-toolkit --skill documentation-standards

Installs into the current project.

Summary

KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.

Files · 1

View on GitHub

SKILL.md

1	# Documentation Standards
2
3	Auto-loaded knowledge skill enforcing KB document conventions across all agents and skills.
4
5	## Frontmatter Specification (MANDATORY)
6
7	Every document in `kb/` MUST start with YAML frontmatter:
8
9	```yaml
10	---
11	title: "Document Title" # REQUIRED — English, descriptive
12	category: reference # REQUIRED — one of 5 valid categories
13	service: ai-toolkit # REQUIRED — service identifier
14	tags: [tag1, tag2, tag3] # REQUIRED — minimum 1, recommended 3+
15	last_updated: "YYYY-MM-DD" # REQUIRED — ISO format
16	created: "YYYY-MM-DD" # REQUIRED — creation date
17	description: "One-line summary." # REQUIRED — for search indexing
18	version: "1.0.0" # optional — semver
19	---
20	```
21
22	All 7 fields above are REQUIRED. Documents without valid frontmatter fail `validate.sh` and block CI.
23
24	## Category Taxonomy
25
26	\| Category \| Directory \| Purpose \| Examples \|
27	\|----------\|-----------\|---------\|----------\|
28	\| `reference` \| `kb/reference/` \| Technical specifications, catalogs, architecture notes, API docs \| `agents-catalog.md`, `architecture-overview.md` \|
29	\| `howto` \| `kb/howto/` \| Step-by-step task guides \| `use-corrective-rag.md`, `configure-mcp-server.md` \|
30	\| `procedures` \| `kb/procedures/` \| SOPs, runbooks, operational processes \| `maintenance-sop.md`, `incident-response.md` \|
31	\| `troubleshooting` \| `kb/troubleshooting/` \| Problem resolution, debugging guides \| `database-connection-issues.md` \|
32	\| `best-practices` \| `kb/best-practices/` \| Guidelines, recommendations, standards \| `security-checklist.md` \|
33
34	Rule: The `category:` frontmatter field MUST match the directory the file lives in.
35
36	## Naming Conventions
37
38	- Filename: kebab-case, descriptive, no dates (`merge-friendly-install-model.md`)
39	- Title: English, clear, matches filename semantics
40	- No prefixes: no `001-`, no `YYYY-MM-DD-` in filenames (dates go in frontmatter)
41	- Max length: keep filenames under 60 characters
42
43	## Language Rule
44
45	All KB content MUST be in English. No exceptions for:
46	- Document titles
47	- Body content
48	- Code comments within docs
49	- Table headers and descriptions
50
51	## Quality Standards
52
53	### Required for every KB document:
54	- [ ] Valid YAML frontmatter with all 7 required fields
55	- [ ] Category matches directory
56	- [ ] Written in English
57	- [ ] Title is clear and descriptive
58	- [ ] Content is actionable (not just placeholders)
59
60	### Required for procedural docs (howto, procedures):
61	- [ ] Prerequisites listed
62	- [ ] Steps are numbered
63	- [ ] Commands are copy-pasteable
64	- [ ] Verification section present
65
66	### Required for troubleshooting docs:
67	- [ ] Symptoms described
68	- [ ] Root cause identified
69	- [ ] Resolution steps provided
70	- [ ] Prevention notes included
71
72	## Templates
73
74	### Reference Document
75	```yaml
76	---
77	title: "AI Toolkit - [Topic]"
78	category: reference
79	service: ai-toolkit
80	tags: [topic, subtopic]
81	version: "1.0.0"
82	created: "YYYY-MM-DD"
83	last_updated: "YYYY-MM-DD"
84	description: "Brief summary."
85	---
86
87	# [Topic]
88
89	## Overview
90	[What this document covers]
91
92	## Details
93	[Technical content]
94
95	## Related
96	- [Other relevant KB docs]
97	```
98
99	### How-To Guide
100	```yaml
101	---
102	title: "How to [Task]"
103	category: howto
104	service: ai-toolkit
105	tags: [howto, task-name]
106	created: "YYYY-MM-DD"
107	last_updated: "YYYY-MM-DD"
108	description: "Step-by-step guide for [task]."
109	---
110
111	# How to [Task]
112
113	## Prerequisites
114	- [Requirement]
115
116	## Steps
117
118	### 1. [Action]
119	[Instructions + commands]
120
121	### 2. [Action]
122	[Instructions + commands]
123
124	## Verification
125	[How to confirm success]
126
127	## Troubleshooting
128	\| Problem \| Solution \|
129	\|---------\|----------\|
130	\| [Error] \| [Fix] \|
131	```
132
133	### SOP / Procedure
134	```yaml
135	---
136	title: "SOP: [Process Name]"
137	category: procedures
138	service: ai-toolkit
139	tags: [sop, process-name]
140	created: "YYYY-MM-DD"
141	last_updated: "YYYY-MM-DD"
142	description: "Standard procedure for [process]."
143	---
144
145	# SOP: [Process Name]
146
147	## Purpose
148	[Why this procedure exists]
149
150	## Prerequisites
151	- [Requirement]
152
153	## Procedure
154	### Step 1: [Action]
155	[Detailed instructions]
156
157	## Verification
158	[How to verify success]
159
160	## Rollback
161	[How to revert if needed]
162	```
163
164	## Validation
165
166	```bash
167	# Validates ALL kb/*/.md frontmatter (title, category, service, tags, created, last_updated, description)
168	scripts/validate.py
169
170	# Checks: required fields present, category is valid, tags non-empty
171	```
172
173	Valid categories: `reference`, `howto`, `procedures`, `troubleshooting`, `best-practices`, `planning`.
174
175	## Anti-Patterns
176
177	\| Anti-Pattern \| Problem \| Fix \|
178	\|-------------\|---------\|-----\|
179	\| No frontmatter \| Blocks CI, not indexed \| Add frontmatter with all required fields \|
180	\| Wrong category \| Confuses search \| Match

People who liked this also viewed

6 picks

Type