Validates and improves Spryker documentation using Vale, Markdownlint, and style guide standards. Ensures Jekyll-compatible Markdown with proper formatting, tone, and internal links.
This skill validates and improves Spryker documentation according to repository standards, ensuring content meets quality requirements for docs.spryker.com.
When the user asks to validate or build documentation:
1. Run git diff to find all changed markdown files compared to master:
```bash
git diff master..HEAD --name-only | grep '.md'
```
2. If no changed files found, check working directory for uncommitted changes:
```bash
git status --porcelain | grep '.md'
```
3. Store the list of changed files for validation
For each changed markdown file:
1. Run Vale (prose linting) with error-level alerts only:
```bash
vale --minAlertLevel=error path/to/file.md
```
2. Run Markdownlint (syntax checking):
```bash
markdownlint-cli2 path/to/file.md
```
3. If tools are not installed, inform the user and provide installation instructions based on their OS
4. Collect all ERROR-level issues only (ignore warnings and suggestions)
Check all internal links in changed files follow this format:
**Required format:**
```markdown
[link text](/docs/section/file.html)
```
**Rules:**
**Example:**
Report any links not following this format as errors.
Analyze content for the following standards:
**Grammar and Sentence Structure:**
**Tone of Voice:**
Ensure tone aligns with technical documentation best practices:
**Writing Style:**
- `{% info_block infoBox "Info" %}...{% endinfo_block %}` instead of `> [!NOTE]`
- `{% info_block warningBox "Warning" %}...{% endinfo_block %}`
- `{% include %}` tags as appropriate
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 changed and why
**Format:**
```
1. **Original:** `This is the old text.`
**New:** `This is the improved text.`
**Summary:** Changed passive voice to active voice for clarity.
```
**ONLY show items that need amendments** - do not list "no change" items.
Provide a clear summary:
**Example 1: User asks to validate documentation**
```
User: "Validate my documentation changes"
Agent:
1. Runs git diff to find changed .md files
2. Runs Vale and Markdownlint on each file
3. Checks internal link formatting
4. Reports only errors with specific fixes
5. Provides numbered list of amendments
```
**Example 2: User asks to build documentation**
```
User: "Build the documentation"
Agent:
1. Finds all changed markdown files
2. Validates each file with Vale and Markdownlint
3. Evaluates against Spryker standards
4. Reports errors and suggested improvements
5. Confirms documentation is ready or lists required fixes
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/spryker-documentation-standards/raw