Spryker Documentation Validator

This skill validates Spryker documentation markdown files against style guidelines and linting tools, ensuring high-quality, consistent content for docs.spryker.com.

What This Skill Does

When to Use This Skill

Use this when:

Instructions

Step 1: Find Changed Markdown Files

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

```bash

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

```

If no files are found, inform the user that no markdown files have changed.

Step 2: Run Validation Tools

For each changed markdown file, run both validation tools:

**Vale (prose linting - errors only):**

```bash

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

```

**Markdownlint (markdown syntax):**

```bash

markdownlint-cli2 path/to/file.md

```

**Important:** If tools are not installed, instruct the user to install them according to their OS requirements.

Step 3: Report Errors Only

Step 4: Validate Internal Links

Check that all relative internal links follow this format:

```markdown

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

```

**Rules:**

**Fix any incorrect links found.**

Step 5: Evaluate Against Documentation Standards

Review content for:

**Grammar and Sentence Structure:**

**Tone of Voice (per Google/Microsoft style guides):**

**Writing Style and Markdown:**

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

Step 6: Present Amendments

Present **ONLY amendments** (no "no change" items) in numbered list format:

```

1. **Original:** `Old markdown code`

**New:** `Improved markdown code`

**Summary:** Brief explanation of change and reason

```

**Example:**

```

1. **Original:** `The system will process the request.`

**New:** `The system processes the request.`

**Summary:** Changed future tense to present tense for immediacy.

```

Constraints

Example Usage

**User:** "Build the documentation"

**Agent:**

1. Finds changed markdown files

2. Runs Vale and Markdownlint on each

3. Reports errors with specific fixes

4. Validates internal link format

5. Evaluates against documentation standards

6. Presents numbered list of amendments only