# Markdown

> Transform AI markdown generation to be 100% markdownlint-compliant. Use this skill whenever generating messages containing markdown, generating or editing markdown files (.md) for technical documentation, README files, guides, tutorials, or any GFM content requiring clean, professional presentation.

- **Type:** Skill
- **Install:** `agentstack add skill-redondok-claude-md-skill-markdown`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RedondoK](https://agentstack.voostack.com/s/redondok)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [RedondoK](https://github.com/RedondoK)
- **Source:** https://github.com/RedondoK/claude-md-skill/tree/main/markdown

## Install

```sh
agentstack add skill-redondok-claude-md-skill-markdown
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# GitHub Flavored Markdown Generation

**Version:** 1.2.1

Generate GFM that passes markdownlint validation with zero violations.

## Core Principles

### 1. Blank Lines Are Mandatory

- Before/after ALL lists (MD032)
- Before/after ALL headings except document start (MD022)
- Before/after ALL code blocks (MD031)
- Between ALL block-level elements

### 2. Consistency Required

- Use `-` for lists
- Use `#` for headings (ATX)
- Regular spaces only—never tabs/nbsp

### 3. Structure Matters

- Heading hierarchy: 1→2→3 (not 1→3)
- ONE H1 per document
- Files end with one newline
- Lines under 80 chars

### 4. Invisible Characters Matter

- Use ONLY regular spaces (U+0020)
- Never non-breaking spaces (U+00A0,  )
- Never tabs
- UTF-8 encoding

## Pre-Generation Checklist

- [ ] Where will lists/headings/code appear?
- [ ] Heading levels verified (1→2→3)?
- [ ] Using `-` for all lists?
- [ ] Code languages specified?
- [ ] Lines under 80 chars?
- [ ] Line breaks needed? (two trailing spaces)
- [ ] Using regular spaces only?
- [ ] URLs wrapped in `<>` or `[]`?
- [ ] Document starts with H1?
- [ ] Ordered lists use `1.` for all items?
- [ ] File ends with single newline?
- [ ] Tables use consistent spacing?

## Essential Rules

### Lists (MD032, MD004)

```markdown
Text before.

- Item one
- Item two

Text after.
```

### Headings (MD001, MD022)

```markdown
Text.

## Heading

Content.
```

### Code Blocks (MD031, MD040)

````markdown
Text.

```python
code()
```

Text.
````

**Nested Fences:** When showing markdown examples that contain code blocks,
use **one more backtick** than the deepest level:

- Three backticks (` ``` `): Regular code
- Four backticks (` ```` `): Markdown examples with code
- Five backticks (` ````` `): Nested markdown examples

`````markdown
````markdown
# Example

```bash
command
```

````
`````

### Line Length (MD013)

Break long lines at natural points. Use reference-style links for long URLs.

### URLs and Email (MD034)

Wrap bare URLs and emails:

```markdown
Wrong: https://example.com
Right: 
Right: [link](https://example.com)

Wrong: user@example.com
Right: 
```

### Document Structure (MD041)

Start with H1 (or front matter then H1):

```markdown
# Document Title

First paragraph.
```

### Ordered Lists (MD029)

Use `1.` for all items:

```markdown
1. First
1. Second
1. Third
```

### File Endings (MD047)

End with single newline:

```text
Last content line.
[single newline]
[EOF]
```

### Table Column Style (MD060)

Use consistent spacing in tables. Three styles:

**Compact (recommended):** `| cell |` - single space around content

```markdown
| Header 1 | Header 2 |
| --- | --- |
| Data | More data |
```

**Aligned:** Pipes vertically aligned with padding

**Tight:** `|cell|` - no spaces

Pick ONE style per document. Compact is preferred.

### Character Encoding

**Detection:** View → Render Whitespace in VS Code

**Fix:** Find `\u00A0` → Replace with space

**Critical for AI:** Two trailing spaces = intentional line breaks. Do NOT
remove them.

## Critical Error Patterns

### 1. List Without Blank Lines

**Wrong:**

```markdown
Text:
- Item
Text.
```

**Right:**

```markdown
Text:

- Item

Text.
```

### 2. Heading Without Blank Lines

**Wrong:**

```markdown
Text.
## Head
Text.
```

**Right:**

```markdown
Text.

## Head

Text.
```

### 3. Code Without Blanks/Language

**Wrong:**

````markdown
Text:
```
code
```
Text.
````

**Right:**

````markdown
Text:

```python
code
```

Text.
````

### 4. Inconsistent Markers

**Wrong:**

```markdown
- Item
* Item
```

**Right:**

```markdown
- Item
- Item
```

### 5. Skipping Levels

**Wrong:**

```markdown
# Title

### Sub (skipped H2)
```

**Right:**

```markdown
# Title

## Section

### Sub
```

## Post-Generation Validation

1. Lists have blank lines before/after
2. Headings have blank lines before/after
3. Code has blank lines before/after
4. Heading progression: 1→2→3→4
5. All lists use `-`
6. All code has language
7. Lines under 80 chars
8. Document starts with H1
9. URLs wrapped properly
10. Ordered lists use `1.`
11. File ends with one newline
12. Two trailing spaces used intentionally
13. Only regular spaces (no nbsp/tabs)
14. Tables use consistent column spacing

## Mental Model

Markdown is **blocks with mandatory spacing:**

```text
[Text Block]
↓ BLANK LINE ↓
[Heading Block]
↓ BLANK LINE ↓
[List Block]
↓ BLANK LINE ↓
[Code Block]
↓ BLANK LINE ↓
[Text Block]
[EOF]
```

Every block transition = blank line required.

## Quick Patterns

**List:**

```markdown
text

- item

text
```

**Heading:**

```markdown
text

## Head

text
```

**Code:**

````markdown
text

```lang
code
```

text
````

**Nested:**

```markdown
- parent
  - child
- parent
```

**Ordered:**

```markdown
text

1. item
1. item

text
```

**Table:**

```markdown
text

| Header | Header |
| --- | --- |
| Cell | Cell |

text
```

## Common Languages

**Programming:** `python` `javascript` `java` `c` `cpp` `go` `rust` `ruby`
`php` `swift` `kotlin` `typescript`

**Shell:** `bash` `sh` `powershell` `cmd` `zsh`

**Markup:** `html` `css` `xml` `json` `yaml` `toml` `markdown`

**Database:** `sql` `postgresql` `mysql`

**Other:** `text` `diff` `log`

## Validation

```bash
markdownlint filename.md
```

Goal: Zero errors/warnings.

## Additional Resources

See bundled references:

- `references/complete-rules.md` - Full rule catalog
- `references/edge-cases.md` - Platform quirks
- `references/examples.md` - Detailed examples

## Remember

Most common: Missing blank lines around lists/headings/code.

**Two trailing spaces:** Intentional line breaks. Do NOT remove.

When in doubt:

1. Add blank lines before/after blocks
2. Use `-` for lists
3. Use `#` for headings
4. Specify code language
5. Increment headings by one
6. Use regular spaces only
7. Two trailing spaces = line break

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [RedondoK](https://github.com/RedondoK)
- **Source:** [RedondoK/claude-md-skill](https://github.com/RedondoK/claude-md-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-redondok-claude-md-skill-markdown
- Seller: https://agentstack.voostack.com/s/redondok
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.