markdown-documentation — Claude Code skill: Markdown rules
A skill that gives the agent a fixed set of Markdown rules for READMEs, wikis and docs pages. Useful when the model writes the text and it has to look consistent.
npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a claude-codeWhat markdown-documentation does
The skill covers plain Markdown and GitHub Flavored Markdown: headings, lists, links and images, tables, code blocks, collapsible sections, alerts and Mermaid diagrams. Reference guides live in the references/ directory, one file per topic: text-formatting.md, lists.md, links-and-images.md, extended-syntax-github-flavored-markdown.md, collapsible-sections.md, alerts-and-callouts.md, mermaid-diagrams.md.
A separate section lists practices. It advises descriptive link text, alt text on images, a language tag on every code block, lines under 80-100 characters and a table of contents for long documents. Things to avoid: "click here" links, absolute paths to local files, images used for text, and walls of text without breaks.
The skill installs into Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. In Claude the file lands at ~/.claude/skills/markdown-documentation/SKILL.md, in Cursor at .cursor/skills/markdown-documentation/SKILL.md, in Copilot at .github/skills/markdown-documentation/SKILL.md. The reference examples are written in English, so if your docs are in another language you will be adapting them yourself. It is a syntax skill, not a translation one.
What it helps with
- write a README for a new repository
- make scattered docs pages follow one style
- format a table and code blocks for a GitHub wiki
- add a table of contents and alt text to a long document
- catch broken links and markup before publishing
Example prompts for the agent
- Write a README for this project following the markdown-documentation skill
- Format this comparison table in GitHub Flavored Markdown
- Check my docs page for markup and link mistakes
How to install markdown-documentation
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a claude-code2Manually: put the files in place
~/.claude/skills/markdown-documentation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/markdown-documentation/
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a codex2Manually: put the files in place
.agents/skills/markdown-documentation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a cursor2Manually: put the files in place
.cursor/skills/markdown-documentation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aj-geddes/useful-ai-prompts markdown-documentation2Manually: put the files in place
.github/skills/markdown-documentation/SKILL.md1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a gemini-cli2Platform CLI
gemini skills install https://github.com/aj-geddes/useful-ai-prompts --path skills/markdown-documentationManually: put the files in place
.devin/skills/markdown-documentation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about markdown-documentation
How do I install markdown-documentation in Claude?
Run npx skills add aj-geddes/useful-ai-prompts --skill markdown-documentation -a claude-code. The skill file then sits at ~/.claude/skills/markdown-documentation/SKILL.md.
What does the markdown-documentation skill do?
It describes Markdown and GitHub Flavored Markdown syntax plus formatting practices for READMEs, wikis and docs pages. The agent follows those rules when it writes or edits text.
Which platforms does the skill support?
Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Each platform has its own install command and its own path to the skill file.
Source text
SKILL.md · MIT
--- name: markdown-documentation description: > Master markdown formatting, GitHub Flavored Markdown, README files, and documentation formatting. Use when writing markdown docs, READMEs, or formatting 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)
© aj-geddes · MIT · aj-geddes/useful-ai-prompts
