---

name: gfm description: Use when writing or reviewing GitHub-flavored Markdown (README, issues, PRs, docs) argument-hint: "[file | topic | review]"

GitHub-Flavored Markdown

Arguments

$ARGUMENTS

Instructions

Parse arguments to determine task:

• File path → Write/edit markdown file
• "review" → Audit existing markdown for GFM best practices
• Topic/description → Draft markdown content

Writing Guidelines

Structure:

• Use heading hierarchy (# through ######)—GitHub auto-generates TOC for 2+ headings
• Prefer ATX headings (#) over Setext (===)
• One blank line before headings

Text styling: | Style | Syntax | |-------|--------| | Bold | **text** | | Italic | _text_ | | Bold+italic | ***text*** | | Strikethrough | ~~text~~ | | Code | `code` | | Subscript | <sub>x</sub> | | Superscript | <sup>2</sup> |

Code blocks:

```language
code here
```

Lists:

• Unordered: use - consistently
• Ordered: 1., 2., etc.
• Task lists: - [ ] incomplete, - [x] complete
• Nest by aligning under parent text

Links:

• Inline: [text](url)
• Section anchors: [text](#heading-name) (lowercase, hyphens, no punctuation)
• Relative paths for repo files: docs/CONTRIBUTING.md

Images: ![alt text](url) — always include alt text

Alerts (callouts):

> [!NOTE]
> Useful information

> [!TIP]
> Helpful advice

> [!IMPORTANT]
> Essential info

> [!WARNING]
> Urgent attention

> [!CAUTION]
> Risk warning

Footnotes:

Text with footnote[^1].

[^1]: Footnote content.

Color swatches: `#FF5733`, `rgb(255,87,51)`, `hsl(11,100%,60%)`

Review Checklist

When reviewing markdown:

• [ ] Heading hierarchy is logical (no skipped levels)
• [ ] Code blocks specify language for syntax highlighting
• [ ] Links use relative paths for repo files
• [ ] Images have meaningful alt text
• [ ] Task lists use proper syntax
• [ ] Alerts use correct > [!TYPE] format
• [ ] No trailing whitespace except intentional line breaks
• [ ] Tables are properly aligned

Examples

/gfm README.md                → Edit/create README
/gfm review docs/             → Audit markdown files in docs/
/gfm API documentation        → Draft API docs content
/gfm changelog entry          → Write changelog in GFM style