| name | markdown-authoring |
| description | Author high-quality Markdown documentation with deterministic structure, lint compliance, and CI integration. Use when writing README files, creating docs pages, fixing markdownlint failures, defining style rules, or wiring markdown checks into pre-commit and pipelines. Keywords: markdown, markdownlint, readme, docs, headings, lists, code fences, links, images, lint config, ci, documentation style. |
Markdown Authoring
When to Use
Use this skill when the task involves Markdown content, linting, or documentation standards.
When Not to Use
Do not use this skill for non-Markdown document formats (for example .adoc or .rst) unless conversion is part of the task.
Principles
- Structure first, wording second.
- Keep Markdown lint-clean and deterministic.
- Use code fences with explicit language tags.
- Keep file-level conventions consistent across the repository.
Deterministic Workflow
- Identify document type (README, guide, API doc, changelog).
- Apply template and section order from references.
- Write content with concise headings and actionable examples.
- Run markdownlint locally and fix violations. Re-run until zero errors are reported. If a violation persists: identify the specific rule, fix the source content or apply a narrow, justified inline exception, then re-lint. Do not proceed until lint is clean.
- Lint-fix loop:
lint fails → identify rule → fix source or add justified exception → re-lint → proceed only when clean
- Validate CI/pre-commit integration for regression prevention.
Quick Commands
Lint all Markdown files
bunx markdownlint-cli2 "**/*.md"
Expected result: no errors for staged or target files.
Lint one skill folder
bunx markdownlint-cli2 "skills/documentation/markdown-authoring/**/*.md"
Expected result: folder-specific Markdown issues reported or zero errors.
Run repository checks
bunx @biomejs/biome check .
Expected result: non-Markdown formatting/lint issues also caught.
Evaluate this skill quality
sh skills/agentic-harness/skill-quality-auditor/scripts/evaluate.sh documentation/markdown-authoring --json
Expected result: updated dimension scores and grade.
Read a specific reference
./scripts/read-reference.sh syntax-headings
Expected result: displays reference content for the requested topic.
Check document style compliance
bun run check-style "path/to/document.md"
Expected result: style validation report printed to stdout.
Anti-Patterns
NEVER ship Markdown with missing fence language tags
WHY: Untyped code blocks reduce readability and tooling support.
BAD: Use plain triple backticks for code samples.
GOOD: Use typed fences like ```bash or ```ts.
Consequence: Syntax highlighting and lint checks become inconsistent.
NEVER ignore markdownlint violations by disabling broad rules
WHY: Global suppression hides real quality and maintainability issues.
BAD: Turn off multiple rules to make CI green quickly.
GOOD: Fix source content or apply narrow, justified exceptions.
Consequence: Documentation quality degrades release-over-release.
NEVER use heading levels out of sequence
WHY: Skipped heading levels break document hierarchy.
BAD: Jump from ## to #### with no ###.
GOOD: Increase heading levels one step at a time.
Consequence: Navigation and accessibility suffer.
Consider adding a table of contents for documents longer than 300 lines. Optionally include anchor links in headings to improve internal navigation.
NEVER mix inconsistent list and table styles in one document
WHY: Style drift makes docs harder to scan and review.
BAD: Alternate list markers and inconsistent table pipe spacing.
GOOD: Keep one list style and normalized table formatting.
Consequence: Diff noise increases and review confidence drops.
References
