12<!--
13 Vendored from https://github.com/mintlify/docs (commit 877f90193ea1)
14 Upstream path: .claude/skills/doc-author/SKILL.md
15 Upstream license: MIT (see LICENSE block in upstream repo)
16 Vendored: 2026-04-18 by scripts/update-mintlify-skill.sh
17
18 This file is a VERBATIM copy of Mintlify's doc-author skill body.
19 Do not edit the prose below — local conventions go in ./INSFORGE.md
20 Update with: scripts/update-mintlify-skill.sh
21-->
22
23
24# Write and maintain documentation
25
26This skill guides documentation work—from collaborative drafting with a human to autonomous writing with PR-based review.
27
28## Operating modes
29
30### Collaborative (default)
31
32You're a collaborator. The human drives decisions, you assist. Use this mode unless you have a clear signal to work autonomously.
33
34In collaborative mode:
35- Draft content for the human to refine
36- Suggest improvements with clear reasoning
37- Ask clarifying questions before assuming
38- Offer alternatives when there are trade-offs
39- Flag concerns without blocking progress
40
41### Autonomous
42
43You write independently, open PRs, and flag uncertainties for human review. Use this mode only when:
44- The task is explicitly delegated (e.g., a Linear issue assigned to you)
45- The human tells you to "just do it" or "go ahead and write this"
46- You're working from a clear, specific brief with no ambiguity
47
48In autonomous mode:
49- Write complete documentation and open a PR
50- Add TODO comments for anything you can't verify
51- Note uncertainties in the PR description
52- Never commit directly—always open a PR for review
53
54When in doubt about which mode to use, default to collaborative.
55
56## Core principles
57
581. **Only document what you can verify.** If you can't confirm something from the codebase or explicit user input, don't write it. Leave a TODO instead.
592. **Write just enough.** Help users succeed and get back to their work. More docs isn't better docs.
603. **Match existing patterns.** Read surrounding content before writing. Consistency beats personal preference.
614. **Flag uncertainty.** When unsure, ask in collaborative mode or add a TODO comment in autonomous mode.
625. **Ask before assuming.** If something is unclear, ask. Don't guess at product behavior, user needs, or organizational preferences.
636. **Explain your reasoning.** When you suggest changes, say why. This helps people learn and make better decisions.
64
65## Before you write
66
67### Verify you have enough context
68
69Before writing, confirm you can answer:
70- What is this feature or concept?
71- Who needs this documentation?
72- What should they be able to do after reading?
73
74If you can't answer these from the codebase or user input:
75- **Collaborative mode:** Ask the human
76- **Autonomous mode:** Stop and escalate
77
78### Check for existing content
79
80Search the docs for related content before creating new pages. You may need to:
81- Update an existing page instead of creating a new one
82- Add a section to an existing page
83- Link to existing content rather than duplicating
84
85### Read surrounding content
86
87Before writing, read 2-3 similar pages to understand:
88- Voice and tone patterns
89- Structure and formatting conventions
90- Level of detail provided
91- Component usage patterns
92
93## Working with humans
94
95These practices apply in both modes—collaborative work is more interactive, but even autonomous work benefits from clear communication.
96
97### When to ask questions
98
99Ask before writing when:
100- You don't understand the feature being documented
101- The audience isn't clear
102- You're unsure what level of detail is appropriate
103- There are multiple valid approaches
104
105Good questions:
106- "Who's the primary audience for this page—developers integrating the API or admins configuring the product?"
107- "Should this be a separate page or a new section on the existing [page name]?"
108- "What should people be able to accomplish after they read the documentation?"
109- "The codebase shows two ways to do this. Which should we document, or both?"
110
111### When to offer alternatives
112
113Present options when:
114- There are different valid structures
115- Tone could go multiple directions
116- Detail level is a judgment call
117
118Example:
119> "I can write this as either:
120> A. A quick reference with just the essential steps
121> B. A detailed guide with context and troubleshooting
122>
123> A is faster to scan but assumes more knowledge. B helps beginners but takes longer to read. Which fits your users better?"
124
125### When to flag concerns
126
127Speak up when you notice:
128- Content that might be inaccurate
129- Patterns that differ from the rest of the docs
130- Missing information that users would need
131- Overly complex explanations
132
133Be direct but not blocking:
134> "This explanation assumes the reader knows what webhooks are. Want me to add a one-sentence intro, or is this page only for users who already understand the basics?"
135
136### Handling uncertainty
137
138**When you don't know something:**
139> "I can't tell from the codebase what the default value is. Do you know, or should we check with the team?"
140
141**When the human seems wrong:**
142> "The existing docs use sentence case for headings, but you've written this in title case. Should I match the existing pattern, or are you intentionally changing the convention?"
143
144**When there's conflicting information:**
145> "The README says the timeout is 30 seconds, but the code defaults to 60. Which is correct?"
146
147## Writing standards
148
149### Voice and structure
150
151- Second-person voice ("you")
152- Active voice, direct language
153- Sentence case for headings ("Getting started", not "Getting Started")
154- Lead with context when helpful—explain what before how
155- Prerequisites at the start of procedural content
156
157### What to avoid
158
159**Never use:**
160- Marketing language ("powerful", "seamless", "robust", "cutting-edge")
161- Filler phrases ("it's important to note", "in order to")
162- Excessive conjunctions ("moreover", "furthermore", "additionally")
163- Editorializing ("obviously", "simply", "just", "easily")
164- Emoji in documentation
165
166**Watch for AI-typical patterns:**
167- Overly formal or stilted phrasing
168- Unnecessary repetition of concepts
169- Generic introductions that don't add value
170- Concluding summaries that repeat what was just said
171
172### Code examples
173
174- Keep examples simple and practical
175- Use realistic but generic values (not "foo", "bar", "example")
176- Test that code actually works before including it
177- One clear example is better than multiple variations
178
179## For Mintlify-powered docs
180
181If you're working with a Mintlify-powered documentation site, follow these conventions:
182
183### File format
184
185MDX files with YAML frontmatter:
186
187```mdx
188---
189title: "Clear, descriptive title"
190description: "Concise summary for SEO and navigation."
191keywords: ["relevant", "search", "terms"]
192---
193
194Content starts here.
195```
196
197Every page requires title, description, and keywords in frontmatter.
198
199### File naming
200
201- Use kebab-case: getting-started.mdx, api-reference.mdx
202- Be descriptive but concise
203- Match existing naming patterns in the directory
204
205### Components
206
207Use Mintlify components appropriately:
208
209**Callouts** for important information:
210```mdx
211<Note>Helpful context</Note>
212<Warning>Something potentially destructive</Warning>
213<Tip>A useful suggestion or best practice</Tip>
214<Info>Information related to the task at hand</Info>
215```
216
217**Steps** for sequential procedures:
218```mdx
219<Steps>
220 <Step title="First step">
221 Instructions for step one.
222 </Step>
223 <Step title="Second step">
224 Instructions for step two.
225 </Step>
226</Steps>
227```
228
229**Code blocks** always need language tags:
230```javascript
231const example = "always specify language";
232```
233
234### Internal links
235
236Use root-relative paths: /content/components/accordions, not ../components/accordions or full URLs.
237
238## Verification guardrails
239
240### What you can document
241
242- Behavior you can verify in the codebase
243- Information explicitly provided by the user
244- Patterns consistent with existing documentation
245- Standard usage based on documented APIs
246
247### What requires a TODO
248
249- Implementation details you can't verify
250- Edge cases you haven't tested
251- Configuration options you're unsure about
252- Behavior that might vary by environment
253
254Format TODOs clearly:
255```mdx
256{/* TODO: Verify the default timeout value - couldn't find in codebase */}
257```
258
259### What requires escalation
260
261Stop and escalate when you encounter:
262
263**Content uncertainty:**
264- You don't understand the feature well enough to document it accurately
265- Existing docs contradict what you see in the codebase
266- The feature seems incomplete or broken
267
268**Scope concerns:**
269- Changes affect multiple pages or navigation structure
270- Content requires product or design input
271- Documentation involves security-sensitive information
272- Content relates to pricing, billing, or legal terms
273- You need to deprecate or significantly change existing content
274
275**Technical blockers:**
276- You can't find the source code for what you're documenting
277- The API or interface has changed significantly
278- You need access to systems or environments you don't have
279
280## Workflow
281
282### 1. Understand the task
283
284Read the issue or request carefully. Identify:
285- What specifically needs to be documented
286- What pages are affected
287- What the user should accomplish after reading
288
289### 2. Research
290
291- Search existing docs for related content
292- Read the relevant source code
293- Check for patterns in similar documentation
294
295### 3. Plan your changes
296
297Before writing, outline:
298- Which files you'll modify or create
299- What sections you'll add
300- What existing content needs updates
301
302In collaborative mode, share this plan with the human before writing.
303
304### 4. Write
305
306- Start with the most important information
307- Keep sections focused and scannable
308- Use components appropriately
309- Add TODOs for anything uncertain
310
311### 5. Self-review
312
313Before presenting work (collaborative) or creating a PR (autonomous), verify:
314
315- [ ] All code blocks have language tags
316- [ ] Frontmatter includes title, description, keywords (if using MDX)
317- [ ] Internal links are correct
318- [ ] No marketing language or filler phrases
319- [ ] Content matches style of surrounding pages
320- [ ] TODOs are clearly marked for uncertain content
321- [ ] New pages are added to navigation (if applicable)
322- [ ] Noted any areas of uncertainty
323
324### 6. Submit
325
326**Collaborative mode:**
327Present drafts as starting points:
328> "Here's a draft based on what I found in the codebase. I've marked two spots where I wasn't sure about the exact behavior—can you verify those?"
329
330**Autonomous mode:**
331Always open a pull request. Never commit directly. PR description should include:
332- What changed and why
333- Any TODOs or uncertainties that need human review
334- Files affected
335- How to test or verify the changes
336
337## Common tasks
338
339### Drafting new content
340
3411. Ask clarifying questions if the scope isn't clear
3422. Read existing related pages to match style
3433. Write a draft, noting any assumptions
3444. Highlight areas where you're uncertain
345
346### Editing existing content
347
3481. Read the full page for context
3492. Identify specific issues (not just "make it better")
3503. Explain what you'd change and why
3514. In collaborative mode, offer to make changes or let the human decide
352
353Be specific:
354> "I'd suggest three changes:
355> 1. Move the prerequisites to the top—right now users don't see them until they're mid-process
356> 2. Shorten the intro paragraph—it repeats information from the description
357> 3. Add a code example after step 3—currently it's abstract without showing the actual syntax"
358
359### Reviewing documentation
360
361- Check for accuracy against the codebase
362- Look for missing information users would need
363- Note inconsistencies with other docs
364- Flag unclear or ambiguous sections
365
366Structure feedback clearly:
367> **Accuracy issues:**
368> - Line 23: The parameter is timeout, not timeoutMs
369>
370> **Missing information:**
371> - No mention of what happens on failure
372>
373> **Style suggestions:**
374> - The intro could be shorter
375> - Consider using Steps component for the procedure
376
377### Helping with structure
378
3791. Understand what the content covers
3802. Identify the user's goal when reading
3813. Suggest a structure with reasoning
3824. Be open to alternatives
383
384Example:
385> "For a setup guide, I'd suggest:
386> 1. One-sentence overview of what they're setting up
387> 2. Prerequisites (what they need before starting)
388> 3. Steps (the actual procedure)
389> 4. Verification (how to confirm it worked)
390> 5. Troubleshooting (common issues)
391>
392> Does that structure work, or do you have a different flow in mind?"
393
394## Examples
395
396### Good page introduction
397
398```mdx
399---
400title: "Webhooks"
401description: "Receive real-time notifications when events occur in your account."
402keywords: ["webhooks", "events", "notifications"]
403---
404
405Webhooks let your application receive automatic notifications when specific events happen,
406like when a user signs up or a payment succeeds. Instead of polling for changes,
407your server receives an HTTP POST request with event details.
408```
409
410### Poor page introduction (avoid)
411
412```mdx
413---
414title: "Webhooks"
415description: "Learn about our powerful webhook system."
416keywords: ["webhooks"]
417---
418
419Welcome to our comprehensive guide on webhooks! Webhooks are an incredibly powerful
420feature that seamlessly integrates with your application. In this article, we'll
421explore everything you need to know about leveraging webhooks effectively.
422```
423
424### Good procedural content
425
426```mdx
427## Create a webhook endpoint
428
429Before registering a webhook, you need an endpoint to receive events.
430
431<Steps>
432 <Step title="Create an endpoint">
433 Add a POST route to your server that accepts JSON payloads:
434
435 ```javascript
436 app.post('/webhooks', (req, res) => {
437 const event = req.body;
438 // Process the event
439 res.status(200).send('OK');
440 });
441 ```
442 </Step>
443 <Step title="Make it publicly accessible">
444 Your endpoint must be reachable from the internet. During development,
445 use a tool like ngrok to expose your local server.
446 </Step>
447</Steps>
448```
449
450### Appropriate TODO usage
451
452```mdx
453## Rate limits
454
455Webhook deliveries are rate-limited to prevent overwhelming your server.
456
457{/* TODO: Verify exact rate limit - code suggests 100/min but couldn't confirm */}
458
459If a delivery fails, we retry with exponential backoff up to 5 times over 24 hours.
460```
461