Moai Docs Unified

moai-docs-unified

Enhanced docs unified with AI-powered features. Enhanced with Context7 MCP for up-to-date documentation.

mattnigh/skills_collection·0installs24stars

SKILL.md

Full skill instructions

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)

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/mattnigh/skills_collection --skill dolsoon__my-awesome-project__claude__skills__moai-docs-unified__SKILL.md

View on GitHub

collection/dolsoon__my-awesome-project__claude__skills__moai-docs-unified__SKILL.md

frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications, OR when they provide screenshots/images/designs to replicate or draw inspiration from. For screenshot inputs, extracts design guide...
1 installs
animation-motion
CSS animations, transitions, and scroll-driven effects with accessibility (prefers-reduced-motion). Use when adding motion, hover effects, loading states, or scroll-based animations.
1 installs
laravel
Laravel v12 - The PHP Framework For Web Artisans
1 installs
gemini-document-processing
Guide for implementing Google Gemini API document processing - analyze PDFs with native vision to extract text, images, diagrams, charts, and tables. Use when processing documents, extracting structured data, summarizing PDFs, answering questions about document content, or converting documents to...
0 installs