docs-write
Provides writing principles and formatting standards to produce conversational and concise technical documentation.
Install
mkdir -p .claude/skills/docs-write && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/127" && unzip -o skill.zip -d .claude/skills/docs-write && rm skill.zipInstalls to .claude/skills/docs-write
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).Key capabilities
- →Draft documentation steps and explanations
- →Edit content for clarity and tone
- →Format markdown files with consistent styling
- →Verify code examples for accuracy
- →Apply specific formatting for links and UI elements
How it works
The skill applies a conversational, user-focused style guide to draft and edit documentation. It uses the Prettier tool via a bash command to enforce consistent formatting.
Inputs & outputs
When to use docs-write
- →Writing technical docs for a new feature
- →Editing documentation for clarity
- →Standardizing markdown documentation formatting
- →Crafting user-focused technical guides
About this skill
Documentation Writing Skill
@./../_shared/metabase-style-guide.md
When writing documentation
Start here
- Who is this for? Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
- What do they need? Get them to the answer fast. Nobody wants to be in docs longer than necessary.
- What did you struggle with? Those common questions you had when learning? Answer them (without literally including the question).
Writing process
Draft:
- Write out the steps/explanation as you'd tell a colleague
- Lead with what to do, then explain why
- Use headings that state your point: "Set SAML before adding users" not "SAML configuration timing"
Edit:
- Read aloud. Does it sound like you talking? If it's too formal, simplify.
- Cut anything that doesn't directly help the reader
- Check each paragraph has one clear purpose
- Verify examples actually work (don't give examples that error)
Polish:
- Make links descriptive (never "here")
- Backticks only for code/variables, bold for UI elements
- American spelling, serial commas
- Keep images minimal and scoped tight
Format:
- Run prettier on the file after making edits:
bun run prettier --write <file-path> - This ensures consistent formatting across all documentation
Common patterns
Instructions:
Run:
\`\`\`
command-to-run
\`\`\`
Then:
\`\`\`
next-command
\`\`\`
This ensures you're getting the latest changes.
Not: "(remember to run X before Y...)" buried in a paragraph.
Headings:
- "Use environment variables for configuration" ✅
- "Environment variables" ❌ (too vague)
- "How to use environment variables for configuration" ❌ (too wordy)
Links:
- "Check out the SAML documentation" ✅
- "Read the docs here" ❌
Watch out for
- Describing tasks as "easy" (you don't know the reader's context)
- Using "we" when talking about Metabase features (use "Metabase" or "it")
- Formal language: "utilize", "reference", "offerings"
- Too peppy: multiple exclamation points
- Burying the action in explanation
- Code examples that don't work
- Numbers that will become outdated
Quick reference
| Write This | Not This |
|---|---|
| people, companies | users |
| summarize | aggregate |
| take a look at | reference |
| can't, don't | cannot, do not |
| Filter button | `Filter` button |
| Check out the docs | Click here |
When not to use it
- →When the content requires formal or academic language
- →When the documentation needs to be overly peppy or use multiple exclamation points
Prerequisites
Limitations
- →Requires manual verification of content accuracy
- →Limited to documentation files like markdown and MDX
How it compares
Unlike generic writing, this skill enforces specific stylistic constraints like serial commas, American spelling, and a conversational tone to ensure consistency across technical files.
Compared to similar skills
docs-write side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| docs-write (this skill) | 22 | 6mo | No flags | Beginner |
| content-research-writer | 15 | 9mo | No flags | Beginner |
| doc-coauthoring | 16 | 8mo | No flags | Beginner |
| research-grants | 6 | 7mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by metabase
View all by metabase →You might also like
content-research-writer
ComposioHQ
Assists in writing high-quality content by conducting research, adding citations, improving hooks, iterating on outlines, and providing real-time feedback on each section. Transforms your writing process from solo effort to collaborative partnership.
doc-coauthoring
anthropics
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
research-grants
davila7
Write competitive research proposals for NSF, NIH, DOE, and DARPA. Agency-specific formatting, review criteria, budget preparation, broader impacts, significance statements, innovation narratives, and compliance with submission requirements.
teams-channel-post-writer
daymade
Creates educational Teams channel posts for internal knowledge sharing about Claude Code features, tools, and best practices. Applies when writing posts, announcements, or documentation to teach colleagues effective Claude Code usage, announce new features, share productivity tips, or document lessons learned. Provides templates, writing guidelines, and structured approaches emphasizing concrete examples, underlying principles, and connections to best practices like context engineering. Activates for content involving Teams posts, channel announcements, feature documentation, or tip sharing.
write-docs
tldraw
Writing SDK documentation for tldraw. Use when creating new documentation articles, updating existing docs, or when documentation writing guidance is needed. Applies to docs in apps/docs/content/.
anti-slop
rand
Comprehensive toolkit for detecting and eliminating "AI slop" - generic, low-quality AI-generated patterns in natural language, code, and design. Use when reviewing or improving content quality, preventing generic AI patterns, cleaning up existing content, or enforcing quality standards in writing, code, or design work.