Draft Docs
Generate Tutorial, How-To, Reference, or Explanation documentation drafts to docs/drafts/ for review before publishing. These are the four Diataxis types — see docs-style/references/diataxis-compass.md for the full type-selection procedure.
Arguments
- Topic prompt: Description of what to document (e.g., "Document the WebSocket API")
- --publish [file]: Move reviewed draft to final location and update navigation
Mode 1: Generate Draft
Invoke the draft-docs skill with a topic prompt, e.g. draft-docs "Document the authentication middleware".
Step 0: Gather Context
Before parsing input, gather project context:
# Check for existing docs structure
ls -la docs/ 2>/dev/null || echo "No docs/ directory found"
# Identify documentation framework
ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1
# Check for existing drafts
ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"
# Get recent code changes for context
git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20
Capture:
- Docs structure:
docs/ subdirectories present
- Navigation system:
navigation.json, mint.json, or other config
- Tech stack hints: from file extensions and imports in changed files
- Existing drafts: to avoid duplicates
Step 1: Parse Input
Extract from the prompt:
- Topic: What to document (e.g., "authentication middleware")
- Content type: Detect from keywords:
| Keywords |
Type |
Skill |
| "tutorial", "learn", "getting started", "first", "onboarding", "introduction", "build a/your" |
Tutorial |
tutorial-docs |
| "how to", "guide", "steps", "configure", "set up" |
How-To |
howto-docs |
| "API", "reference", "parameters", "function", "endpoint" |
Reference |
reference-docs |
| "why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs" |
Explanation |
explanation-docs |
These four types are the quadrants of the Diátaxis framework — Tutorial (learning), How-To (task), Reference (information), and Explanation (understanding). Decide with the two compass questions — action or cognition? acquisition or application? — detailed in docs-style/references/diataxis-compass.md. Two distinctions resolve most ambiguity:
- Tutorial vs. How-To both give action steps, but a Tutorial teaches a beginner through a guaranteed-to-succeed lesson (study), while a How-To directs a competent user toward a real goal (work). If the reader is learning the product for the first time, it's a Tutorial; if they already know it and want to get a task done, it's a How-To.
- Reference vs. Explanation both serve theoretical knowledge, but Reference states neutral facts to consult at the keyboard, while Explanation discusses reasoning and context to read away from it. If the request wants opinions, history, or trade-offs, it's Explanation; if it wants an authoritative spec, it's Reference.
If ambiguous, ask: "Should this be a Tutorial (learning by doing), a How-To guide (task completion), a Reference doc (technical lookup), or an Explanation (understanding the why behind a concept)?"
Step 2: Load Skills
Always load both:
- docs-style - Core writing principles
- Detected type skill:
Step 3: Analyze Code
Search the codebase for relevant code:
- Symbol search: Find functions, classes, types matching the topic
- File search: Locate related files by name patterns
- Reference search: Find usage examples
Gather:
- Function/method signatures
- Type definitions
- Existing comments/docstrings
- Usage patterns in tests or examples
Step 4: Generate Draft
Apply the loaded skills to generate documentation:
For Tutorial docs:
- Follow
tutorial-docs template structure
- Title names what the reader will build ("Build your first X"), not what they'll learn
- Use first-person plural — "In this tutorial, we will…" — to keep the teacher/learner narrative
- Give one clear path with no choices or alternatives
- After every step, state what the reader should see ("You should see…")
- Ruthlessly minimize explanation; link out to Explanation docs for the "why"
For Reference docs:
- Follow
reference-docs template structure
- Document all parameters with types
- Include complete, runnable examples from actual code
- Add Related section linking to connected symbols
For How-To docs:
- Follow
howto-docs template structure
- Start title with "How to"
- List concrete prerequisites
- Break into single-action steps
- Include verification section
For Explanation docs:
- Follow
explanation-docs template structure
- Frame the title around understanding a concept ("Understanding X"), not a task
- Open by stating what the reader will understand after reading
- Explain the why behind design decisions, not just what exists
- Discuss trade-offs honestly and acknowledge alternatives that were considered
- Write flowing prose for reading away from the keyboard — no steps to follow
Step 5: Write Draft
Create output path:
docs/drafts/{slug}.md
- Slug from topic: "WebSocket API" →
websocket-api.md
Ensure directory exists:
mkdir -p docs/drafts
Write the draft file (see Hard gates → Write gate: confirm file on disk before the next step)
Report to user:
## Draft Created
**File:** `docs/drafts/{slug}.md`
**Type:** Tutorial | How-To | Reference | Explanation
**Based on:** [list of analyzed symbols/files]
### Next Steps
1. Review the draft for accuracy
2. Add any missing context or examples
3. When ready, publish by invoking the **draft-docs** skill with `--publish docs/drafts/{slug}.md`
Step 6: End-of-Run Verification
Verify draft generation completed successfully:
# Confirm draft file exists
ls -la docs/drafts/{slug}.md
# Validate frontmatter (YAML header)
head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"
# Check markdown syntax (if markdownlint available)
markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"
Verification Checklist:
If any verification fails, report the specific issue and offer to regenerate.
Mode 2: Publish Draft
Invoke the draft-docs skill with the --publish flag, e.g. draft-docs --publish docs/drafts/websocket-api.md.
Step 1: Read Draft
Read the draft file and extract:
- Title
- Content type (from frontmatter or structure)
Step 2: Determine Destination
Ask user which section:
Where should this document go?
1. **Tutorials** → `docs/tutorials/{slug}.md`
2. **API Reference** → `docs/api/{slug}.md`
3. **Guides** → `docs/guides/{slug}.md`
4. **How-To** → `docs/how-to/{slug}.md`
5. **Concepts / Explanation** → `docs/concepts/{slug}.md`
6. **Other** → Specify path
Step 3: Move File
mv docs/drafts/{slug}.md {destination}/{slug}.md
Step 4: Update Navigation
Check for docs/navigation.json and update navigation:
- Read current navigation.json
- Find appropriate navigation group
- Add new page entry
- Write updated navigation.json
Example update:
{
"navigation": [
{
"group": "API Reference",
"pages": [
"api/existing-page",
"api/websocket-api"
]
}
]
}
Step 5: Report
## Published
**From:** `docs/drafts/{slug}.md`
**To:** `{destination}/{slug}.md`
**Navigation:** Updated `docs/navigation.json`
The document is now live in your docs.
Step 6: End-of-Run Verification
Verify publish completed successfully:
# Confirm file moved to destination
ls -la {destination}/{slug}.md
# Confirm draft removed
ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"
# Verify navigation updated
grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"
# Check markdown syntax at final location
markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"
Verification Checklist:
If any verification fails, report the specific issue and offer remediation steps.
Content Type Detection
Tutorial Indicators
- Prompt mentions: tutorial, learn, getting started, first, onboarding, introduction, "build a/your"
- Target is a beginner's first successful experience with the product
- User wants a guided, learn-by-doing lesson, not a task or a lookup
Reference Indicators
- Prompt mentions: API, endpoint, function, method, class, type, parameters, returns
- Target is a specific symbol or set of symbols
- User wants technical specification
How-To Indicators
- Prompt mentions: how to, guide, steps, configure, set up, integrate
- Target is a task or workflow
- User wants procedural instructions
Explanation Indicators
- Prompt mentions: why, how it works, concept, background, rationale, design decision, architecture, trade-offs
- Target is a concept or system the reader wants to understand, not operate
- User wants context and reasoning to read away from the keyboard, not steps to follow
Rules
- Always load
docs-style skill for every draft
- Generate to
docs/drafts/ - never directly to final location
- Include frontmatter with title and description
- Use realistic examples from actual codebase
- Reference analyzed symbols in draft metadata
- Preserve existing navigation structure when publishing
- Ask before overwriting existing files
Hard gates (sequenced)
Do not skip ahead: each Pass must be true before the next step. Use commands or explicit artifacts—not internal assurance.
Generate draft (Mode 1)
- Context gate — Pass: Step 0 commands ran (or equivalent) and you recorded at least one concrete outcome: e.g.
docs/ listing snippet, or explicit note that docs/ is missing and will be created.
- Type gate — Pass: Tutorial vs How-To vs Reference vs Explanation is decided using the keyword table and the two compass questions or the user’s explicit answer (quote or paraphrase with “user chose …”). Do not start Step 3: Analyze Code until this is locked.
- Skills gate — Pass: Before analysis, both are in play: docs-style and the type skill (tutorial-docs, howto-docs, reference-docs, or explanation-docs). In your run, name the two skills loaded (paths)—not “I reviewed writing guidelines.”
- Write gate — Pass: After writing the draft,
test -f docs/drafts/{slug}.md succeeds (or ls shows the file). Only then emit the Draft Created block.
Publish draft (Mode 2)
- Destination gate — Pass: User chose a destination (from the menu or a specific path). Resolve
{destination} to a full path; Pass when the parent directory exists (test -d "$(dirname "$path")" or project-appropriate check) and you are not overwriting an existing file without explicit user approval.
- Move gate — Pass: After
mv, the file exists at {destination}/{slug}.md (test -f) and navigation updates (if applicable) are applied before claiming Published.
1---
2name: draft-docs
3description: Generate first-draft technical documentation from code analysis
4disable-model-invocation: true
5metadata:
6 source: https://skillmd.com/skills/existential-birds/draft-docs
7---
8
9# Draft Docs
10
11Generate Tutorial, How-To, Reference, or Explanation documentation drafts to `docs/drafts/` for review before publishing. These are the four [Diataxis](https://diataxis.fr/) types — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md) for the full type-selection procedure.
12
13## Arguments
14
15- **Topic prompt:** Description of what to document (e.g., "Document the WebSocket API")
16- **--publish [file]:** Move reviewed draft to final location and update navigation
17
18## Mode 1: Generate Draft
19
20Invoke the **draft-docs** skill with a topic prompt, e.g. `draft-docs "Document the authentication middleware"`.
21
22### Step 0: Gather Context
23
24Before parsing input, gather project context:
25
26```bash
27# Check for existing docs structure
28ls -la docs/ 2>/dev/null || echo "No docs/ directory found"
29
30# Identify documentation framework
31ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1
32
33# Check for existing drafts
34ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"
35
36# Get recent code changes for context
37git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20
38```
39
40**Capture:**
41- Docs structure: `docs/` subdirectories present
42- Navigation system: `navigation.json`, `mint.json`, or other config
43- Tech stack hints: from file extensions and imports in changed files
44- Existing drafts: to avoid duplicates
45
46### Step 1: Parse Input
47
48Extract from the prompt:
49
501. **Topic:** What to document (e.g., "authentication middleware")
512. **Content type:** Detect from keywords:
52
53| Keywords | Type | Skill |
54|----------|------|-------|
55| "tutorial", "learn", "getting started", "first", "onboarding", "introduction", "build a/your" | Tutorial | [tutorial-docs](../tutorial-docs/SKILL.md) |
56| "how to", "guide", "steps", "configure", "set up" | How-To | [howto-docs](../howto-docs/SKILL.md) |
57| "API", "reference", "parameters", "function", "endpoint" | Reference | [reference-docs](../reference-docs/SKILL.md) |
58| "why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs" | Explanation | [explanation-docs](../explanation-docs/SKILL.md) |
59
60These four types are the quadrants of the [Diátaxis](https://diataxis.fr/) framework — Tutorial (learning), How-To (task), Reference (information), and Explanation (understanding). Decide with the two compass questions — *action or cognition? acquisition or application?* — detailed in [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md). Two distinctions resolve most ambiguity:
61
62- **Tutorial vs. How-To** both give action steps, but a Tutorial teaches a beginner through a guaranteed-to-succeed lesson (study), while a How-To directs a competent user toward a real goal (work). If the reader is learning the product for the first time, it's a Tutorial; if they already know it and want to get a task done, it's a How-To.
63- **Reference vs. Explanation** both serve theoretical knowledge, but Reference *states* neutral facts to consult at the keyboard, while Explanation *discusses* reasoning and context to read away from it. If the request wants opinions, history, or trade-offs, it's Explanation; if it wants an authoritative spec, it's Reference.
64
65If ambiguous, ask: "Should this be a Tutorial (learning by doing), a How-To guide (task completion), a Reference doc (technical lookup), or an Explanation (understanding the why behind a concept)?"
66
67### Step 2: Load Skills
68
69Always load both:
70
711. [docs-style](../docs-style/SKILL.md) - Core writing principles
722. Detected type skill:
73 - [tutorial-docs](../tutorial-docs/SKILL.md) for Tutorial
74 - [howto-docs](../howto-docs/SKILL.md) for How-To
75 - [reference-docs](../reference-docs/SKILL.md) for Reference
76 - [explanation-docs](../explanation-docs/SKILL.md) for Explanation
77
78### Step 3: Analyze Code
79
80Search the codebase for relevant code:
81
821. **Symbol search:** Find functions, classes, types matching the topic
832. **File search:** Locate related files by name patterns
843. **Reference search:** Find usage examples
85
86Gather:
87- Function/method signatures
88- Type definitions
89- Existing comments/docstrings
90- Usage patterns in tests or examples
91
92### Step 4: Generate Draft
93
94Apply the loaded skills to generate documentation:
95
96**For Tutorial docs:**
97- Follow `tutorial-docs` template structure
98- Title names what the reader will build ("Build your first X"), not what they'll learn
99- Use first-person plural — "In this tutorial, we will…" — to keep the teacher/learner narrative
100- Give one clear path with no choices or alternatives
101- After every step, state what the reader should see ("You should see…")
102- Ruthlessly minimize explanation; link out to Explanation docs for the "why"
103
104**For Reference docs:**
105- Follow `reference-docs` template structure
106- Document all parameters with types
107- Include complete, runnable examples from actual code
108- Add Related section linking to connected symbols
109
110**For How-To docs:**
111- Follow `howto-docs` template structure
112- Start title with "How to"
113- List concrete prerequisites
114- Break into single-action steps
115- Include verification section
116
117**For Explanation docs:**
118- Follow `explanation-docs` template structure
119- Frame the title around understanding a concept ("Understanding X"), not a task
120- Open by stating what the reader will understand after reading
121- Explain the *why* behind design decisions, not just what exists
122- Discuss trade-offs honestly and acknowledge alternatives that were considered
123- Write flowing prose for reading away from the keyboard — no steps to follow
124
125### Step 5: Write Draft
126
1271. **Create output path:**
128 - `docs/drafts/{slug}.md`
129 - Slug from topic: "WebSocket API" → `websocket-api.md`
130
1312. **Ensure directory exists:**
132 ```bash
133 mkdir -p docs/drafts
134 ```
135
1363. **Write the draft file** (see **Hard gates** → Write gate: confirm file on disk before the next step)
137
1384. **Report to user:**
139 ```markdown
140 ## Draft Created
141
142 **File:** `docs/drafts/{slug}.md`
143 **Type:** Tutorial | How-To | Reference | Explanation
144 **Based on:** [list of analyzed symbols/files]
145
146 ### Next Steps
147
148 1. Review the draft for accuracy
149 2. Add any missing context or examples
150 3. When ready, publish by invoking the **draft-docs** skill with `--publish docs/drafts/{slug}.md`
151 ```
152
153### Step 6: End-of-Run Verification
154
155Verify draft generation completed successfully:
156
157```bash
158# Confirm draft file exists
159ls -la docs/drafts/{slug}.md
160
161# Validate frontmatter (YAML header)
162head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"
163
164# Check markdown syntax (if markdownlint available)
165markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"
166```
167
168**Verification Checklist:**
169- [ ] Draft file created at `docs/drafts/{slug}.md`
170- [ ] Frontmatter includes `title` and `description`
171- [ ] Content type matches detected type (Tutorial, How-To, Reference, or Explanation)
172- [ ] Code examples are complete and runnable (Tutorial/How-To/Reference); concepts grounded in real design decisions (Explanation)
173- [ ] Tutorial drafts give a single path with observable "You should see…" outcomes at each step
174- [ ] All analyzed symbols referenced in draft
175
176If any verification fails, report the specific issue and offer to regenerate.
177
178## Mode 2: Publish Draft
179
180Invoke the **draft-docs** skill with the `--publish` flag, e.g. `draft-docs --publish docs/drafts/websocket-api.md`.
181
182### Step 1: Read Draft
183
184Read the draft file and extract:
185- Title
186- Content type (from frontmatter or structure)
187
188### Step 2: Determine Destination
189
190Ask user which section:
191
192```markdown
193Where should this document go?
194
1951. **Tutorials** → `docs/tutorials/{slug}.md`
1962. **API Reference** → `docs/api/{slug}.md`
1973. **Guides** → `docs/guides/{slug}.md`
1984. **How-To** → `docs/how-to/{slug}.md`
1995. **Concepts / Explanation** → `docs/concepts/{slug}.md`
2006. **Other** → Specify path
201```
202
203### Step 3: Move File
204
205```bash
206mv docs/drafts/{slug}.md {destination}/{slug}.md
207```
208
209### Step 4: Update Navigation
210
211Check for `docs/navigation.json` and update navigation:
212
2131. **Read current navigation.json**
2142. **Find appropriate navigation group**
2153. **Add new page entry**
2164. **Write updated navigation.json**
217
218Example update:
219```json
220{
221 "navigation": [
222 {
223 "group": "API Reference",
224 "pages": [
225 "api/existing-page",
226 "api/websocket-api"
227 ]
228 }
229 ]
230}
231```
232
233### Step 5: Report
234
235```markdown
236## Published
237
238**From:** `docs/drafts/{slug}.md`
239**To:** `{destination}/{slug}.md`
240**Navigation:** Updated `docs/navigation.json`
241
242The document is now live in your docs.
243```
244
245### Step 6: End-of-Run Verification
246
247Verify publish completed successfully:
248
249```bash
250# Confirm file moved to destination
251ls -la {destination}/{slug}.md
252
253# Confirm draft removed
254ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"
255
256# Verify navigation updated
257grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"
258
259# Check markdown syntax at final location
260markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"
261```
262
263**Verification Checklist:**
264- [ ] Document moved to `{destination}/{slug}.md`
265- [ ] Draft removed from `docs/drafts/`
266- [ ] Navigation file updated with new page entry
267- [ ] No broken links in navigation structure
268- [ ] Document accessible at expected URL path
269
270If any verification fails, report the specific issue and offer remediation steps.
271
272## Content Type Detection
273
274### Tutorial Indicators
275
276- Prompt mentions: tutorial, learn, getting started, first, onboarding, introduction, "build a/your"
277- Target is a beginner's first successful experience with the product
278- User wants a guided, learn-by-doing lesson, not a task or a lookup
279
280### Reference Indicators
281
282- Prompt mentions: API, endpoint, function, method, class, type, parameters, returns
283- Target is a specific symbol or set of symbols
284- User wants technical specification
285
286### How-To Indicators
287
288- Prompt mentions: how to, guide, steps, configure, set up, integrate
289- Target is a task or workflow
290- User wants procedural instructions
291
292### Explanation Indicators
293
294- Prompt mentions: why, how it works, concept, background, rationale, design decision, architecture, trade-offs
295- Target is a concept or system the reader wants to understand, not operate
296- User wants context and reasoning to read away from the keyboard, not steps to follow
297
298## Rules
299
300- Always load `docs-style` skill for every draft
301- Generate to `docs/drafts/` - never directly to final location
302- Include frontmatter with title and description
303- Use realistic examples from actual codebase
304- Reference analyzed symbols in draft metadata
305- Preserve existing navigation structure when publishing
306- Ask before overwriting existing files
307
308## Hard gates (sequenced)
309
310Do not skip ahead: each **Pass** must be true before the next step. Use commands or explicit artifacts—not internal assurance.
311
312### Generate draft (Mode 1)
313
3141. **Context gate — Pass:** Step 0 commands ran (or equivalent) and you recorded at least one concrete outcome: e.g. `docs/` listing snippet, or explicit note that `docs/` is missing and will be created.
3152. **Type gate — Pass:** Tutorial vs How-To vs Reference vs Explanation is decided using the keyword table and the two compass questions **or** the user’s explicit answer (quote or paraphrase with “user chose …”). Do not start **Step 3: Analyze Code** until this is locked.
3163. **Skills gate — Pass:** Before analysis, both are in play: [docs-style](../docs-style/SKILL.md) and the type skill ([tutorial-docs](../tutorial-docs/SKILL.md), [howto-docs](../howto-docs/SKILL.md), [reference-docs](../reference-docs/SKILL.md), or [explanation-docs](../explanation-docs/SKILL.md)). In your run, name the two skills loaded (paths)—not “I reviewed writing guidelines.”
3174. **Write gate — Pass:** After writing the draft, `test -f docs/drafts/{slug}.md` succeeds (or `ls` shows the file). Only then emit the **Draft Created** block.
318
319### Publish draft (Mode 2)
320
3211. **Destination gate — Pass:** User chose a destination (from the menu or a specific path). Resolve `{destination}` to a full path; **Pass** when the parent directory exists (`test -d "$(dirname "$path")"` or project-appropriate check) **and** you are not overwriting an existing file without explicit user approval.
3222. **Move gate — Pass:** After `mv`, the file exists at `{destination}/{slug}.md` (`test -f`) and navigation updates (if applicable) are applied before claiming **Published**.