Markdown Documentation
Write READMEs, wikis, and technical pages with correct Markdown and GitHub Flavored Markdown formatting.
Overview
markdown-documentation is a journey-wide agent skill that teaches Markdown and GFM formatting—usable whenever a solo builder needs polished READMEs and docs before sharing or shipping.
Install
npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill markdown-documentationWhat is this skill?
- Covers standard headings through H6 plus GFM tables, code fences, and links
- Reference guides split across text formatting, lists, links/images, extended GFM, and collapsible sections
- Explicit When to Use list: README, wikis, blog posts, and comment formatting
- Quick-start header ladder for consistent doc structure
- Table of contents pattern for navigable long-form docs
- 5 reference guides for text, lists, links/images, extended GFM, and collapsible sections
Adoption & trust: 1k installs on skills.sh; 250 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are writing READMEs or docs but headers, lists, tables, and GFM extras render inconsistently or look unprofessional on GitHub.
Who is it for?
Builders documenting repos, skills, APIs, or side projects who want agent-guided formatting instead of guessing GFM rules.
Skip if: iOS architecture decisions or Azure deployment runbooks where domain-specific skills should lead.
When should I use this skill?
Writing markdown docs, READMEs, or formatting documentation.
What do I get? / Deliverables
You ship well-structured Markdown with correct GFM patterns and linked reference detail for harder syntax like collapsible sections.
- Formatted Markdown document
- GFM-compliant README or doc section
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Format a one-page product scope doc with headers and bullet acceptance criteria.
Rewrite the repo README with GFM tables for env vars and scripts.
Structure release notes with fenced code blocks and linked migration steps.
Standardize help-center articles with consistent list and link patterns.
How it compares
Authoring and formatting reference for human-readable docs, not a token compressor for oversized SKILL.md files.
Common Questions / FAQ
Who is markdown-documentation for?
Solo developers and small teams using AI coding agents to write READMEs, internal wikis, and technical documentation with consistent Markdown and GFM.
When should I use markdown-documentation?
In Validate when drafting landing or scope docs; in Build for README and reference folders; in Ship and Launch for changelog and distribution copy; in Grow for support articles—whenever Markdown quality matters.
Is markdown-documentation safe to install?
It is primarily formatting guidance; still review the Security Audits panel on this Prism page and the aj-geddes/useful-ai-prompts source before automation with network or shell tools.
SKILL.md
READMESKILL.md - Markdown Documentation
# Markdown Documentation ## Table of Contents - [Overview](#overview) - [When to Use](#when-to-use) - [Quick Start](#quick-start) - [Reference Guides](#reference-guides) - [Best Practices](#best-practices) ## Overview Master markdown syntax and best practices for creating well-formatted, readable documentation using standard Markdown and GitHub Flavored Markdown (GFM). ## When to Use - README files - Documentation pages - GitHub/GitLab wikis - Blog posts - Technical writing - Project documentation - Comment formatting ## Quick Start - Comment formatting ```markdown # H1 Header ## H2 Header ### H3 Header #### H4 Header ##### H5 Header ###### H6 Header # Alternative H1 ## Alternative H2 ``` ## Reference Guides Detailed implementations in the `references/` directory: | Guide | Contents | |---|---| | [Text Formatting](references/text-formatting.md) | Text Formatting | | [Lists](references/lists.md) | Lists | | [Links and Images](references/links-and-images.md) | Links and Images, Code Blocks, Tables | | [Extended Syntax (GitHub Flavored Markdown)](references/extended-syntax-github-flavored-markdown.md) | Extended Syntax (GitHub Flavored Markdown) | | [Collapsible Sections](references/collapsible-sections.md) | Collapsible Sections, Syntax Highlighting, Badges | | [Alerts and Callouts](references/alerts-and-callouts.md) | Alerts and Callouts | | [Mermaid Diagrams](references/mermaid-diagrams.md) | Mermaid Diagrams | ## Best Practices ### ✅ DO - Use descriptive link text - Include table of contents for long documents - Add alt text to images - Use code blocks with language specification - Keep lines under 80-100 characters - Use relative links for internal docs - Add badges for build status, coverage, etc. - Include examples and screenshots - Use semantic line breaks - Test all links regularly ### ❌ DON'T - Use "click here" as link text - Forget alt text on images - Mix HTML and Markdown unnecessarily - Use absolute paths for local files - Create walls of text without breaks - Skip language specification in code blocks - Use images for text content (accessibility) # Alerts and Callouts ## Alerts and Callouts ```markdown > **Note** > This is a note > **Warning** > This is a warning > **Important** > This is important information GitHub-style alerts (GFM): > [!NOTE] > Useful information > [!TIP] > Helpful advice > [!IMPORTANT] > Key information > [!WARNING] > Critical content > [!CAUTION] > Negative potential consequences ``` # Collapsible Sections ## Collapsible Sections ````markdown <details> <summary>Click to expand</summary> Hidden content goes here. - Can include lists - Code blocks - Images ```javascript const code = "works too"; ``` ```` </details> ``` ## Syntax Highlighting `````markdown Common languages: ````javascript ```typescript ```python ```bash ```java ```go ```rust ```sql ```json ```yaml ```html ```css ```dockerfile ```graphql ```markdown ```` ````` ````` ## Badges ```markdown       ``` # Extended Syntax (GitHub Flavored Markdown) ## Extended Syntax (GitHub Flavored Markdown) ```markdown Footnotes: Here's a sentence with a footnote[^1]. [^1]: This is the footnote. Definition list: Term : Definition Emoji: :smile: :rocket: :heart: :+1: :-1: :eyes: Automatic URL linking: https://github.com Task lists in issues: - [x] #739 - [ ] https://github.com/octo-org/repo/issues/1 -