Better Md Skill

Better-md-skill

Better-md-skill is a Markdown documentation engineering skill for AI coding agents. It creates, improves, restructures, audits, and validates Markdown (READMEs, API docs, tutorials, specifications, and changelogs) with CommonMark and GitHub Flavored Markdown awareness, markdownlint-inspired checks, GitHub documentation style, evidence-based reading psychology, and visual README design.

Use it when you want AI-assisted Markdown work to be correct, readable, and standards-aligned. It provides:

• Structured workflows for every document type, with diff-oriented, meaning-preserving edits
• A validation gate that verifies links, assets, and content integrity, and never fabricates
• Evidence-based readability rules: goal-first headings, chunked prose, restrained emphasis
• Visual asset suggestions: precise invisible comments where screenshots or diagrams belong

[!CAUTION] Better-md-skill is an opinionated quality standard, not a beautifier. It deliberately leaves good documents alone, never rewrites content beyond structure, and refuses to invent URLs, icons, badges, or image paths. Treat it as a standards layer on top of your agent, not a content author.

Where to Start

1. Install the skill into your agent (see Install).
2. Restart your agent's session. Skills are loaded at session start.
3. Open a document and ask your agent:

Improve this README using Better-md-skill.

[!TIP] For a check without changes:

Audit this Markdown without changing it.

The skill reports what it changed, why, and what remains unverified.

Choose Your Path

• New to the skill: Start with Install and Use it to improve your first document.
• Evaluating it: Run the test suite, 51 cases covering every capability.
• Extending it: Read the Contributing Guide and add a fixture for any behavioral change.

Navigate This Repository

Install

The skill follows the Agent Skills open standard, so the same files work in any SKILL.md-capable agent: Claude Code, OpenCode, Codex, Gemini CLI, Cursor, GitHub Copilot, and 30+ more.

npm install -g https://github.com/FrekiJoms/better-md-skill/archive/refs/heads/main.tar.gz

The postinstall hook copies skills/better-md-skill/ into every supported agent's personal skill directory. The tarball URL is recommended over the github:owner/repo shorthand, whose git-dependency packaging is unreliable on some npm 11.x versions.

[!TIP] Alternative installs:

# From a local checkout via the skills CLI
npx skills add ./better-md-skill --skill better-md-skill -g --copy -y

# From GitHub via the skills CLI
npx skills add FrekiJoms/better-md-skill --skill better-md-skill -g --copy -y

# From a checkout, manually
npm run install:skills          # install to all supported agents
npm run install:skills:dry      # preview without writing
node scripts/install.mjs --agents opencode claude-code
node scripts/install.mjs --list

For OpenCode you can also point skills.paths at this repository in opencode.json (scanned recursively for **/SKILL.md). Restart the agent's session after installing. Skills are not hot-reloaded.

Uninstall

Remove the skill and its copies from every supported agent:

npm uninstall -g better-md-skill

The preuninstall hook deletes the better-md-skill folder from each agent's personal skill directory. From a checkout, or if the hook did not run, remove the copies manually:

node scripts/install.mjs --uninstall
npm run uninstall:skills          # same command
node scripts/install.mjs --uninstall --agents opencode claude-code

Or delete the folders directly: ~/.config/opencode/skills/better-md-skill, ~/.claude/skills/better-md-skill, ~/.agents/skills/better-md-skill, ~/.codex/skills/better-md-skill, ~/.gemini/skills/better-md-skill, ~/.config/github-copilot/skills/better-md-skill.

Use it

Ask your agent, for example:

Improve this README using Better-md-skill.

Improve the structure but preserve all content.

Make this GitHub README more polished and add appropriate technology icons.

The skill picks the right rules for the document type and target renderer (GitHub vs portable CommonMark), then reports what it changed, why, and what remains unverified.

What it improves

