Skip to main content
skill CX Codex

kpi-dashboard · datadrivenconstruction — Claude Code skill for KPI dashboards

kpi-dashboard is a Claude Code skill that builds KPI dashboards for construction projects. It tracks cost, schedule, quality, and safety metrics.

MIT 1 installs ★ 434 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill kpi-dashboard -a claude-code
Open on GitHub

What kpi-dashboard does

kpi-dashboard defines project KPIs and records each value with a date, status, and trend. Its standard set covers CPI and SPI, cost and schedule variance, defects, rework, safety, and labor productivity.

Each KPI has a target and warning and critical thresholds. The skill also allows custom KPI definitions, retrieves the latest recorded values, and provides a project summary. Trend calculations use recorded history and compare a new value with recent entries.

Python 3 and the pandas library are required.

What it helps with

  • track project costs and schedule performance
  • compare KPI values with targets and thresholds
  • record changes in quality and safety metrics
  • define custom project indicators

Example prompts for the agent

  • Build a construction project KPI dashboard covering CPI, SPI, quality, and safety.
  • Add a custom project KPI and set its status thresholds.
  • Record the latest KPI values and show the project summary.

How to install kpi-dashboard

1Skills CLI (Vercel)

npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill kpi-dashboard -a claude-code

2Manually: put the files in place

~/.claude/skills/kpi-dashboard/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/kpi-dashboard/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about kpi-dashboard

How do I install kpi-dashboard in Claude Code?

Run npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill kpi-dashboard -a claude-code. The skill file is located at ~/.claude/skills/kpi-dashboard/SKILL.md.

What does kpi-dashboard do?

It helps define and track construction project KPIs, record values, and calculate their status and trend.

What does kpi-dashboard require?

It requires Python 3 and the pandas library.

Source text

SKILL.md · MIT
---
name: "kpi-dashboard"
description: "Build KPI dashboards for construction projects. Track CPI, SPI, quality, safety metrics in real-time."
homepage: "https://datadrivenconstruction.io"
metadata: {"openclaw": {"emoji": "📈", "os": ["darwin", "linux", "win32"], "homepage": "https://datadrivenconstruction.io", "requires": {"bins": ["python3"]}}}
---
# KPI Dashboard Builder

## Business Case

### Problem Statement
Project monitoring challenges:
- Multiple metrics to track
- Data from various sources
- Real-time visibility needed
- Executive reporting

### Solution
Unified KPI dashboard system for construction projects with automated data collection, visualization, and alerting.

## Technical Implementation

