Imported from MartiXDev/Platform (.agents/skills/martix-markdown/AGENTS.md). Install upstream with npx skills add MartiXDev/Platform --skill martix-markdown. Copyright stays with the author.

MartiX Markdown companion

• This file is the long-form companion to SKILL.md.
• Route tight here too: assess scope first, open the nearest grouped rule, then add only the reference layer the question actually needs.
• The package now follows a layered, standalone-first split: SKILL.md routes activation, AGENTS.md explains how to apply the library, rules\*.md holds the grouped markdownlint guidance, references\*.md provides maps and the instruction-bridge layer, and templates\*.md plus assets\*.json keep the package maintainable.
• Start with the closest grouped rule and add instruction-bridge.md whenever the task compares upstream markdownlint defaults with repo-local Markdown or accessibility overlays.

Package inventory

Working stance

• Assess the boundary before loading deep context. If the request is generic writing help, repo publishing process, or another domain skill's technical guidance, hand off instead of forcing a markdownlint route.
• Keep this package markdownlint-specific. General writing coaching, publishing workflows, or broad documentation style guidance belongs elsewhere unless it changes a markdownlint rule, config choice, or review route.
• Treat the grouped rule files as the primary day-to-day guidance. The bundled reference maps help choose a route quickly, but they do not replace the rule files.
• Keep upstream markdownlint defaults separate from repo-local overlays. Use the instruction bridge when the real question is "what is markdownlint's default" versus "what does this repository additionally expect?"
• Prefer the smallest durable fix: content edit first, repo config second, file-local exception third, and custom rule last.
• Preserve document meaning, structure, link targets, accessibility, and review readability before mechanical cleanup.

Critical markdownlint facts

• Upstream markdownlint defaults and repo-local Markdown instructions are different layers.
• MD041, MD025, and front matter title handling are policy-sensitive, not universal Markdown requirements.
• MD045 and MD059 cover only part of accessibility review. Duplicate link text, filename-like alt text, plain language, and emoji-heavy formatting still need human review.
• Prettier coexistence is usually narrow. Structural rules such as headings, blank-line boundaries, fragments, and alt text stay in content or human review territory.
• Inline suppressions are escape hatches, not baseline policy.

Source boundaries

Read the source index first whenever a new rule, reference, or comparison note might widen beyond the approved boundary.

Common review routes

Reference index

• Source index and guardrails
• Grouped rule family map
• Config and validation map
• Instruction bridge
• Accessibility review map
• Default rule profile
• Install and validation notes
• Prettier and tooling notes

Authoring contract

• Keep every grouped rule aligned with rules/_sections.md.
• Preserve the explicit split between Upstream default and Repo-local overlay.
• Keep SKILL.md compact and routing-oriented. Move durable detail into grouped rules or references instead of rebuilding a monolith.
• Update metadata.json, assets/taxonomy.json, and assets/section-order.json in the same change whenever rule or reference coverage changes.

Research and comparison

• Use the rule template for new grouped rules.
• Use the research pack template when a future expansion needs a source inventory before new guidance lands.
• Use the comparison matrix template for repo-local overlay comparisons, formatter boundary comparisons, or upstream-versus-package audits.
• Keep markdownlint-cli2-config.template.jsonc as the narrow starting point for repo config changes.

Standalone packaging note

• This package is the canonical standalone skill under skills.
• If you document or install it directly, use npx skills add <source>.
• A future direct marketplace registration should point to skills/martix-markdown rather than duplicate the package in another location.