markdown-mastery
Markdown Mastery: Advanced markdown, Mermaid diagrams, GitHub-flavored markdown, formatting patterns
Profile →npx skills add cosmicstack-labs/mercury-agent-skills --skill markdown-mastery --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Guides an agent to produce expressive, well-formatted Markdown content, covering basic to advanced techniques, diagrams, and tooling for consistency across documents.
How it works
- Emphasizes treating Markdown as code: linting, automatic formatting, reasonable line lengths, and semantic element usage.
- Stresses purposeful use of elements: avoid misusing bold, inline code, or manual numbering; prioritize semantic Markdown.
- Asserts diagrams are documentation: Mermaid diagrams should be embedded and versioned with code.
- Encourages writing for plain text first so documents remain scannable without renderers.
- Provides a maturity model from Basic to Expert with concrete capabilities (tables, footnotes, GFM, HTML embedding, CI tooling, multi-file includes).
- Includes an Actionable Guidance section with extended Markdown syntax examples, Mermaid setups, and various diagram types (flowcharts, sequences, Gantt, class, ERD, state, pie charts, user journeys, Git graphs).
- Covers GitHub-Flavored Markdown specifics for mentions, references, autolinks, and emoji mappings.
- Offers Markdown linting, auto-formatting configurations, and a CI pipeline example for quality gates.
When to use it
Use when creating or validating Markdown content that aims to be readable in plain text, includes diagrams, or requires consistent formatting across multi-file documentation. Suitable for developers producing multi-section documents and technical writers aiming for advanced diagrams.
What it can touch
- Tools: claude-code
- Commands and workflows shown include Mermaid CLI setup, npx mmdc invocations, and various Markdown diagram blocks. Specific blocks enumerate commands and file patterns such as
npm install -g @mermaid-js/mermaid-cli,npx mmdc -i diagram.mmd -o diagram.png, andnpx prettier --write '**/*.md'.
Caveats
- License noted as MIT. (FACTS: license: MIT)
- No outcomes promised beyond the described actions and tooling usage. (FACTS: description and content focus on instructions and examples; no outcome guarantees.)
# Markdown Mastery Write expressive, beautifully formatted markdown — from basic documents to complex technical content with diagrams, advanced formatting, and automated tooling. ## Core Principles ### 1. Markdown Is Code — Treat It With Respect Formatting consistency matters. Lint your markdown, format it automatically, keep line lengths reasonable, and use semantic elements correctly. ### 2. Every Element Has a Purpose Don't use bold where a heading belongs. Don't use inline code where a code block is needed. Don't use manual numbering where list numbering works. Semantic markdown is readable markdown. ### 3. Diagrams Are Documentation A Mermaid diagram is worth a thousand words of architectural explanation. Embed diagrams directly in documentation — they version alongside the code and never go out of sync. ### 4. Write for Plain Text First Markdown's superpower is readability in its raw form. Even without a renderer, your document should be scannable and understandable. --- ## Markdown Mastery Maturity Model | Level | Syntax Knowledge | Formatting | Diagrams | Tooling | Complex Documents | |-------|-----------------|------------|----------|---------|-------------------| | **1: B
- Core Principles
- 1. Markdown Is Code — Treat It With Respect
- 2. Every Element Has a Purpose
- 3. Diagrams Are Documentation
- 4. Write for Plain Text First
- Markdown Mastery Maturity Model
- Actionable Guidance
- Extended Markdown Syntax Reference
- Mermaid Diagrams
- Table of Contents
- Internal Links
- Embeds
- Tags
- Block References
Mermaid CLI (for rendering locally) npm install -g @mermaid-js/mermaid-cli Render a mermaid file npx mmdc -i diagram.mmd -o diagram.png VS Code extension: "Markdown Preview Mermaid Support" git log --oneline journalctl -u app.service -n 50
What does the markdown-mastery skill do?
Markdown Mastery: Advanced markdown, Mermaid diagrams, GitHub-flavored markdown, formatting patterns
How do I install it?
Run `npx skills add cosmicstack-labs/mercury-agent-skills --skill markdown-mastery --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From cosmicstack-labs/mercury-agent-skills, a repository with 364 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.