```python
import pandas as pd
from typing import Dict, Any, List, Optional, Callable
from dataclasses import dataclass, field
from datetime import date, datetime
from enum import Enum


class KPICategory(Enum):
    COST = "cost"
    SCHEDULE = "schedule"
    QUALITY = "quality"
    SAFETY = "safety"
    PRODUCTIVITY = "productivity"
    SUSTAINABILITY = "sustainability"


class KPIStatus(Enum):
    ON_TARGET = "on_target"
    AT_RISK = "at_risk"
    CRITICAL = "critical"


class TrendDirection(Enum):
    IMPROVING = "improving"
    STABLE = "stable"
    DECLINING = "declining"


@dataclass
class KPIDefinition:
    kpi_id: str
    name: str
    category: KPICategory
    unit: str
    target: float
    warning_threshold: float
    critical_threshold: float
    higher_is_better: bool = True
    formula: str = ""


@dataclass
class KPIValue:
    kpi_id: str
    value: float
    date: date
    status: KPIStatus
    trend: TrendDirection


class KPIDashboard:
    """Build and manage KPI dashboards for construction projects."""

    def __init__(self, project_name: str):
        self.project_name = project_name
        self.kpis: Dict[str, KPIDefinition] = {}
        self.history: Dict[str, List[KPIValue]] = {}
        self._define_standard_kpis()

    def _define_standard_kpis(self):
        """Define standard construction KPIs."""

        standard_kpis = [
            # Cost KPIs
            KPIDefinition("CPI", "Cost Performance Index", KPICategory.COST,
                         "ratio", 1.0, 0.95, 0.90, True, "BCWP / ACWP"),
            KPIDefinition("CV", "Cost Variance", KPICategory.COST,
                         "$", 0, -50000, -100000, True, "BCWP - ACWP"),
            KPIDefinition("BUDGET_USED", "Budget Utilization", KPICategory.COST,
                         "%", 100, 105, 110, False),

            # Schedule KPIs
            KPIDefinition("SPI", "Schedule Performance Index", KPICategory.SCHEDULE,
                         "ratio", 1.0, 0.95, 0.90, True, "BCWP / BCWS"),
            KPIDefinition("SV", "Schedule Variance", KPICategory.SCHEDULE,
                         "days", 0, -7, -14, True),
            KPIDefinition("COMPLETION", "Project Completion", KPICategory.SCHEDULE,
                         "%", 100, 95, 90, True),

            # Quality KPIs
            KPIDefinition("DEFECT_RATE", "Defect Rate", KPICategory.QUALITY,
                         "per 1000 units", 0, 5, 10, False),
            KPIDefinition("FIRST_PASS", "First Pass Yield", KPICategory.QUALITY,
                         "%", 95, 90, 85, True),
            KPIDefinition("REWORK", "Rework Percentage", KPICategory.QUALITY,
                         "%", 0, 3, 5, False),

            # Safety KPIs
            KPIDefinition("TRIR", "Total Recordable Incident Rate", KPICategory.SAFETY,
                         "per 200k hours", 0, 2, 4, False),
            KPIDefinition("LOST_DAYS", "Lost Time Injuries", KPICategory.SAFETY,
                         "incidents", 0, 1, 3, False),
            KPIDefinition("SAFETY_OBSERVATIONS", "Safety Observations", KPICategory.SAFETY,
                         "count", 50, 30, 20, True),

            # Productivity KPIs
            KPIDefinition("LABOR_PROD", "Labor Productivity", KPICategory.PRODUCTIVITY,
                         "%", 100, 90, 80, True),
            KPIDefinition("EQUIP_UTIL", "Equipment Utilization", KPICategory.PRODUCTIVITY,
                         "%", 85, 70, 60, True),
        ]

        for kpi in standard_kpis:
            self.kpis[kpi.kpi_id] = kpi
            self.history[kpi.kpi_id] = []

    def add_custom_kpi(self, kpi: KPIDefinition):
        """Add custom KPI definition."""
        self.kpis[kpi.kpi_id] = kpi
        self.history[kpi.kpi_id] = []

    def record_value(self, kpi_id: str, value: float, record_date: date = None):
        """Record KPI value."""

        if kpi_id not in self.kpis:
            return

        kpi = self.kpis[kpi_id]
        record_date = record_date or date.today()

        # Calculate status
        status = self._calculate_status(kpi, value)

        # Calculate trend
        trend = self._calculate_trend(kpi_id, value)

        kpi_value = KPIValue(
            kpi_id=kpi_id,
            value=value,
            date=record_date,
            status=status,
            trend=trend
        )

        self.history[kpi_id].append(kpi_value)

    def _calculate_status(self, kpi: KPIDefinition, value: float) -> KPIStatus:
        """Calculate KPI status based on thresholds."""

        if kpi.higher_is_better:
            if value >= kpi.target:
                return KPIStatus.ON_TARGET
            elif value >= kpi.warning_threshold:
                return KPIStatus.AT_RISK
            else:
                return KPIStatus.CRITICAL
        else:
            if value <= kpi.target:
                return KPIStatus.ON_TARGET
            elif value <= kpi.warning_threshold:
                return KPIStatus.AT_RISK
            else:
                return KPIStatus.CRITICAL

    def _calculate_trend(self, kpi_id: str, current_value: float) -> TrendDirection:
        """Calculate trend direction."""

        history = self.history.get(kpi_id, [])
        if len(history) < 2:
            return TrendDirection.STABLE

        # Compare with average of last 3 values
        recent_values = [h.value for h in history[-3:]]
        avg = sum(recent_values) / len(recent_values)

        kpi = self.kpis[kpi_id]
        diff = current_value - avg

        if abs(diff) < avg * 0.05:  # Within 5%
            return TrendDirection.STABLE
        elif (diff > 0 and kpi.higher_is_better) or (diff < 0 and not kpi.higher_is_better):
            return TrendDirection.IMPROVING
        else:
            return TrendDirection.DECLINING

    def get_current_values(self) -> Dict[str, KPIValue]:
        """Get most recent value for each KPI."""

        current = {}
        for kpi_id, history in self.history.items():
            if history:
                current[kpi_id] = history[-1]
        return current

    def get_dashboard_summary(self) -> Dict[str, Any]:
        """Get dashboard summary."""

        current = self.get_current_values()

        summary = {
            'project': self.project_name,
            'date': date.today().isoformat(),
            'total_kpis': len(self.kpis),
            'by_status': {s.value: 0 for s in KPIStatus},
            'by_category': {},
            'alerts': []
        }

        for kpi_id, value in current.items():
            summary['by_status'][value.status.value] += 1

            category = self.kpis[kpi_id].category.value
            if category not in summary['by_category']:
                summary['by_category'][category] = {'on_target': 0, 'at_risk': 0, 'critical': 0}
            summary['by_category'][category][value.status.value] += 1

            if value.status == KPIStatus.CRITICAL:
                summary['alerts'].append({
                    'kpi': self.kpis[kpi_id].name,
                    'value': value.value,
                    'target': self.kpis[kpi_id].target,
                    'status': 'critical'
                })

        return summary

    def get_kpi_details(self, kpi_id: str) -> Dict[str, Any]:
        """Get detailed KPI information."""

        if kpi_id not in self.kpis:
            return {}

        kpi = self.kpis[kpi_id]
        history = self.history.get(kpi_id, [])

        return {
            'definition': {
                'id': kpi.kpi_id,
                'name': kpi.name,
                'category': kpi.category.value,
                'unit': kpi.unit,
                'target': kpi.target,
                'formula': kpi.formula
            },
            'current': {
                'value': history[-1].value if history else None,
                'status': history[-1].status.value if history else None,
                'trend': history[-1].trend.value if history else None
            },
            'history': [
                {'date': h.date.isoformat(), 'value': h.value, 'status': h.status.value}
                for h in history
            ]
        }

    def generate_html_dashboard(self) -> str:
        """Generate HTML dashboard."""

        summary = self.get_dashboard_summary()
        current = self.get_current_values()

        html = f"""
<!DOCTYPE html>
<html>
<head>
    <title>KPI Dashboard - {self.project_name}</title>
    <style>
        body {{ font-family: Arial, sans-serif; margin: 20px; }}
        .header {{ background: #2196F3; color: white; padding: 20px; margin-bottom: 20px; }}
        .kpi-grid {{ display: grid; grid-template-columns: repeat(4, 1fr); gap: 15px; }}
        .kpi-card {{ border: 1px solid #ddd; padding: 15px; border-radius: 5px; }}
        .on_target {{ border-left: 4px solid #4CAF50; }}
        .at_risk {{ border-left: 4px solid #FF9800; }}
        .critical {{ border-left: 4px solid #F44336; }}
        .kpi-value {{ font-size: 24px; font-weight: bold; }}
        .kpi-name {{ color: #666; font-size: 14px; }}
    </style>
</head>
<body>
    <div class="header">
        <h1>{self.project_name} - KPI Dashboard</h1>
        <p>Last updated: {summary['date']}</p>
    </div>
    <div class="kpi-grid">
"""

        for kpi_id, value in current.items():
            kpi = self.kpis[kpi_id]
            html += f"""
        <div class="kpi-card {value.status.value}">
            <div class="kpi-name">{kpi.name}</div>
            <div class="kpi-value">{value.value:.2f} {kpi.unit}</div>
            <div>Target: {kpi.target} | Trend: {value.trend.value}</div>
        </div>
"""

        html += "</div></body></html>"
        return html

    def export_to_excel(self, output_path: str) -> str:
        """Export dashboard to Excel."""

        with pd.ExcelWriter(output_path, engine='openpyxl') as writer:
            # Summary
            summary = self.get_dashboard_summary()
            summary_df = pd.DataFrame([{
                'Project': summary['project'],
                'Date': summary['date'],
                'On Target': summary['by_status']['on_target'],
                'At Risk': summary['by_status']['at_risk'],
                'Critical': summary['by_status']['critical']
            }])
            summary_df.to_excel(writer, sheet_name='Summary', index=False)

            # Current values
            current = self.get_current_values()
            current_data = []
            for kpi_id, value in current.items():
                kpi = self.kpis[kpi_id]
                current_data.append({
                    'KPI': kpi.name,
                    'Category': kpi.category.value,
                    'Value': value.value,
                    'Unit': kpi.unit,
                    'Target': kpi.target,
                    'Status': value.status.value,
                    'Trend': value.trend.value
                })
            current_df = pd.DataFrame(current_data)
            current_df.to_excel(writer, sheet_name='Current KPIs', index=False)

        return output_path
```

