markdown-plugin

A single coding-agent skill that enforces rendering-compatibility rules for markdown output — GFM conformance plus emacs markdown-mode quirks (source-aligned tables, no escaped pipes, separator-row alignment markers, code-fence language tags).

The skill triggers on any Write/Edit of a .md/.markdown file and on any markdown tables or code blocks the agent emits in chat.

Status: small and stable. The rule set is hardened against the specific edge cases that broke renderings in real use; new rules get added as they surface. PRs and issues welcome.

Why this exists

Coding agents emit markdown that "looks fine" in GitHub's renderer but breaks in stricter ones — emacs markdown-mode, mdBook, several VS Code preview engines. The most painful classes of breakage:

• Escaped pipes (\|) inside table cells — invisible in some renderers, columns silently misalign in others.
• Tables not byte-aligned in the source — render fine on GitHub, completely wrong in any tool that aligns by source position rather than display width.
• Code fences without a language tag — render as a plain block instead of getting syntax highlighting; some renderers won't even apply background styling.
• Separator rows missing alignment markers — the :---: / :--- / ---: triplet that controls column alignment.

The skill description includes MUST so the agent harness surfaces it as a precondition, not a suggestion.

Layout

markdown-plugin/
├── README.md
├── LICENSE
├── install.sh
└── plugins/
    ├── claude-code/
    │   └── .claude-plugin/
    │       └── plugin.json          Claude Code plugin manifest
    └── skills/
        └── markdown/
            └── SKILL.md             The actual rules (~200 lines)

The skill is a single file — plugins/skills/markdown/SKILL.md. Edit it there, then re-run bash install.sh to push the change to every agent.

Install

git clone https://github.com/MrVampy/markdown-plugin.git
cd markdown-plugin
bash install.sh

Installs into whichever of the three agents the script finds on your machine:

Agent	Install path
Claude Code	~/.claude/plugins/markdown/skills/markdown/
Codex	~/.codex/skills/markdown/
OpenCode	~/.config/opencode/skills/markdown/

Safe to re-run — each install path is wiped and rewritten, so the script is the canonical sync mechanism after edits.

Why a plugin and not just a file

Keeping the skill in a standalone git-tracked project means:

• One source of truth. Edit in one place, deploy to all three agents.
• Version control. Diff rule changes; revert if a rule regresses or starts producing false positives.
• Portable. Copy the directory to a new machine and bash install.sh wires it into every agent at once.
• Composable. Sits alongside other skill plugins (e.g. memory-plugin) without conflict — each owns its own subdirectory under each agent's skills root.

Related

• memory-plugin — same plugin pattern, different feature: a typed wiki shared across the three agents.

License

MIT. See LICENSE.