Spryker Documentation Validation & Style Guide

This skill validates and improves Spryker documentation (https://docs.spryker.com) by enforcing vale prose linting, markdownlint syntax rules, and Spryker-specific documentation standards.

Instructions

When the user requests documentation validation, build, or style improvements, follow these steps:

1. Find Changed Files

Identify all modified markdown files compared to master:

```bash

git diff master..HEAD --name-only | grep '.md'

```

2. Run Validation Tools

For each changed file, run both linters:

**Vale (prose linting):**

```bash

vale --minAlertLevel=error path/to/file.md

```

**Markdownlint (markdown syntax):**

```bash

markdownlint-cli2 path/to/file.md

```

If tools are not installed, prompt the user to install them per OS requirements.

3. Report Errors Only

```

1. **Original:** `[original markdown code]`

**New:** `[corrected markdown code]`

**Summary:** [brief explanation of change]

```

4. Validate Internal Links

All relative internal links MUST follow this format:

```markdown

[link text](/docs/section/file.html)

```

**Rules:**

**Example:**

5. Apply Documentation Standards

Evaluate and improve content following these standards:

#### Grammar and Sentence Structure

#### Tone of Voice

Align with technical documentation best practices (Google Developer Documentation Style Guide, Microsoft Style Guide). Tone should be:

**Required tone elements:**

#### Writing Style & Markdown

**Spelling:**

**Markdown Formatting:**

- `{% info_block infoBox "Info" %}...{% endinfo_block %}` instead of `> [!NOTE]`

- `{% include %}`

- `{% info_block warningBox "Warning" %}`

6. Present All Suggestions

ONLY show amendments—do not list "no change" items.

Format each suggestion as:

```

1. **Original:** `[current code]`

**New:** `[improved code]`

**Summary:** [what changed and why]

```

Limitations

Example Workflow

User: "Validate my documentation changes"

1. Run `git diff master..HEAD --name-only | grep '.md'` to find changed files

2. Run `vale --minAlertLevel=error` on each file

3. Run `markdownlint-cli2` on each file

4. Check internal link format

5. Apply Documentation Standards review

6. Present numbered list of specific fixes with original, new, and summary