ad-assessment-documents

gilberth 的头像作者 gilberth

Active Directory健康评估的专业文档生成器。创建具有一致品牌、适当的数据可视化、基于严重性的格式化和可操作修复指南的行政级DOCX报告。在从OpsIdentity JSON数据生成评估报告或提高文档输出质量时使用。

📖 中文导读:Active Directory健康评估的专业文档生成器。创建具有一致品牌、适当的数据可视化、基于严重性的格式化和可操作修复指南的行政级DOCX报告。在从OpsIdentity JSON数据生成评估报告或提高文档输出质量时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: ad-assessment-documents description: Professional document generator for Active Directory health assessments. Creates executive-quality DOCX reports with consistent branding, proper data visualization, severity-based formatting, and actionable remediation guidance. Use when generating assessment reports from OpsIdentity JSON data or improving document output quality.

AD Assessment Document Generator Skill

Generate professional, executive-ready DOCX assessment reports from Active Directory health data.

"The document should look like it came from a Big 4 consulting firm, not a script output."

When to Use This Skill

Trigger Action
"Generate assessment document" Load 📄 Document Structure
"Improve report formatting" Check 🎨 Design System
"Fix table layouts" Reference 📊 Table Templates
"Format findings section" Use 🔍 Finding Cards

Design Philosophy

Professional Standards

Principle Implementation
Executive First Lead with business impact, technical details follow
Visual Hierarchy Score card → Summary table → Detailed findings
Actionable Every finding includes copy-paste remediation
Consistent Same styling throughout, no visual surprises
Error-Free Never show undefined, null, or [object Object]

Color Palette (Severity-Based)

Severity Fill Color Text Color Usage
Critical #FEE2E2 #991B1B Red badge, immediate action
High #FEF3C7 #92400E Orange badge, priority action
Medium #FEF9C3 #854D0E Yellow badge, scheduled action
Low #DBEAFE #1E40AF Blue badge, optimization
Info #F3F4F6 #374151 Gray badge, informational
Success #D1FAE5 #065F46 Green badge, compliant

Typography System

Font Family: Arial (universal compatibility)

Title:           28pt, Bold, #1E3A5F (Navy)
Heading 1:       18pt, Bold, #1E3A5F
Heading 2:       14pt, Bold, #374151 (Gray-700)
Heading 3:       12pt, Bold, #4B5563 (Gray-600)
Body:            11pt, Regular, #111827 (Gray-900)
Caption:         9pt, Regular, #6B7280 (Gray-500)
Code:            10pt, Consolas, #1F2937, Background #F3F4F6

Document Structure

Required Sections (In Order)

  1. Cover Page

    • Logo placeholder (centered)
    • Document title: "Active Directory Health Assessment"
    • Subtitle: "Security and Configuration Report"
    • Client domain name (prominent)
    • Assessment date
    • Confidentiality notice
  2. Executive Summary (1 page max)

    • Health score gauge (0-100)
    • Risk distribution chart (text-based)
    • Top 3-5 critical findings (bullet summary)
    • Immediate action items
  3. Environment Overview

    • Forest/Domain properties table
    • Domain Controllers status table
    • FSMO roles health table
    • Sites and subnets summary
  4. Findings by Category

    • Grouped by: Critical → High → Medium → Low
    • Each finding uses the Finding Card template
    • Include affected objects count
  5. Detailed Remediation

    • Step-by-step instructions
    • PowerShell commands (properly formatted)
    • Validation steps
    • External documentation links
  6. Appendices

    • Full affected objects lists
    • Technical metrics raw data
    • Glossary of terms

Data Validation Rules

CRITICAL: Never Output These

// Before generating any field, validate:
if (value === undefined || value === null || value === '') {
  return 'No disponible';  // Or appropriate default
}
if (typeof value === 'object' && !Array.isArray(value)) {
  return JSON.stringify(value);  // Or extract specific field
}
if (value === 'undefined ms' || value === 'undefined') {
  return 'N/A';
}

Health Score Calculation

// Score should NEVER be 0 if systems are operational
function calculateHealthScore(findings) {
  let score = 100;
  
  findings.forEach(f => {
    switch(f.severity) {
      case 'CRITICAL': score -= 15; break;
      case 'HIGH': score -= 10; break;
      case 'MEDIUM': score -= 5; break;
      case 'LOW': score -= 2; break;
    }
  });
  
  return Math.max(0, score);  // Floor at 0
}

Quick Reference: docx-js Patterns

Severity Badge Cell

function createSeverityCell(severity) {
  const colors = {
    'CRITICAL': { fill: 'FEE2E2', text: '991B1B' },
    'HIGH': { fill: 'FEF3C7', text: '92400E' },
    'MEDIUM': { fill: 'FEF9C3', text: '854D0E' },
    'LOW': { fill: 'DBEAFE', text: '1E40AF' }
  };
  const c = colors[severity] || colors['LOW'];
  
  return new TableCell({
    shading: { fill: c.fill, type: ShadingType.CLEAR },
    children: [new Paragraph({
      alignment: AlignmentType.CENTER,
      children: [new TextRun({ 
        text: severity, 
        bold: true, 
        color: c.text,
        size: 20 
      })]
    })]
  });
}

Code Block Paragraph

function createCodeBlock(code) {
  return new Paragraph({
    shading: { fill: 'F3F4F6', type: ShadingType.CLEAR },
    spacing: { before: 120, after: 120 },
    indent: { left: 360, right: 360 },
    children: [new TextRun({
      text: code,
      font: 'Consolas',
      size: 20,
      color: '1F2937'
    })]
  });
}

Reference Files

Load these for specific implementation details:

Anti-Patterns to Avoid

❌ Don't ✅ Do Instead
Show [object Object] Extract specific property or stringify
Use undefined in tables Use "N/A" or "No disponible"
Mix languages randomly Consistent Spanish or English throughout
Escape PowerShell chars (\$) Use raw code, handle escaping in generation
"Ver detalles en otra sección" Include details inline or specific page ref
Score of 0 with operational DCs Calculate proper weighted score
Inconsistent table widths Use fixed column width templates
Unicode bullets in lists Use proper docx-js numbering config

Version History

Version Date Changes
1.0.0 2025-12-27 Initial skill creation