Skip to content
cccskills
FreePublished on GitHub

docs-write

Create and edit Markdown or MDX documentation in Metabase's clear, conversational style. Put actions first, tailor explanations to readers, improve headings and links, check examples, and apply consistent formatting.

OriginalShow the original description

Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).

See how to install

Good for

  • Draft task-focused instructions for readers
  • Simplify overly formal documentation
  • Improve headings, links, and interface labels
  • Check examples and format edited documents

Files included (1)

  • SKILL.md2.8 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Documentation Writing Skill

@./../_shared/metabase-style-guide.md

When writing documentation

Start here

  1. Who is this for? Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
  2. What do they need? Get them to the answer fast. Nobody wants to be in docs longer than necessary.
  3. 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:

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 ThisNot This
people, companiesusers
summarizeaggregate
take a look atreference
can't, don'tcannot, do not
Filter button`Filter` button
Check out the docsClick here

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

adaptyv

FreeSummary

Support experimental validation of designed proteins through a cloud laboratory. Prepare and optimize sequences, submit tests for binding, expression, thermal stability, or enzyme activity, track experiment progress, and retrieve results through the API.

  • Submit designed proteins for binding tests
  • Request expression, thermal stability, or enzyme activity tests
  • Optimize sequences for solubility before experiments
foryourhealth111-pixel/Vibe-Skills3.8KUpdated Oct 20, 2026

aeon

FreeSummary

Analyze time series, observations ordered over time, using aeon in Python. Build classification, prediction, and clustering workflows, detect unusual patterns or changes, and compare methods through an interface compatible with scikit-learn.

  • Classifying time series by their patterns
  • Forecasting future values from past observations
  • Detecting anomalies and change points
foryourhealth111-pixel/Vibe-Skills3.8KUpdated Oct 20, 2026

algorithmic-art

FreeSummary

Create original generative art with p5.js, using code to produce patterns and motion. Receive a written artistic concept and an interactive HTML viewer with adjustable parameters, reproducible random variations, seed navigation, and PNG downloads.

  • Create art from particle motion and flow fields
  • Explore patterns by adjusting sliders
  • Reproduce a favorite variation with the same seed
foryourhealth111-pixel/Vibe-Skills3.8KUpdated Oct 20, 2026

alpha-vantage

FreeSummary

Retrieve stock prices, exchange rates, cryptocurrency prices, company financial statements, and economic indicators through the Alpha Vantage API. It also covers historical data, news sentiment, and technical indicators, which summarize price and trading patterns.

  • Retrieve historical stock prices and trading volumes
  • Collect company financial statements and earnings data
  • Check foreign exchange and cryptocurrency prices
foryourhealth111-pixel/Vibe-Skills3.8KUpdated Oct 20, 2026

Design backend systems with clear boundaries between business rules, databases, and external services. Use Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to organize new applications, refactor existing code, and make core logic easier to test.

  • Planning the structure of a new backend
  • Refactoring tightly coupled applications
  • Testing business rules independently of external services
foryourhealth111-pixel/Vibe-Skills3.8KUpdated Oct 20, 2026

astropy

FreeSummary

Helps process astronomical data in Python by converting coordinates, units, and time scales, working with FITS observation files, matching object catalogs, and calculating distances using cosmological models.

  • Converting celestial coordinates
  • Reading and editing FITS observation files
  • Matching objects across astronomical catalogs
foryourhealth111-pixel/Vibe-Skills3.8KUpdated Oct 20, 2026

See all skills by foryourhealth111-pixel

Report a problem with this skill