## Quick Start

```python
# Create dashboard
dashboard = KPIDashboard("Office Building A")

# Record KPI values
dashboard.record_value("CPI", 0.95)
dashboard.record_value("SPI", 1.02)
dashboard.record_value("DEFECT_RATE", 3.5)
dashboard.record_value("TRIR", 1.8)
dashboard.record_value("LABOR_PROD", 92)

# Get summary
summary = dashboard.get_dashboard_summary()
print(f"On Target: {summary['by_status']['on_target']}")
print(f"Critical: {summary['by_status']['critical']}")
```

## Common Use Cases

### 1. HTML Dashboard
```python
html = dashboard.generate_html_dashboard()
with open("dashboard.html", "w") as f:
    f.write(html)
```

### 2. KPI Details
```python
details = dashboard.get_kpi_details("CPI")
print(f"Current CPI: {details['current']['value']}")
```

### 3. Custom KPI
```python
dashboard.add_custom_kpi(KPIDefinition(
    "WASTE_DIVERSION", "Waste Diversion Rate",
    KPICategory.SUSTAINABILITY, "%", 75, 60, 50, True
))
```

## Resources
- **DDC Book**: Chapter 4.1 - Data Analytics and Decision Making
- **Website**: https://datadrivenconstruction.io

© datadrivenconstruction · MIT · datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction

