⚠️ Partial UV Script Migration Notice

2 of 5 UV CLI scripts have been consolidated into the builder-skill-uvscript skill on 2025-11-30.

Migrated scripts:

• builder-skill_lint_docs.py (previously lint_korean_docs.py)

• builder-skill_validate_diagrams.py (previously validate_mermaid_diagrams.py)

• Find migrated scripts in: .claude/skills/builder-skill-uvscript/scripts/

Remaining scripts (3 workflow-specific scripts retained in this skill):

• extract_mermaid_details.py

• generate_final_comprehensive_report.py

• validate_korean_typography.py

Usage:

• Migrated: uv run .claude/skills/builder-skill-uvscript/scripts/builder-skill_lint_docs.py

• Retained: uv run .claude/skills/moai-workflow-docs/scripts/extract_mermaid_details.py

Quick Reference (30 seconds)

Purpose: Comprehensive documentation validation framework with 5 specialized phases.

Core Phases:

• Markdown Linting - Syntax, structure, links validation

• Mermaid Diagrams - Diagram syntax and type checking

• Mermaid Details - Code extraction and rendering guide

• Korean Typography - UTF-8, spacing, encoding validation

• Report Generation - Aggregated quality report

Key Benefits:

• Catch errors before publication

• Multi-language support (Korean, English, Japanese, Chinese)

• Diagram syntax validation

• Typography consistency

• Actionable recommendations

Available Scripts: 5 validation and reporting scripts

Usage Pattern:

• Load skill: Skill("moai-workflow-docs")

• Check SKILL.md for "When to use"

• Execute script with --help flag

• Run script with options

• Only read source if --help insufficient

Important: Don't read script source code unless necessary. All scripts are self-documenting via --help flag.

Implementation Guide (5 minutes)

Features

• Unified documentation generation for technical projects

• README, API docs, architecture guides, and deployment docs

• CommonMark compliance with proper formatting standards

• Automated cross-referencing and navigation

• Multi-language documentation support

When to Use

• Generating project documentation from code and specifications

• Creating API reference documentation automatically

• Building architecture decision records (ADRs)

• Producing deployment guides and runbooks

• Synchronizing documentation with code changes

Core Patterns

Pattern 1: Documentation Structure

docs/ ├── README.md (project overview) ├── API.md (API reference) ├── ARCHITECTURE.md (system design) ├── DEPLOYMENT.md (deployment guide) └── CONTRIBUTING.md (contribution guide)

Pattern 2: Auto-generated API Docs

Extract from code comments and type hints

def generate_api_docs(source_files): 1. Parse docstrings and annotations 2. Generate markdown tables for parameters/returns 3. Include code examples from tests 4. Cross-reference related endpoints 5. Validate all links and references

Pattern 3: Documentation Sync

• Detect code changes via git diff

• Identify affected documentation sections

• Update docs automatically or prompt for review

• Validate documentation completeness

• Generate changelog entries

Available Scripts

scripts/lint_korean_docs.py

When to use: Validate Korean markdown documentation before committing Quick start: uv run .claude/skills/moai-workflow-docs/scripts/lint_korean_docs.py --help

Features:

• Validate Korean markdown syntax (UTF-8 encoding)

• Check heading structure (H1-H6 hierarchy)

• Verify code block formatting

• Detect broken internal links

• Check list indentation

• Dual output (human + --json)

Exit codes: 0 (pass), 1 (warnings), 2 (errors), 3 (fatal)

scripts/validate_mermaid_diagrams.py

When to use: Check Mermaid diagram syntax before committing documentation Quick start: uv run .claude/skills/moai-workflow-docs/scripts/validate_mermaid_diagrams.py --help

Features:

• Validate Mermaid diagram types (flowchart, sequence, class, state, ER, gantt, pie)

• Check syntax errors (missing nodes, edges, participants)

• Verify required elements per diagram type

• Detect unclosed diagram blocks

• Dual output (human + --json)

Exit codes: 0 (all valid), 1 (warnings), 2 (invalid diagrams), 3 (fatal)

scripts/validate_korean_typography.py

When to use: Validate Korean typography rules and encoding Quick start: uv run .claude/skills/moai-workflow-docs/scripts/validate_korean_typography.py --help

scripts/extract_mermaid_details.py

When to use: Extract Mermaid diagrams for detailed review Quick start: uv run .claude/skills/moai-workflow-docs/scripts/extract_mermaid_details.py --help

scripts/generate_final_comprehensive_report.py

When to use: Generate aggregated validation report Quick start: uv run .claude/skills/moai-workflow-docs/scripts/generate_final_comprehensive_report.py --help

📚 Core Patterns (5-10 minutes)

Pattern 1: Documentation Validation Pipeline

Key Concept: Run validation scripts in sequence to catch multiple error types

Pipeline Flow:

• Run markdown linting on documentation files

• Validate all Mermaid diagrams for syntax

• Extract Mermaid diagrams for review

• Check Korean typography (if applicable)

• Generate comprehensive report

Basic Execution:

Run complete validation