• Structure: heading hierarchy, lists, tables, code fences, links, whitespace, fixed per document type
• Readability: headings that lead with the reader's goal, chunked prose, restrained emphasis (evidence-based; see references/reading-psychology.md)
• GitHub readiness: GFM tables, task lists, alerts, relative links, Mermaid, theme-aware images; portable documents stay portable
• Validation: a post-edit gate that checks integrity, accessibility, and anti-fabrication
• Visual design: verified tech icons, truthful badges, logos, screenshots, diagrams
• Asset authoring: creates real SVG banners, logos, and icon sets in the repository when they are missing (SVG is text; no capture tools needed)
• Visual suggestions: when a screenshot, diagram, or GIF would help but the agent cannot create it, it leaves a precise invisible VISUAL SUGGESTION comment in place (below)

How visual suggestions work

After improving a document, the skill reviews it for visual opportunities. If the current agent cannot create or insert screenshots, images, or other assets, it places a precise, invisible HTML comment exactly where the asset belongs. Never at the bottom, never a fake image reference:

## Dashboard

The dashboard provides an overview of sales, revenue, and recent transactions.

<!-- VISUAL SUGGESTION [SCREENSHOT]:
Recommended file: `assets/screenshots/dashboard-overview.png`

Add a screenshot of the main dashboard here.
Show the sidebar, KPI cards, revenue chart, and recent transactions.
Purpose: Provide a visual overview of the application's primary interface.
-->

The comment names the asset type (SCREENSHOT, DIAGRAM, ARCHITECTURE, WORKFLOW, GIF, VIDEO, UI_PREVIEW, BEFORE_AFTER, CHART, ILLUSTRATION, LOGO, TECH_STACK), what to show, which details, why, and sometimes a filename or alt text. A human or a visual-capable agent can act on it later. If the agent genuinely has the tools and you asked for visuals, it creates the asset, verifies it exists, then references it.

How it stays honest

After every edit, the skill re-reads the document and checks:

• Heading hierarchy (single H1, no skipped levels, blank lines around headings)
• Lists, tables, and code fences (consistency, indentation, column counts, language identifiers)
• Whitespace (no trailing spaces, no hard tabs, single final newline)
• Links and image references (well-formed, defined, resolvable, alt text present)
• GitHub-specific syntax (tables, task lists, alerts)
• Content integrity (no lost, reordered, or reworded content; code byte-identical)
• No fabrication (every URL, icon, badge, and asset is real, verified, or documented as a pattern)

How it works

Eight reference modules are loaded conditionally; only the rules a document needs are used:

skills/better-md-skill/
├── SKILL.md                    Core behavior: workflow, decision rules, preservation rules
└── references/
    ├── github-gfm.md           GitHub Flavored Markdown specifics
    ├── commonmark.md           CommonMark core and portability
    ├── markdownlint.md         markdownlint-inspired checks (MD001–MD059)
    ├── documentation-style.md  GitHub documentation style guide distilled
    ├── reading-psychology.md   How humans read: chunking, crowding, visual noise
    ├── document-patterns.md    Structure patterns per document type
    ├── visual-assets.md        Icons, badges, logos, screenshots, theme-aware images
    └── validation.md           The post-edit validation gate

A portable CommonMark document never receives GitHub-only rules; a GitHub README gets the full GFM plus visuals treatment.

Documentation

See it in action

Model documents in skills/better-md-skill/examples/:

• README.md: a model GitHub README
• API.md: a model API reference
• tutorial.md: a model tutorial
• specification.md: a model specification
• changelog.md: a model Keep a Changelog changelog

Test it

tests/ holds a 51-case fixture suite: bad headings, broken lists, bad tables, missing code languages, broken links, poor and good READMEs, all supported document types, GitHub alerts, CommonMark vs GFM awareness, technology icons, badges, screenshots, existing assets, light/dark logos, excessive decoration, invalid external assets, visual suggestions, reading-psychology cases, enhanced README patterns, SVG asset authoring, the calibrated main-README pattern (size-gated navigation, detection-driven badges and tech stack), and existing images kept as-is. See tests/README.md for how to run it.

Contributing

1. Read the test harness docs to understand how behavior is verified.
2. Add or improve a fixture in tests/ for any behavioral change; every capability claim should be covered by a case.
3. Keep reference modules focused and sourced: cite the authoritative standard each rule comes from.
4. Never add fabricated URLs, icons, badges, or assets to examples or fixtures.
5. Run the suite before opening a pull request.

License

MIT. See LICENSE for the full text.