moai-docs-unified

Docs Unified

Primary Agent: doc-syncer
Secondary Agents: alfred
Version: 4.0.0
Keywords: docs, unified, cd, ci, test

📖 Progressive Disclosure

Level 1: Quick Reference (Core Concepts)

📚 Content

Section 1: Unified Framework Overview

The moai-docs-unified skill provides a complete documentation management ecosystem integrating 5 specialized validation scripts:

Core Components:

Phase 1: Markdown Linting (syntax, structure, links)
Phase 2: Mermaid Diagram Validation (syntax, rendering, type checking)
Phase 2.5: Mermaid Detail Extraction (code preview, rendering guide)
Phase 3: Korean Typography Validation (UTF-8, full-width chars, spacing)
Phase 4: Comprehensive Report Generation (aggregation, prioritization, recommendations)

Key Benefits:

Catch documentation errors before publication
Ensure consistency across 4 languages (ko, en, ja, zh)
Validate diagram syntax and rendering capability
Maintain Korean language best practices
Generate actionable quality reports

Section 2: Script Specifications

Script 1: lintkoreandocs.py

Purpose: Comprehensive markdown validation for Korean documentation

Location: .claude/skills/moai-docs-unified/scripts/lintkoreandocs.py

Key Validations:

Header structure (H1 uniqueness, level hierarchy)
Code blocks (language declaration, matching delimiters)
Links (relative paths, file existence, https protocol)
Lists (marker consistency, indentation)
Tables (column count, alignment)
Korean-specific (full-width chars, encoding)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py \
  --path docs/src/ko \
  --output .moai/reports/lint_report_ko.txt

Output: .moai/reports/lintreportko.txt (8 validation categories)

Script 2: validatemermaiddiagrams.py

Purpose: Mermaid diagram type and syntax validation

Location: .claude/skills/moai-docs-unified/scripts/validatemermaiddiagrams.py

Key Features:

Diagram type detection (graph, flowchart, stateDiagram, sequenceDiagram, classDiagram, erDiagram, gantt)
Configuration block handling (%%{init: ...}%%)
Node/edge relationship validation
Line count and complexity metrics

Supported Diagram Types:

✅ graph TD/BT/LR/RL          (Flowchart)
✅ stateDiagram-v2            (State machines)
✅ sequenceDiagram            (Interactions)
✅ classDiagram               (Class structures)
✅ erDiagram                  (Entity relationships)
✅ gantt                       (Timelines)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py \
  --path docs/src \
  --output .moai/reports/mermaid_validation_report.txt

Output: .moai/reports/mermaidvalidationreport.txt (16 diagrams, 100% valid)

Script 3: extractmermaiddetails.py

Purpose: Extract and document all Mermaid diagram code with rendering guide

Location: .claude/skills/moai-docs-unified/scripts/extractmermaiddetails.py

Key Features:

Extract all mermaid blocks from documentation
Show diagram type and line count
Provide full code preview
Generate rendering test guide (mermaid.live)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py \
  --path docs/src \
  --output .moai/reports/mermaid_detail_report.txt

Output: .moai/reports/mermaiddetailreport.txt (full diagram code + test guide)

Script 4: validatekoreantypography.py

Purpose: Korean-specific typography and encoding validation

Location: .claude/skills/moai-docs-unified/scripts/validatekoreantypography.py

Key Validations:

UTF-8 Encoding verification
Full-width character detection (U+3000, ＜, ＞, etc.)
Punctuation consistency (. vs。, , vs、)
Spacing rules (Korean-English boundaries)
Character statistics per file

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py \
  --path docs/src \
  --output .moai/reports/korean_typography_report.txt

Output: .moai/reports/koreantypographyreport.txt (28,543 lines validated, 43 files)

Script 5: generatefinalcomprehensive_report.py

Purpose: Aggregate all validation phases into prioritized quality report

Location: .claude/skills/moai-docs-unified/scripts/generatefinalcomprehensive_report.py

Report Structure:

Executive Summary (8.5/10 quality score)
Phase Results (Priority 1/2/3 items)
Recommendations (Done/In Progress/TODO)
Action Items (Immediate/Short-term/Long-term)
Generated Report Files (all 4 phases)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

# With custom report directory
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py \
  --report-dir .moai/reports \
  --output .moai/reports/korean_docs_comprehensive_review.txt

Output: .moai/reports/koreandocscomprehensive_review.txt (aggregated report)

Section 3: Integration Patterns

Single Script Execution

# Phase 1: Markdown linting
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

# Phase 2: Mermaid validation
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

# Phase 2.5: Mermaid code extraction
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py

# Phase 3: Korean typography
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

# Phase 4: Comprehensive report
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

Complete Validation Pipeline