Similar skills

All skills for Data and databases →

kpi-dashboard by other authors comes first.

kpi-dashboard genspark-ai Builds an Excel KPI dashboard from operating data, with definitions, targets, actuals, attainment and trend charts. Useful for recurring metric reviews. CX Codex +1 ★ 12,746repo stars kpi-dashboard-design Seth Hobson The kpi-dashboard-design skill helps design KPI dashboards, choose useful metrics, and trace conflicting calculations. Use it for SaaS, operations, and cohort analysis views. CX Codex +1 16,141installs consumer-goods-tpe-dashboard-custom-kpi-configure forcedotcom consumer-goods-tpe-dashboard-custom-kpi-configure is a Claude Code skill that clones TPE Analytics parameters, measurements, and dashboards for customer KPIs. It supports custom KPI setup for Promotion Analysis and Tactic Analysis. CX Codex +1 324installs dashboard-creator mhattingpete dashboard-creator builds a single-page HTML dashboard with KPI cards, charts, progress bars and data tables. Handy when you need to show metrics without a frontend framework. CX Codex +1 337installs exec-dashboard-blueprint gtmagents exec-dashboard-blueprint is a Claude Code skill for structuring board-ready marketing dashboards around a Story Arc. It organizes /marketing-analytics output into KPIs, risks, and actions with owners and due dates. CX Codex +1 ★ 450repo stars build-exec-dashboard gtmagents build-exec-dashboard turns flags for audience, KPIs, cadence and format into an executive dashboard spec, with a rollout kit attached. CX Codex +1 ★ 450repo stars dashboard-design Otabek Abdiraimov dashboard-design is a Claude Code plugin for building KPI dashboards, charts, and heatmaps. It checks the finished screen from a screenshot. ★ 1,073repo stars

From the same set156

The whole set →
clash-detection-analysis clash-detection-analysis detects geometric clashes between IFC BIM elements, identifying physical intersections and clearance violations before construction starts. CX Codex +1 115installs scenario-planner scenario-planner models construction scenarios and compares options by cost, schedule, and resources. Helps you see what happens if you double the crew or compress the timeline. CX Codex +1 115installs ontology-mapper ontology-mapper maps construction data elements to standard schemas like IFC, COBie, and Uniclass for cross-system semantic consistency. CX Codex +1 115installs json-parser json-parser is a skill that parses and checks JSON from construction APIs, IoT sensors, and BIM exports, turning nested records into tables for structured-data projects. CX Codex +1 115installs weather-api weather-api is a Claude Code skill that retrieves weather forecasts and historical data and assesses conditions for construction work. It supports scheduling outdoor tasks. CX Codex +1 115installs capacity-planning capacity-planning forecasts staffing demand and identifies workforce gaps across construction projects. Helps evaluate capacity before pursuing new bids. CX Codex +1 115installs cwicr-location-factor cwicr-location-factor is a Claude Code skill that applies regional labor, material, and equipment factors to CWICR estimates. Compare project costs across regions. CX Codex +1 115installs email-construction email-construction generates structured construction emails: RFI responses, submittal transmittals, change order notices, and meeting invites. CX Codex +1 115installs

Project sponsors

Companies that keep this analytics open