markdown-a11y

Review markdown files for accessibility issues and provide prioritized linting commands.

Updated Apr 14, 2026
One-click install
npx skills add https://github.com/dallay/opencode-docker --skill markdown-a11y
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: markdown-a11y
Source: https://github.com/dallay/opencode-docker/tree/main/config/skills/markdown-a11y
Command: npx skills add https://github.com/dallay/opencode-docker --skill markdown-a11y

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Ensures markdown documentation is readable and navigable for people using assistive technologies by identifying accessibility issues that are commonly overlooked in READMEs, docs, and profiles.

Core Features & Use Cases

  • Descriptive links: Detects and recommends replacing generic link text like "here" with context-rich link labels.
  • Image alt text guidance: Flags missing, empty, or filename-based alt text and suggests concise, meaningful alternatives.
  • Heading hierarchy & lists: Identifies skipped heading levels, fake headings, and improper list markup to improve navigation for screen readers.
  • Emoji and plain language: Flags excessive or meaning-bearing emoji and suggests clearer, plain-language rewrites.
  • Prioritized fixes & tooling: Provides a ranked remediation list and practical linting commands (e.g., markdownlint) to validate changes.

Quick Start

Review README.md for markdown accessibility and return a prioritized list of actionable fixes for images, headings, links, lists, emoji, and plain language.

Frequently Asked Questions about markdown-a11y

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check markdown files for accessibility issues?

To check markdown files for accessibility issues, review documentation pages and READMEs to enforce descriptive link text, meaningful image alt text, correct heading hierarchy, proper list markup, and restrained emoji use for screen reader compatibility.

What markdown accessibility problems affect screen reader navigation?

Markdown accessibility problems that affect screen reader navigation include skipped heading levels, fake headings, generic link text like "here", missing image alt text, and improper list markup, all of which disrupt assistive technology navigation.

How do I fix heading hierarchy and missing alt text in documentation?

Fix heading hierarchy and missing alt text in documentation by identifying skipped heading levels and flagging filename-based or empty alt text, then replacing them with correct sequential markup and concise, meaningful image descriptions.

Can I use markdownlint to enforce accessible heading and link standards?

You can use markdownlint to enforce accessible heading and link standards by applying practical linting commands that validate descriptive link text, correct heading hierarchy, and proper list markup changes in your markdown files.

Does excessive emoji use impact markdown accessibility for assistive technologies?

Excessive emoji use impacts markdown accessibility because screen readers announce every emoji, which disrupts the reading flow; flagging meaning-bearing emoji and rewriting with plain language ensures inclusive documentation.

What is the best way to audit a GitHub profile README for inclusive language?

The best way to audit a GitHub profile README for inclusive language is to review the markdown for screen reader compatibility, checking for descriptive links, proper list markup, and plain language rewrites to ensure accessible documentation.