#!/bin/bash
# Run all 5 phases sequentially

echo "Running Phase 1: Markdown Linting..."
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

echo "Running Phase 2: Mermaid Validation..."
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

echo "Running Phase 2.5: Mermaid Detail Extraction..."
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py

echo "Running Phase 3: Korean Typography..."
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

echo "Running Phase 4: Comprehensive Report..."
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

echo "All validation phases complete!"
echo "Check .moai/reports/ for generated files:"
ls -lh .moai/reports/*.txt

Section 4: Project Root Auto-Detection

All scripts use automatic project root detection:

def find_project_root(start_path: Path) -> Path:
    current = start_path
    while current != current.parent:
        if (current / "pyproject.toml").exists() or (current / ".git").exists():
            return current
        current = current.parent
    raise RuntimeError("Project root not found")

script_path = Path(__file__).resolve()
project_root = find_project_root(script_path.parent)

Benefits:

Works from any directory
Works from any execution context (local, CI/CD, automation)
No hardcoded paths
Handles relative paths correctly
Compatible with uv run

Section 5: CI/CD Integration

GitHub Actions Integration:

# .github/workflows/docs-validation.yml
name: Documentation Validation

on:
  pull_request:
    paths:
      - 'docs/**'
  push:
    branches:
      - develop
      - main

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install uv
        run: pip install uv

      - name: Run Documentation Validation Suite
        run: |
          # Phase 1: Markdown Linting
          uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

          # Phase 2: Mermaid Validation
          uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

          # Phase 3: Korean Typography
          uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

          # Phase 4: Comprehensive Report
          uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

      - name: Upload Reports
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: documentation-reports
          path: .moai/reports/*.txt

      - name: Comment PR with Results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('.moai/reports/korean_docs_comprehensive_review.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '📊 Documentation Validation Report\n```\n' + report.slice(0, 3000) + '\n```'
            });

Section 6: Quality Metrics

Phase 1 - Markdown Linting:

53 files scanned
8 validation categories
351 false-positive links (relative paths)
Quality indicator: Syntax errors detected

Phase 2 - Mermaid Validation:

16 diagrams across 9 files
100% valid diagram syntax
3 diagram types (graph, state, sequence)
Renderability verified at mermaid.live

Phase 3 - Korean Typography:

28,543 lines validated
43 Korean content files
100% UTF-8 encoding
Full-width character minimization

Phase 4 - Comprehensive Report:

Overall Quality Score: 8.5/10
Priority 1 (Critical): 0 items
Priority 2 (High): 2 items
Priority 3 (Low): 1 item

Level 2: Practical Implementation (Common Patterns)

📚 Content

Section 1: Unified Framework Overview

The moai-docs-unified skill provides a complete documentation management ecosystem integrating 5 specialized validation scripts:

Core Components:

Phase 1: Markdown Linting (syntax, structure, links)
Phase 2: Mermaid Diagram Validation (syntax, rendering, type checking)
Phase 2.5: Mermaid Detail Extraction (code preview, rendering guide)
Phase 3: Korean Typography Validation (UTF-8, full-width chars, spacing)
Phase 4: Comprehensive Report Generation (aggregation, prioritization, recommendations)

Key Benefits:

Catch documentation errors before publication
Ensure consistency across 4 languages (ko, en, ja, zh)
Validate diagram syntax and rendering capability
Maintain Korean language best practices
Generate actionable quality reports

Section 2: Script Specifications

Script 1: lintkoreandocs.py

Purpose: Comprehensive markdown validation for Korean documentation

Location: .claude/skills/moai-docs-unified/scripts/lintkoreandocs.py

Key Validations:

Header structure (H1 uniqueness, level hierarchy)
Code blocks (language declaration, matching delimiters)
Links (relative paths, file existence, https protocol)
Lists (marker consistency, indentation)
Tables (column count, alignment)
Korean-specific (full-width chars, encoding)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py \
  --path docs/src/ko \
  --output .moai/reports/lint_report_ko.txt

Output: .moai/reports/lintreportko.txt (8 validation categories)

Script 2: validatemermaiddiagrams.py

Purpose: Mermaid diagram type and syntax validation

Location: .claude/skills/moai-docs-unified/scripts/validatemermaiddiagrams.py

Key Features:

Diagram type detection (graph, flowchart, stateDiagram, sequenceDiagram, classDiagram, erDiagram, gantt)
Configuration block handling (%%{init: ...}%%)
Node/edge relationship validation
Line count and complexity metrics

Supported Diagram Types:

✅ graph TD/BT/LR/RL          (Flowchart)
✅ stateDiagram-v2            (State machines)
✅ sequenceDiagram            (Interactions)
✅ classDiagram               (Class structures)
✅ erDiagram                  (Entity relationships)
✅ gantt                       (Timelines)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py \
  --path docs/src \
  --output .moai/reports/mermaid_validation_report.txt

Output: .moai/reports/mermaidvalidationreport.txt (16 diagrams, 100% valid)

Script 3: extractmermaiddetails.py

Purpose: Extract and document all Mermaid diagram code with rendering guide

Location: .claude/skills/moai-docs-unified/scripts/extractmermaiddetails.py

Key Features:

Extract all mermaid blocks from documentation
Show diagram type and line count
Provide full code preview
Generate rendering test guide (mermaid.live)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py \
  --path docs/src \
  --output .moai/reports/mermaid_detail_report.txt

Output: .moai/reports/mermaiddetailreport.txt (full diagram code + test guide)

Script 4: validatekoreantypography.py

Purpose: Korean-specific typography and encoding validation

Location: .claude/skills/moai-docs-unified/scripts/validatekoreantypography.py

Key Validations:

UTF-8 Encoding verification
Full-width character detection (U+3000, ＜, ＞, etc.)
Punctuation consistency (. vs。, , vs、)
Spacing rules (Korean-English boundaries)
Character statistics per file

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

# With custom paths
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py \
  --path docs/src \
  --output .moai/reports/korean_typography_report.txt

Output: .moai/reports/koreantypographyreport.txt (28,543 lines validated, 43 files)

Script 5: generatefinalcomprehensive_report.py

Purpose: Aggregate all validation phases into prioritized quality report

Location: .claude/skills/moai-docs-unified/scripts/generatefinalcomprehensive_report.py

Report Structure:

Executive Summary (8.5/10 quality score)
Phase Results (Priority 1/2/3 items)
Recommendations (Done/In Progress/TODO)
Action Items (Immediate/Short-term/Long-term)
Generated Report Files (all 4 phases)

Execution:

# From project root
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

# With custom report directory
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py \
  --report-dir .moai/reports \
  --output .moai/reports/korean_docs_comprehensive_review.txt

Output: .moai/reports/koreandocscomprehensive_review.txt (aggregated report)

Section 3: Integration Patterns

Single Script Execution

# Phase 1: Markdown linting
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

# Phase 2: Mermaid validation
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

# Phase 2.5: Mermaid code extraction
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py

# Phase 3: Korean typography
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

# Phase 4: Comprehensive report
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

Complete Validation Pipeline

#!/bin/bash
# Run all 5 phases sequentially

echo "Running Phase 1: Markdown Linting..."
uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

echo "Running Phase 2: Mermaid Validation..."
uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

echo "Running Phase 2.5: Mermaid Detail Extraction..."
uv run .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.py

echo "Running Phase 3: Korean Typography..."
uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

echo "Running Phase 4: Comprehensive Report..."
uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

echo "All validation phases complete!"
echo "Check .moai/reports/ for generated files:"
ls -lh .moai/reports/*.txt

Section 4: Project Root Auto-Detection

All scripts use automatic project root detection:

def find_project_root(start_path: Path) -> Path:
    current = start_path
    while current != current.parent:
        if (current / "pyproject.toml").exists() or (current / ".git").exists():
            return current
        current = current.parent
    raise RuntimeError("Project root not found")

script_path = Path(__file__).resolve()
project_root = find_project_root(script_path.parent)

Benefits:

Works from any directory
Works from any execution context (local, CI/CD, automation)
No hardcoded paths
Handles relative paths correctly
Compatible with uv run

Section 5: CI/CD Integration

GitHub Actions Integration:

# .github/workflows/docs-validation.yml
name: Documentation Validation

on:
  pull_request:
    paths:
      - 'docs/**'
  push:
    branches:
      - develop
      - main

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install uv
        run: pip install uv

      - name: Run Documentation Validation Suite
        run: |
          # Phase 1: Markdown Linting
          uv run .claude/skills/moai-docs-unified/scripts/lint_korean_docs.py

          # Phase 2: Mermaid Validation
          uv run .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.py

          # Phase 3: Korean Typography
          uv run .claude/skills/moai-docs-unified/scripts/validate_korean_typography.py

          # Phase 4: Comprehensive Report
          uv run .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_report.py

      - name: Upload Reports
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: documentation-reports
          path: .moai/reports/*.txt

      - name: Comment PR with Results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('.moai/reports/korean_docs_comprehensive_review.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '📊 Documentation Validation Report\n```\n' + report.slice(0, 3000) + '\n```'
            });

Section 6: Quality Metrics

Phase 1 - Markdown Linting:

53 files scanned
8 validation categories
351 false-positive links (relative paths)
Quality indicator: Syntax errors detected

Phase 2 - Mermaid Validation:

16 diagrams across 9 files
100% valid diagram syntax
3 diagram types (graph, state, sequence)
Renderability verified at mermaid.live

Phase 3 - Korean Typography:

28,543 lines validated
43 Korean content files
100% UTF-8 encoding
Full-width character minimization

Phase 4 - Comprehensive Report:

Overall Quality Score: 8.5/10
Priority 1 (Critical): 0 items
Priority 2 (High): 2 items
Priority 3 (Low): 1 item

✅ Validation Checklist

5 validation scripts integrated
Project root auto-detection implemented
Command-line argument support added
CI/CD integration examples provided
Quality metrics documented
Usage patterns explained
Error handling implemented

Level 3: Advanced Patterns (Expert Reference)

Note: Advanced patterns for complex scenarios.

Coming soon: Deep dive into expert-level usage.

🎯 Best Practices Checklist

Must-Have:

✅ [Critical practice 1]
✅ [Critical practice 2]

Recommended:

✅ [Recommended practice 1]
✅ [Recommended practice 2]

Security:

🔒 [Security practice 1]

🔗 Context7 MCP Integration

When to Use Context7 for This Skill:

This skill benefits from Context7 when:

Working with [docs]
Need latest documentation
Verifying technical details

Example Usage:

# Fetch latest documentation
from moai_adk.integrations import Context7Helper

helper = Context7Helper()
docs = await helper.get_docs(
    library_id="/org/library",
    topic="docs",
    tokens=5000
)

Relevant Libraries:

Library	Context7 ID	Use Case
[Library 1]	`/org/lib1`	[When to use]

📊 Decision Tree

When to use moai-docs-unified:

Start
  ├─ Need docs?
  │   ├─ YES → Use this skill
  │   └─ NO → Consider alternatives
  └─ Complex scenario?
      ├─ YES → See Level 3
      └─ NO → Start with Level 1

🔄 Integration with Other Skills

Prerequisite Skills:

Skill("prerequisite-1") – [Why needed]

Complementary Skills:

Skill("complementary-1") – [How they work together]

Next Steps:

Skill("next-step-1") – [When to use after this]

📚 Official References

Metadata

skill_id: moai-docs-unified
skill_name: Unified Documentation Management & Quality Assurance
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 2200
triggers:
  - keywords: [documentation management, docs linting, mermaid validation, korean typography, documentation quality, comprehensive report, docs-unified]
  - contexts: [docs-unified, @docs:all, documentation-management, quality-assurance]
agents:
  - docs-manager
  - docs-auditor
  - quality-gate
freedom_level: high
context7_references:
  - url: "https://en.wikipedia.org/wiki/Software_quality"
    topic: "Software Quality Metrics"
  - url: "https://github.com/moai-adk/moai-adk"
    topic: "MoAI-ADK Documentation Standards"

📈 Version History

v4.0.0 (2025-11-12)

✨ Context7 MCP integration
✨ Progressive Disclosure structure
✨ 10+ code examples
✨ Primary/secondary agents defined
✨ Best practices checklist
✨ Decision tree
✨ Official references

Generated with: MoAI-ADK Skill Factory v4.0 Last Updated: 2025-11-12 Maintained by: Primary Agent (doc-syncer)

moai-docs-unified

Installation

Similar popular skills

Also in this package

Agent compatibility

Skill metadata

Package contents

History

SKILL.md

moai-docs-unified

📖 Progressive Disclosure

Level 1: Quick Reference (Core Concepts)

Section 1: Unified Framework Overview

Section 2: Script Specifications

Script 1: lintkoreandocs.py

Script 2: validatemermaiddiagrams.py

Script 3: extractmermaiddetails.py

Script 4: validatekoreantypography.py

Script 5: generatefinalcomprehensive_report.py

Section 3: Integration Patterns

Single Script Execution

Complete Validation Pipeline

Section 4: Project Root Auto-Detection

Section 5: CI/CD Integration

Section 6: Quality Metrics

Level 2: Practical Implementation (Common Patterns)

Section 1: Unified Framework Overview

Section 2: Script Specifications

Script 1: lintkoreandocs.py

Script 2: validatemermaiddiagrams.py

Script 3: extractmermaiddetails.py

Script 4: validatekoreantypography.py

Script 5: generatefinalcomprehensive_report.py

Section 3: Integration Patterns

Single Script Execution

Complete Validation Pipeline

Section 4: Project Root Auto-Detection

Section 5: CI/CD Integration

Section 6: Quality Metrics

Level 3: Advanced Patterns (Expert Reference)

🎯 Best Practices Checklist

🔗 Context7 MCP Integration

📊 Decision Tree

🔄 Integration with Other Skills

📚 Official References

📈 Version History