# Coding Markdown

> When markdown being written or edited, including rules, skills, and documentation. Trigger any time a .md file is being created or modified, a skill's SKILL.md is being updated, rules files under .kilocode/rules*/ are being edited, or a user says "update the docs", "fix the readme", "edit this skill", "write documentation", or "format this markdown". Load with read_file on .kilocode/skills/coding-markdown/SKILL.md (ignore the absolute path in the location tag).

- Skill: `scottermonk/coding-markdown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add scottermonk/coding-markdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scottermonk/coding-markdown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ScotterMonk (https://skillmd.com/u/scottermonk)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/scottermonk/coding-markdown

---


# Markdown Instructions

These rules apply to **all markdown the AI writes** — project files (README, rules, skills, docs), plans, and inline markdown in responses.

## File Path References
Strictly enforce minimalist path references to reduce noise:
- **Follow platform link requirements first**: If the active harness requires clickable file references or line numbers, that requirement overrides this section.
- **Default for markdown files**: When no platform requirement says otherwise, use plain backticks instead of `[name](path)` syntax.
- **Line numbers**: Include line numbers only when the active harness or planning workflow requires them.
- **No redundancy**: Do not repeat the filename in both brackets and parentheses.
- **Contextual pointers**: Reference section names instead of line numbers.

**Exceptions**: Planner modes (`architect`, `planner-a`, `planner-b`, `planner-c`) may use links when creating or modifying a plan; any harness-level clickable-link rule also overrides the default plain-backtick preference.

Examples:
- Bad: `[app/models/user.py](app/models/user.py)` → Good: `` `app/models/user.py` ``
- Bad: `[user.py](app/models/user.py:50)` → Good: `` `app/models/user.py` ``
- Bad: `See \`rules/01-general.md\`` → Good: `See 'Critical Resources' in \`rules/01-general.md\``

## Formatting Standards

**Style & Typography**
- *Files/code*: Prefer inline backticks (`file.py`) unless the active harness requires clickable file links.
- *Indentation*: Use exactly 4 spaces for nested items.

**Lists & Spacing**
- *Numbering*: Use `)` as separator (e.g., `1)`, `2)`). Never use periods (`1.`).
- *Density*: No empty lines between list items. Group related items tightly.
- *Headers*: Start content on the very next line after a header — no blank line between them.
- *Punctuation*: Period at the end of every list item line.
- *Sections*: Single empty line between major sections only.

**Ordered list example**
*Bad* (wrong separator, extra spacing, missing punctuation):
```markdown
## Steps

1. First item

2. Second item
```
*Good* (correct separator, compact, punctuated):
```markdown
## Steps
1) First item.
    - Nested detail.
2) Second item.
```

**Un-ordered list example**
*Good*:
```markdown
## Points
- First item.
    - Nested detail.
- Second item.
```

**Tables**: Do NOT use markdown tables (`| col | col |` syntax). They are hard for humans to scan and expensive for LLMs to parse (pipe alignment, separator rows, cross-referencing headers). Use **linear format** instead — bold labels with dashes and indentation.

This applies everywhere: markdown files, skill definitions, plans, and inline markdown in responses.

- *Wrong* (table):
```md
| Category | Chimp | Octopus |
|---|---|---|
| Tool use | 50 | 40 |
| Swimming | 40 | 95 |
```

- *Right* (linear):
```md
**Tool use**:
- Chimp: 50, Octopus: 40
**Swimming**:
- Chimp: 40, Octopus: 95
```

- *Also right* (single-line per item when columns are few):
```md
**Tool use** — Chimp: 50, Octopus: 40
**Swimming** — Chimp: 40, Octopus: 95
```

**Mermaid diagrams**: Use only when requested by user.