moai-docs-unified

modu-ai

Updated Today

22 views

424

Documentationdocumentation

About

This skill provides AI-enhanced documentation management by integrating specialized tools and agents. It uses Context7 MCP to ensure access to current documentation and supports operations like reading, searching, and fetching web content. Use it for unified documentation handling within CI/CD and testing workflows.

Quick Install

Claude Code

Recommended

Plugin CommandRecommended

/plugin add https://github.com/modu-ai/moai-adk

Git CloneAlternative

git clone https://github.com/modu-ai/moai-adk.git ~/.claude/skills/moai-docs-unified

Copy and paste this command in Claude Code to install this skill

Documentation

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: lint_korean_docs.py

Purpose: Comprehensive markdown validation for Korean documentation

Location: .claude/skills/moai-docs-unified/scripts/lint_korean_docs.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/lint_report_ko.txt (8 validation categories)

Script 2: validate_mermaid_diagrams.py

Purpose: Mermaid diagram type and syntax validation

Location: .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.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/mermaid_validation_report.txt (16 diagrams, 100% valid)

Script 3: extract_mermaid_details.py

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

Location: .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.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/mermaid_detail_report.txt (full diagram code + test guide)

Script 4: validate_korean_typography.py

Purpose: Korean-specific typography and encoding validation

Location: .claude/skills/moai-docs-unified/scripts/validate_korean_typography.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/korean_typography_report.txt (28,543 lines validated, 43 files)

Script 5: generate_final_comprehensive_report.py

Purpose: Aggregate all validation phases into prioritized quality report

Location: .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_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/korean_docs_comprehensive_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: lint_korean_docs.py

Purpose: Comprehensive markdown validation for Korean documentation

Location: .claude/skills/moai-docs-unified/scripts/lint_korean_docs.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/lint_report_ko.txt (8 validation categories)

Script 2: validate_mermaid_diagrams.py

Purpose: Mermaid diagram type and syntax validation

Location: .claude/skills/moai-docs-unified/scripts/validate_mermaid_diagrams.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/mermaid_validation_report.txt (16 diagrams, 100% valid)

Script 3: extract_mermaid_details.py

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

Location: .claude/skills/moai-docs-unified/scripts/extract_mermaid_details.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/mermaid_detail_report.txt (full diagram code + test guide)

Script 4: validate_korean_typography.py

Purpose: Korean-specific typography and encoding validation

Location: .claude/skills/moai-docs-unified/scripts/validate_korean_typography.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/korean_typography_report.txt (28,543 lines validated, 43 files)

Script 5: generate_final_comprehensive_report.py

Purpose: Aggregate all validation phases into prioritized quality report

Location: .claude/skills/moai-docs-unified/scripts/generate_final_comprehensive_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/korean_docs_comprehensive_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)

GitHub Repository

modu-ai/moai-adk

Path: .claude/skills/moai-docs-unified

agentic-aiagentic-codingagentic-workflowclaudeclaudecodevibe-coding

Related Skills

when-creating-presentations-use-pptx-generation

Other

This skill generates enterprise-grade PowerPoint presentations by enforcing structured workflows and design constraints. It produces accessible, professionally formatted decks with proper slide structure, notes, and WCAG compliance. Use it when you need automated generation of board decks, reports, or data-driven presentations.

View skill

when-creating-skill-template-use-skill-builder

Other

This Claude Skill helps developers create new Claude Code Skills with proper YAML frontmatter and directory structure. It generates all required files including documentation and ensures skills follow best practices. Use this template generator when building reusable skills to maintain specification compliance and progressive disclosure.

View skill

when-documenting-code-use-doc-generator

Report Writer

Other

The Report Writer skill generates professional reports from research and data, supporting technical, business, and academic styles. It structures input content with features like an optional table of contents and outputs formatted markdown. Use this skill to quickly transform raw findings into polished, audience-appropriate documentation.

View skill