Our review
This skill guides writing technical documentation in Metabase's conversational, clear, and user-focused style, emphasizing clarity, structure, and audience awareness.
Strengths
- Provides a complete style guide with concrete examples and common pitfalls
- Focuses on action-oriented writing and removing unnecessary information
- Includes automated formatting checks with Prettier for consistency
- Encourages critical review and verification of examples for accuracy
Limitations
- Primarily tailored to Metabase's documentation style, may need adaptation for other contexts
- Does not handle generation of diagrams or complex illustrations
- Assumes basic familiarity with Markdown and documentation tools
Use this skill to write or revise any technical documentation (Markdown, MDX) following a clear, conversational, and user-focused style.
Avoid this skill for non-documentation tasks such as coding, testing, or deployment.
Security analysis
SafeThe skill only uses Bash to run 'yarn prettier' for formatting documentation files. No destructive, exfiltrating, or obfuscated commands are present. The allowed tools are standard for file operations and pose no security risk beyond typical utility use.
No concerns found
Examples
Write documentation for setting up Metabase with Docker. Use the Metabase style guide: start with who it's for, lead with actions, and use descriptive headings.Revise this documentation paragraph to follow Metabase style: remove formal language, make links descriptive, and ensure each sentence has a clear purpose. The text: 'Users should first reference the configuration guide located at the following URL. Click here to access it.'Create a step-by-step guide on how to create a dashboard in Metabase. Use the patterns from the style guide: state the goal in the heading, lead with what to do, then explain why.name: docs-write description: Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.). allowed-tools: Read, Write, Grep, Bash, Glob
Documentation Writing Skill
Use references/metabase-style-guide.md guide when writing or editing Metabase documentation. It sets the default tone, structure, and formatting so people can get answers fast and trust the steps.
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:
yarn 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 |
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Pivot Decision Framework
Documentation
Documents a strategic pivot or persevere decision with evidence, analysis, and rationale. Use when evaluating whether to change direction on a product, feature, or strategy based on market feedback.