coding-markdown

name

coding-markdown

description

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).

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):

## Steps

1. First item

2. Second item

Good (correct separator, compact, punctuated):

## Steps
1) First item.
    - Nested detail.
2) Second item.

Un-ordered list example Good:

## 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):

| Category | Chimp | Octopus |
|---|---|---|
| Tool use | 50 | 40 |
| Swimming | 40 | 95 |

• Right (linear):

**Tool use**:
- Chimp: 50, Octopus: 40
**Swimming**:
- Chimp: 40, Octopus: 95

• Also right (single-line per item when columns are few):

**Tool use** — Chimp: 50, Octopus: 40
**Swimming** — Chimp: 40, Octopus: 95

Mermaid diagrams: Use only when requested by user.