Skip to content

aalmada/agent-package-manager-extension / .agents/skills/markdown-best-practices

markdown-best-practices

Verified

ALWAYS use this skill whenever creating, editing, or reviewing any Markdown (.md) file — README.md, SKILL.md, AGENTS.md, CONTRIBUTING.md, changelogs, or any other Markdown documentation — even for small edits. Write and review Markdown files for consistent, correctly-rendering formatting: heading hierarchy and spacing, list marker and indentation consistency, fenced code block languages and blank-line spacing, table pipe and column consistency, link and image conventions, and whitespace hygiene. USE FOR: authoring or reviewing README.md, SKILL.md, AGENTS.md, or any Markdown documentation; fixing inconsistent headings, lists, code fences, or tables; fixing issues reported by Markdown linters such as markdownlint; choosing link/image/emphasis styles; general Markdown formatting conventions. DO NOT USE FOR: non-Markdown formats (reStructuredText, AsciiDoc); prose tone or content-quality review; the SKILL.md authoring workflow itself (see create-skill); AGENTS.md content structure (see agents-md).

Markdown Best Practices

Markdown renders differently across parsers when formatting is inconsistent or incomplete. These conventions keep documents portable across GitHub, static-site generators, and editor previews.

Anatomy

FilePurpose
SKILL.mdTop pitfalls, workflow, reference table
references/headings-and-structure.mdHeading hierarchy, spacing, single-title rule
references/lists-and-code-blocks.mdList markers/indentation, fenced code languages and spacing
references/tables.mdTable pipe/column consistency, blank-line spacing
references/links-images-and-whitespace.mdLink/image conventions, whitespace hygiene

Top Pitfalls

PitfallFix
Fenced code block with no language tagAlways tag it: ```bash, ```json, ```text for plain/pseudocode
Heading with no blank line above/belowBlank line before and after every heading
Heading levels skip (H1 → H3)Increment by exactly one level at a time
More than one H1 in a documentExactly one H1 as the title; everything else H2+
Table rows padded inconsistentlyPick one column style and use it for every row, including the separator
Mixed list markers (-, *, +) in one documentPick one marker and use it throughout
List/table/code block missing surrounding blank linesBlank line before and after each block
Bare URL with no link syntaxWrap it: <https://...> or [text](https://...)
Trailing whitespace or hard tabsStrip trailing spaces (except an intentional 2-space line break); use spaces, not tabs
Generic link text ("click here", "link")Use descriptive text, e.g. "the setup guide"

Workflow: Writing New Markdown

  1. Start with a single H1 title; every other heading is H2 or deeper, incrementing by one level at a time.
  2. Add a blank line before and after every heading, list, table, and fenced code block.
  3. Tag every fenced code block with a language (bash, json, yaml, text, ...).
  4. Pick one style each for list markers, emphasis (*/_), and table pipe padding — apply it document-wide.
  5. Give links descriptive text and images alt text; wrap bare URLs.
  6. End the file with exactly one trailing newline; no trailing whitespace.

Workflow: Reviewing Existing Markdown

  1. Scan headings top to bottom: one H1, no level skips, no duplicates, blank lines around each.
  2. Scan lists and tables for mixed markers, ragged indentation, or inconsistent pipe padding.
  3. Scan fenced code blocks for a missing language tag.
  4. Scan links for bare URLs, empty destinations, and generic text.
  5. Strip trailing whitespace and collapse multiple blank lines to one.

Reference Files

FileLoad When
references/headings-and-structure.mdStructuring or fixing a document's heading hierarchy
references/lists-and-code-blocks.mdWriting/reviewing lists or fenced code blocks
references/tables.mdWriting/reviewing Markdown tables
references/links-images-and-whitespace.mdWriting/reviewing links, images, or general whitespace
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall