Spryker Documentation Helper

This skill helps you work with the Spryker documentation repository (https://docs.spryker.com) by automating validation, enforcing style standards, and improving documentation quality.

Purpose

Validate markdown documentation with Vale (prose linting) and markdownlint (syntax checking)

Enforce Spryker documentation standards aligned with Google Developer Documentation Style Guide and Microsoft Style Guide

Fix internal link formatting to match Jekyll requirements

Provide specific, actionable amendments to improve article quality

Automate the full validation workflow for changed files

Validation Workflow

When asked to validate, build, or review documentation changes, follow this sequence:

Step 1: Find Changed Files

Run this command to identify all modified markdown files compared to master:

```bash

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

```

Step 2: Run Validation Tools

For each changed 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

```

If vale or markdownlint-cli2 are not installed, prompt the user to install them according to OS requirements.

Step 3: Report and Fix Errors

**ONLY address ERRORS**, not warnings or suggestions

Provide specific fixes for each error found

Present fixes in the required format (see Presenting Suggestions below)

Step 4: Validate Internal Links

Check that all relative internal links follow this format:

```markdown

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

```

**Rules:**

Path must start with `/`

Path must end with `.html` (NOT `.md`)

Use the actual file path, replacing `.md` extension with `.html`

**Example:**

File: `docs/dg/dev/integrate-and-configure/integrate-development-tools/integrate-web-profiler.md`

Link: `[Web Profiler Integration](/docs/dg/dev/integrate-and-configure/integrate-development-tools/integrate-web-profiler.html)`

Fix any links that do not match this pattern.

Step 5: Apply Documentation Standards

Review the content for adherence to Spryker documentation standards:

#### Tone of Voice

Ensure the tone is:

Formal yet helpful

Encouraging

Clear and concise

Consistent

Warm, relaxed, and ready to lend a hand

**Required tone elements:**

Use second person ('you') to address the reader directly

Use active voice for clarity

Use present tense where appropriate

Avoid contractions (use 'do not' instead of 'don't')

Use appropriate technical terms, avoiding unnecessary jargon

#### Grammar and Sentence Structure

Check for:

Typos

Incorrect verb tense

Subject-verb agreement issues

Incorrect punctuation

Overly long, complex, or unclear sentences

Suggest improved sentence structures for better readability.

#### Writing Style and Markup

**Spelling:**

Use American spelling consistently

**Markdown Formatting:**

Verify proper use of headings, lists, links, code blocks, and inline formatting

Use Jekyll-compatible syntax for Spryker-specific components:

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

Apply other Spryker Liquid tags as needed:

- `{% include %}`

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

Ensure output renders correctly in Jekyll but remains readable in raw Markdown

Verify proper alt text for images

Check that heading levels are not skipped (no jump from h2 to h4)

Presenting Suggestions

Present all suggestions in a numbered list. Each item MUST include:

1. **Original markdown code** - The current text/code

2. **New markdown code** - The improved version

3. **Summary of the change** - Brief explanation of what was changed and why

**ONLY show amendments - do not list items with no changes.**

**Example format:**

```

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

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

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

```

Important Constraints

Do NOT suggest removing any part of the document unless it violates a documented rule in the style guides or validation tools

If removal seems beneficial but is not required by the rules, note it as an optional consideration rather than a recommendation

Focus ONLY on errors, not warnings or suggestions from linting tools

Example Usage

**User:** "Build the docs"

**Assistant actions:**

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

2. For each file, run vale and markdownlint-cli2

3. Report all errors with specific fixes

4. Check internal link formatting

5. Review against documentation standards

6. Present all amendments in the required format

**User:** "Validate the integration guide"

**Assistant actions:**

1. Identify the integration guide file

2. Run vale and markdownlint-cli2 on it

3. Check internal links

4. Review tone, grammar, and style

5. Present numbered list of specific amendments

Spryker Documentation Helper

Spryker Documentation Helper

Purpose

Validation Workflow

Step 1: Find Changed Files

Step 2: Run Validation Tools

Step 3: Report and Fix Errors

Step 4: Validate Internal Links

Step 5: Apply Documentation Standards

Presenting Suggestions

Important Constraints

Example Usage

Reviews (0)