---

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:

• 📄 Document Structure - Complete section templates with docx-js code
• 🎨 Design System - Full color palette, typography, spacing
• 📊 Table Templates - Pre-built table layouts for each section
• 🔍 Finding Cards - Individual finding presentation format

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