Spryker Documentation Validator

Validates and improves Spryker documentation markdown files for docs.spryker.com, ensuring compliance with Vale prose linting, Markdownlint syntax checking, and Spryker documentation standards.

What This Skill Does

This skill helps maintain high-quality Spryker documentation by:

Instructions

Step 1: Find Changed Files

When the user asks to validate or build documentation, first identify all changed markdown files compared to master:

```bash

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

```

Step 2: Run Validation Tools

For each changed markdown file, run both validation tools:

**Vale (prose linting):**

```bash

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

```

**Markdownlint (markdown syntax):**

```bash

markdownlint-cli2 path/to/file.md

```

**Important:** If vale or markdownlint-cli2 are not installed, inform the user and provide installation instructions for their OS.

Step 3: Address ONLY Errors

Step 4: Validate Internal Links

All relative internal links MUST follow this format:

```markdown

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

```

**Rules:**

**Example:**

Step 5: Apply Documentation Standards

Evaluate content for:

**Grammar and Sentence Structure:**

**Tone of Voice (align with Google/Microsoft technical documentation styles):**

**Markdown and Markup:**

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

- Apply other Liquid tags: `{% include %}`, `{% info_block warningBox "Warning" %}`

Step 6: Present Suggestions

Present all suggestions in a numbered list with this format:

```

1. **Original:** `This is the old text.`

**New:** `This is the improved text.`

**Summary:** Changed passive voice to active voice for clarity.

```

**Each item must include:**

1. Original markdown code

2. New markdown code

3. Summary of the change and why

**ONLY show amendments - do not show "no change" items**

Constraints

Example Usage

**User:** "Validate my documentation changes"

**AI Response:**

1. Runs git diff to find changed .md files

2. Executes vale and markdownlint-cli2 on each file

3. Reports only errors with specific line numbers

4. Checks internal link formats

5. Provides numbered list of amendments with original/new/summary format

6. Confirms all errors have been addressed