uv run .claude/skills/moai-workflow-docs/scripts/lint_korean_docs.py --help uv run .claude/skills/moai-workflow-docs/scripts/lint_korean_docs.py --input docs/ uv run .claude/skills/moai-workflow-docs/scripts/lint_korean_docs.py --input docs/ --json

Pattern 2: Markdown Structure Validation

Key Concept: Ensure consistent markdown structure and formatting

Common Validations:

• Headers: H1 unique, proper nesting (H1→H2→H3)

• Code blocks: Language declared, matching delimiters

• Links: Relative paths valid, files exist, HTTPS protocol

• Lists: Consistent markers (-, *, +), proper indentation

• Tables: Column count consistent, alignment markers

Example Issues:

❌ Missing language in code block: ✅ Correct syntax:python

❌ Invalid link: text ✅ Correct syntax: text

❌ Inconsistent list markers: - item1, * item2 ✅ Consistent: - item1, - item2

Pattern 3: Mermaid Diagram Validation

Key Concept: Validate diagram syntax and type compatibility

Supported Types:

• graph TD/BT/LR/RL

• Flowcharts (top-down, bottom-up, left-right, right-left)

• stateDiagram-v2

• State machines

• sequenceDiagram

• Sequence diagrams

• classDiagram

• Class structures

• erDiagram

• Entity relationship diagrams

• gantt

• Gantt charts (timelines)

Validation Checks:

• Diagram type recognized

• Configuration block valid

• Node/edge relationships valid

• Syntax errors detected

• Complexity metrics

Pattern 4: Korean Typography Rules

Key Concept: Maintain Korean language best practices

Validation Rules:

• No full-width ASCII characters (ａ-ｚ should be a-z)

• Proper spacing around parentheses: （한글） vs (한글)

• UTF-8 encoding (no broken characters)

• Consistent punctuation (，vs, 、vs..)

• Proper use of Hangul vs Hanja (한글 vs 한漢字)

Pattern 5: Quality Report Generation

Key Concept: Aggregate validation results with actionable recommendations

Report Contents:

• Summary statistics (files, issues, severity)

• Issue categorization (errors vs warnings)

• Priority ranking (critical, high, medium, low)

• Specific file locations and line numbers

• Recommended fixes

Advanced Documentation

This Skill uses Progressive Disclosure. For detailed implementation:

• modules/validation-scripts.md - Complete script specifications

• modules/execution-guide.md - How to run validations

• modules/troubleshooting.md - Common issues and fixes

• modules/reference.md - API reference and configuration

• modules/scripts-reference.md - Script API reference

• modules/integration-patterns.md - Integration patterns and examples

🔧 Common Use Cases

Use Case 1: CI/CD Integration

Run validation on every commit:

.github/workflows/docs-validation.yml

on: [push, pull_request] jobs: validate-docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Validate documentation run: | uv run .claude/skills/moai-workflow-docs/scripts/lint_korean_docs.py uv run .claude/skills/moai-workflow-docs/scripts/validate_mermaid_diagrams.py

Use Case 2: Pre-Commit Hook

Validate docs before committing:

#!/bin/bash

.git/hooks/pre-commit

uv run .claude/skills/moai-workflow-docs/scripts/lint_korean_docs.py if [ $? -ne 0 ]; then echo "Documentation validation failed" exit 1 fi

Use Case 3: Documentation Review

Generate report for review team:

uv run .claude/skills/moai-workflow-docs/scripts/generate_quality_report.py
--path docs/src
--output .moai/reports/review_report.txt
--format detailed

🔗 Integration with Other Skills

Complementary Skills:

• Skill("moai-docs-generation") - Generate documentation automatically

• Skill("moai-docs-toolkit") - Document manipulation and conversion

• Skill("moai-cc-claude-md") - Markdown formatting standards

Typical Workflow:

• Use moai-docs-generation to create documentation

• Use this Skill (moai-workflow-docs) to validate output

• Use moai-docs-toolkit for additional processing

📈 Version History

1.0.1 (2025-11-23)

• 🔄 Refactored with Progressive Disclosure pattern

• 📚 Scripts moved to modules/ for clarity

• ✨ Core patterns highlighted in SKILL.md

• ✨ Added CI/CD and hook integration examples

1.0.0 (2025-11-12)

• ✨ Markdown linting with 8 validation categories

• ✨ Mermaid diagram validation

• ✨ Korean typography validation

• ✨ Comprehensive quality reporting

Works Well With

Agents:

• workflow-docs - Documentation generation workflow

• core-quality - Quality assurance and validation

• workflow-spec - Specification documentation

Skills:

• moai-docs-generation - Generate documentation automatically

• moai-docs-toolkit - Document manipulation and conversion

• moai-cc-claude-md - Markdown formatting standards

• moai-library-mermaid - Advanced diagram validation

• moai-library-nextra - Nextra-based documentation architecture

Commands:

• /moai:3-sync

• Documentation synchronization

• /moai:9-feedback

• Documentation improvement feedback

Maintained by: alfred Domain: Documentation & Quality Assurance Generated with: MoAI-ADK Skill Factory